PetHatch

Curated desktop pets for quota-aware coding companions.

PetHatch keeps a small set of animated pet packs that Kaji and compatible runtimes can launch. The goal is not a large marketplace; the goal is a few well-polished pets with clear behavior, source metadata, and useful messages.

Gallery: misterbrookt.github.io/pethatch 中文文档

Featured Pets

The default surface is intentionally small:

• navi: a sleepy lying panda with bamboo for the calmer Kaji design language.
• xiaochai: a sleepy shiba companion for focus, quota pressure, and rest reminders.
• oneko: classic lightweight pixel pet.
• amber: compact MIT status pet.

Extra imported packs may remain in the repository for reference, but manifest.featuredPetIds defines what Kaji and the gallery should show first.

Use Locally

./bin/pethatch list
./bin/pethatch doctor
./bin/pethatch validate

./bin/pethatch install navi --force
./bin/pethatch run navi
./bin/pethatch run navi --size medium
./bin/pethatch run navi --demo

Kaji can pass quota-aware state into the pet runtime:

./bin/pethatch run navi \
  --activity-source runtimeEvent \
  --state-file "$HOME/Library/Application Support/Kaji/pet-state.json"

Behavior

Each pet pack can include runtime.json. Navi Panda and Shiba are the current reference pets:

• focus: stay quiet while the session is healthy.
• quota pressure: warn before the coding run hits a quota wall.
• quota limit: wait and make the blocked state obvious.
• long session: remind the user to rest after 60 minutes.

The sprite contract stays simple: an 8 x 9 atlas with stable rows such as idle, waiting, running, review, and failed. Runtime events map onto those rows instead of requiring endless custom animations.

Build / Deps

pethatch run uses Pillow and PyObjC (AppKit / Quartz) on macOS.

License

Code and docs are MIT. Pet assets follow per-pack license fields.