tokiepet 0.1.0

A pixel desktop pet that feeds on Claude Code tokens, walks on top of your windows, and falls when you move them.

tokie

A pixel desktop pet that lives on top of your windows, walks across the edges of your terminal / browser / IDE, and slowly grows fatter on the tokens you've spent in Claude Code.

macOS only (uses Cocoa + Quartz for the click-through overlay).

Install (one-liner)

pip install git+https://github.com/Andersonscat/tokiepet.git

Then:

tokie start

That's it — the pet will start walking on top of your windows. Requires macOS 11+ and Python 3.9+. Dependencies (PyObjC) are installed automatically.

A PyPI release under the name tokiepet is planned (the bare tokie name is squatted by an unrelated tokenizer). Once published, the one-liner will simplify to pip install tokiepet. The CLI command and Python import are both tokie either way.

From source (for development)

git clone https://github.com/Andersonscat/tokiepet
cd tokiepet
pip install -e .

Uninstall

tokie stop
pip uninstall tokiepet
rm -rf ~/.tokie

Run

tokie            # foreground — Ctrl-C to quit
tokie start      # detach into the background
tokie stop       # kill any running instance
tokie status     # show pid + uptime

You can also run as a module:

python -m tokie

What he does

• Walks along the top edges of any window on screen — terminal, browser, finder, IDE — and falls with gravity when you move that window out from under him.
• Eats whenever Claude spends tokens in ~/.claude/projects/**/*.jsonl. Different food (berries / cookies / sushi / cake) per token type (input / output / cache read / cache write). Fatter when you've been coding a lot.
• Sleeps in a curl when he hasn't been fed in a while. Place a doghouse near him for a nicer nap.
• Lounges spontaneously when idle — lies down on his side, eyes open, tail flicking.
• Roasts marshmallows if you put a placed campfire next to him. Six-second roast cycle with browning marshmallow, then he eats it.
• Plays Pixel Smash — there's a built-in catapult + block-tower mini-game (toolkit in inventory → Games).
• Falls with a parachute if you drop him from a serious height.

Interactions

• Hover over him with the cursor — eyes track, you can pet him by waving over his body, hearts spawn.
• Drag him anywhere with the mouse.
• Click him to toggle the stats dashboard (Health, Hunger, Joy, Energy, XP, token totals).
• Inventory lives in a small chest button — drag out a stick (he fetches), catapult, doghouse, fan, campfire, build pieces, or pet-card.
• Pet card opens his profile — click the name to rename him, toggle behaviour settings, see stats.

State & data

All state is stored in ~/.tokie/state.json. Token data is read from ~/.claude/projects/**/*.jsonl — Tokie never sends anything anywhere.

If you previously had ~/claude-pet/state.json from an older install, it's auto-migrated on first run.

Requirements

• macOS 11+ (relies on pyobjc-framework-Cocoa 12+; older PyObjC 10.x segfaults when rendering borderless overlays).
• Python 3.9+
• A copy of Claude Code is optional — Tokie still works without any tokens to eat, he just won't grow.

Status

Single-author hobby project. macOS only for now; Windows/Linux would need a different overlay backend (Qt/Tauri). Contributions welcome.

License

MIT