Agent Pets

🪴 A fun side project (unfinished). I built this as a playful way to give Claude Code sessions their own on-screen pets — the way Codex has its little companion. It never got fully finished; I'll likely come back to it down the line (if Fable returns, or with GPT 5.6) when I have the time.

A native macOS companion that gives every coding-agent session its own animated pixel-art pet. Each pet lives on top of your desktop and reflects what its session is doing — idle, coding, researching, waiting on you, done, blocked, or errored — through sprite animation, glow, and optional sound. Ambient, glanceable status for multiple Claude Code or Codex sessions without switching windows.

What it does

• One draggable pet per active session, always on top, across multiple monitors.
• Eight live states driven by the agent's own lifecycle hooks — the pet animates as the session works.
• A menu-bar dashboard to name pets, pick appearances, set scale, and toggle sound per pet or globally.
• A 12-creature pixel roster (fox, wolf, bear, deer, rabbit, boar, parrot, slime, mushroom, eye, ice spirit, robot), all CC0 art.
• A local HTTP API and agent-pets CLI for scripting, plus an MCP server so agents can set their own status.
• AgentPets Village — a standalone, Animal Crossing-inspired browser game starring the same creature roster. Launches on its own, no pets (or macOS) required: ./Game/play.sh.
• AgentPets Village 2 — the comprehensive sequel on Burrow, a from-scratch Rust→WASM game engine (zero dependencies): museum, villager schedules, weather, planting, town building. ./Game2/play.sh.

Everything runs locally. No network calls leave your machine; the only socket is a loopback API on 127.0.0.1:47771.

Requirements

• macOS 14 (Sonoma) or newer
• Swift 5.9+ toolchain (Xcode or Command Line Tools)
• Python 3 + Pillow, only if you want to re-slice sprite sheets

Build

swift build            # builds all targets
swift test             # runs the AgentPetsCore unit suite

Targets:

Target	Product	Role
AgentPetsCore	library	pure state/logic, unit-tested
AgentPets	app	the on-screen overlay + menu-bar dashboard
AgentPetsCLI	agent-pets	spawn/set/scale/list pets, install hooks
AgentPetsMCP	agent-pets-mcp	stdio MCP server (set_status, set_pet)

Run

# start the overlay app
swift run AgentPets

# install the Claude Code hooks (idempotent — safe to re-run)
agent-pets install-hooks

# manual smoke
agent-pets spawn --session demo --pet fox
agent-pets set --session demo --state coding

install-hooks copies the CLI to a stable location and points your Claude Code hooks at that copy, so moving or rebuilding this project does not break the integration. Re-run agent-pets install-hooks after a swift build if you want the installed copy refreshed.

How state is detected

Claude Code pre-tool / post-tool / stop hooks call agent-pets hook, which maps tool activity to a pet state via AgentStateMapper. Codex sessions use a coarser hook plus the MCP server, where the agent can set its own status directly. A done-linger monitor keeps a pet in its "done" state for a configurable window, and long-running work is detected and surfaced as its own state.

Configuration

• Global config: ~/Library/Application Support/AgentPets/config.json
• Per-project overrides: .agentpets.json in a project root
• Pet positions persist across launches and snap to monitors.

AgentPets Village 1 & 2 (standalone games)

The repo also ships AgentPets Village, a cozy Animal Crossing-inspired life sim that reuses the pet roster as its villager cast. It is completely independent of the overlay app — plain HTML5/JS, no build step, works on any OS:

./Game/play.sh                          # v1 (vanilla JS): serve + open browser
node --test "Game/tests/*.test.mjs"     # v1 test suite (Node 18+)

./Game2/play.sh                         # v2 (Rust → WASM on the Burrow engine)
cd Game2 && cargo test                  # v2 native test suite (73 tests)
node --test "Game2/tests-node/*.test.mjs"  # headless sessions vs the real wasm

Fish, catch bugs, dig fossils, befriend the villagers, pay off your loan to a robot bank, and decorate your house — on a real-time clock with real seasons. Village 2 adds a museum with donations and fossil assessment, villager daily schedules with pathfinding, weather, planting and tree-chopping, paths and outdoor decoration, and seasonal events — all on Burrow, a from-scratch Rust game engine compiled to WebAssembly with a hand-rolled zero-import ABI (no wasm-bindgen, no crates at all).

Sprites

Pixel art is data-driven. scripts/slice_sprites.py slices CC0 sprite packs into square-padded PNG strips with a per-creature manifest.json; per-creature recipes live in scripts/sprite_recipes/. Run scripts/verify_runtime_assets.sh after changing any art to confirm strip dimensions stay consistent.

License

MIT — see LICENSE.