A desktop pet runtime for AI coding tools. The pet reacts to what your AI tool is doing — running tasks, waiting for input, finishing up, or hitting errors.
Windows builds are in GitHub Releases.
Coding-Pet-<version>-x64.exe— portable installerCoding-Pet-<version>-x64.zip— unpacked application
Mac and Linux build scripts are included (dist:mac, dist:linux) but have not been verified on real hardware. Community feedback welcome.
Windows:
npm run install:desktop
npm run dev:desktopMac / Linux:
npm run install:desktop
npm run start:unixThe pet window appears immediately — no configuration needed.
Open the ⚙ → Plugins tab to install a bridge with one click.
| Tool | Mechanism | Config file |
|---|---|---|
| Claude Code | Hooks (PreToolUse / Stop / …) | ~/.claude/settings.json |
| Gemini CLI | Hooks (before_tool / after_agent / …) | ~/.gemini/settings.json |
| Qwen Code | Hooks (same naming as Claude Code) | ~/.qwen/settings.json |
| OpenCode | Plugin SDK | ~/.config/opencode/plugins/ |
Multiple tools can be active at once — the pet follows the one that last wrote a state file. Use the Source tab to lock a window to a specific tool.
Hover over the pet and click ⚙ to open the selector. All pets found in configured discovery sources appear as cards. Click to switch; the choice persists across restarts.
The pet reads a JSON snapshot and plays the matching animation:
{
"state": "running",
"title": "Working",
"body": "Editing src/index.ts"
}Available states: idle, running, waiting, failed, review, waving, jumping, running-left, running-right.
Write the snapshot to any path, add it to stateFiles in config.json, and the pet polls it every second. See Integrating with other tools.
apps/desktop/config.json — only edit if you need to change defaults:
{
"petDir": "",
"petFormat": "codex-pet-v1",
"adapter": "file",
"stateFiles": [
"~/.coding-pet/claude-code-state.json",
"~/.coding-pet/gemini-cli-state.json",
"~/.coding-pet/qwen-code-state.json"
],
"discoverySources": ["./sample-data", "~/.codex/pets"],
"window": { "width": 280, "height": 320, "alwaysOnTop": true }
}~ expands to your home directory. Changes take effect on next launch.
| Package | Description |
|---|---|
| apps/desktop | Electron desktop shell |
| packages/runtime-core | Types, plugin API, animation engine (TypeScript) |
| packages/codex-pet-adapter | Loads codex-pet-v1 pet packages |
| packages/claude-code-host-bridge | Claude Code hooks bridge |
| packages/gemini-cli-host-bridge | Gemini CLI hooks bridge |
| packages/qwen-code-host-bridge | Qwen Code hooks bridge |
| packages/opencode-host-bridge | OpenCode plugin bridge |
npm run build:desktop # Windows
npm run build:desktop:mac # macOS
npm run build:desktop:linux # LinuxOutput goes to apps/desktop/release/.
Run tests across all packages:
npm testRun the desktop in dev mode:
npm run dev:desktop