session-pet

#Install

One installer covers both platforms. Inside a clone it builds from source; outside a clone it downloads a prebuilt binary from the latest GitHub release. Pick your platform:

$ git clone https://github.com/chud-lori/session-pet.git
$ cd session-pet
$ ./install.sh --login-item   # build, run, and start at every login

$ curl -fsSL https://raw.githubusercontent.com/chud-lori/session-pet/main/install.sh | sh

$ git clone https://github.com/chud-lori/session-pet.git
$ cd session-pet
$ ./install.sh --autostart    # build, run, and start at every login

$ curl -fsSL https://raw.githubusercontent.com/chud-lori/session-pet/main/install.sh | sh

#The five session phases

Both providers are normalized into one set of phases, and the phase is what the pet's posture, its status dots and the panel cards all report. Pick a phase to see what it looks like on screen.

Status dots appear under the pet once two or more sessions are live, so one glance counts how many are working, finished, or waiting on you.

#Using the pet

The pet is a frameless always-on-top window with true per-pixel transparency, so clicks land only on its opaque pixels and pass through everywhere else.

Sounds

A quiet chime when a turn finishes, and a louder double ping when an agent needs you. The two have separate debounce clocks, so an urgent ping is never swallowed by a chime that just played. On macOS the defaults are the system Glass.aiff and Ping.aiff played through afplay; on Linux they are the freedesktop .oga theme sounds played through the first available of paplay, pw-play or ffplay. Both are replaceable, see configuration.

Muted, the pet still jumps on every alert and keeps a small reminder hop going with a "!" badge until you acknowledge it, because motion works when sound cannot.

Wandering

The pet takes short strolls along your screen with a walk cycle, never while something needs your attention and never while the panel is open. Sprite packs can ship hand-drawn walk frames; packs without them get an automatic two-frame leg shuffle. Turn it off in panel settings.

Jump to terminal

Clicking a session card raises the terminal running it, with no hook and no shell integration: the agent process is found in the process list and its parent chain is walked to the first GUI application. How precisely it lands depends on what that application exposes.

#Command reference

The pet helper

Works from anywhere inside the repository, on both platforms.

$ ./pet          # start, or bring it back after quitting
$ ./pet stop     # quit, the same as right-click then Quit
$ ./pet status   # is it running?

Installer

Running the binaries directly

The statusline pet (legacy)

pet.py renders a tiny pet inside the Claude Code statusline and shares XP, species and name with the desktop pet through .state/state.json. It is kept for compatibility; the native pets replaced it on both platforms, and pet_window.py, the original Tkinter window, is deprecated.

$ python3 pet.py species              # list species, current one marked
$ python3 pet.py set species dragon   # pick your pet
$ python3 pet.py set name Smaug       # rename it
$ python3 pet.py status               # XP and stage outside the statusline

#Configuration

Environment variables

Keys in .state/state.json

The same file on both platforms. Species, name and the toggles are normally set from the panel; the sound keys have no UI and are edited by hand.

A missing or unplayable sound file falls back to the platform default silently. For a pack that works on both platforms use .wav or .mp3: .aiff is unreliable on the Linux players, and afplay cannot play .oga.

Sprite packs

Drop a JSON file into sprites/, one species per file, picked up at the next launch and added to the picker. No rebuild, no export step. The species key is the filename stem, and a pack whose key matches a built-in replaces that sprite. Malformed files are skipped rather than fatal. sprites/example-slime.json ships as a working template.

{"name": "Slimey", "emoji": "🧼",
 "palette": {"X": "#7ee8a2", "k": "#2f4a33"},
 "rows": ["....kkkk....", "...kXXXXk..."]}

Rows are pixel strings and each character is a palette key. . is transparent; o, w and g are eye pixels, which the pet redraws as X while blinking, so use X for the main body color. Built-in sprites are 16 pixels wide and wider maps scale down to that footprint. An optional walk key holds an array of frames in the same shape as rows. Built-in sprites live in native/assets.json, the source of truth for both platforms.

Permission-prompt alerts (optional)

Claude Code permission prompts leave no trace in the transcript, so the pet cannot see them by reading files alone. This hook closes that gap. Merge it into ~/.claude/settings.json under "hooks" yourself, with the path pointing at your clone; the installer never edits your settings. It needs jq.

"Notification": [{"hooks": [{"type": "command", "async": true,
  "command": "jq -c . >> /path/to/session-pet/.state/events.jsonl"}]}]

The hook runs asynchronously and appends one JSON line per notification; the pet truncates that log itself so it cannot grow unbounded. Without the hook everything else still works, and permission prompts surface as stalled after a grace period instead of as an instant ping.

#How a phase is decided

No SDK and no daemon inside your agents. The pet reads the transcript files the agents already write: Claude Code's ~/.claude/projects/*.jsonl and Codex's ~/.codex/sessions/**/rollout-*.jsonl.

• It tails, it does not read. Every couple of seconds only the last 64 KB of each recent transcript is read, growing once to 512 KB when no decisive event is in that window, with lossy UTF-8 decoding so a byte split across the chunk boundary can never nil the whole tail. Gigabyte-long sessions cost almost nothing.
• Turn-end comes from the transcript, not the clock. A session is finished only when its last assistant event says so: stop_reason: end_turn for Claude Code, task_complete for Codex. A long tool run or a thinking pause never counts as done.
• An end_turn is not always the end of a turn. A blocking Stop hook, or a queued message, continues the conversation seconds later. The scanner holds a short confirmation window and watches for the hook-feedback event that follows, so intermediate turn-ends stay silent and you get one ding, at the real end.
• Subagents count as work. They write under <session-id>/subagents/**, where the parent transcript looks idle while the session is not, so their activity folds into the parent.
• A quiet session stays listed while its terminal is open, which is read from the process list rather than guessed from the transcript.

You can watch the classifier work. ./test/run.sh stages the fixture transcripts in test/fixtures/ under an isolated fake home and runs one scan. Two of the six lines from a real run on this repository, with the absolute repository prefix shortened to .../:

$ SESSION_PET_HOME=test/home ./native/SessionPet --scan-once
{"doing":"needs your answer","phase":"input","path":".../test/home/.claude/projects/p1/ask-user.jsonl","label":"/Users/test/proj"}
{"doing":"1 subagent working…","phase":"working","path":".../test/home/.claude/projects/p1/subagent-parent.jsonl","label":"/Users/test/proj"}

The fixtures cover the cases that cost real debugging: a turn-end, an AskUserQuestion, a transcript line over 70 KB, a meta user event that must not read as a new turn, a Codex rollout, and a parent whose subagent is still running.

#XP, stages and species

Every session that finishes a turn banks 5 XP into the shared pool, and XP is what moves the pet through its stages. Nothing else feeds it: there are no streaks, quests or currencies.

Before the pet hatches, the panel's XP line reads egg · pick a sprite in settings to hatch! rather than showing an empty bar. Once an evolved form is unlocked, an evolution dropdown appears in settings so you can roll back to an earlier form.

Species

Eleven species ship in the picker: cat, dragon, crab, octopus, dino, agumon, pudge, mario, fox, alien and turtle. The egg is a stage rather than a choice, and greymon is agumon's evolved form, earned at the adult stage rather than picked. Three of the sprites below are rendered straight from the pixel maps in native/assets.json, the same file the apps read.

#What it will not do

Kept deliberately out of scope, so the pet stays small:

• No support for a long list of providers. Claude Code and Codex only.
• No approving or denying permission prompts from the pet. It notifies, you act in the terminal.
• No chatting with an agent from the pet window.
• No menu-bar or notch rewrite. It stays a floating desktop pet.
• No further gamification. XP, stages and species are the ceiling.

The rule behind the sounds: any false needs-input or ready ding is release-blocking. A false working is tolerable, but it has to be time-bounded, which is what the stalled phase exists for.

#Questions