Pixel-art desktop pets that react to your Claude Code sessions. Clawd (the crab) tracks your first open chat and a blue cube tracks the second. Each buddy glows and shows a label as its session changes state: idle, thinking, working, done, or waiting on you.
Drag a buddy to move it. Right-click either one to quit both.
- Python 3 with Tkinter (ships with the standard macOS/Windows Python installers;
on Linux install
python3-tk)
./start_buddy.sh # launch in the background (survives closing the terminal)Logs go to /tmp/claude_buddy.log. To stop, right-click a buddy.
Claude Code hooks call set_state.sh <state> on session events, which updates a
small state file that buddy.py polls:
idle | thinking | working | done | question | end
Wire it up in your Claude Code settings.json hooks so ensure_buddy.sh runs on
SessionStart (idempotent, relaunches if it crashed) and set_state.sh runs on
the state-changing events.
| File | Purpose |
|---|---|
buddy.py |
The two-pet renderer (Clawd + cube) |
shimeji.py |
Standalone single-pet variant |
set_state.py |
Maps a Claude Code hook payload to the right buddy |
set_state.sh |
Hook entry point: set_state.sh <state> |
start_buddy.sh |
Launch the buddies in the background |
ensure_buddy.sh |
Idempotent launcher for SessionStart |