agent-pet-bridge

A tiny stdin/stdout bridge that lets any CLI agent drive a customizable animated pet. The wrapped agent does not need a plugin SDK: if it can read stdin and write stdout, it can be wrapped.

npm install
npm run demo

Wrap a real agent:

agent-pet run --pet ./examples/pets/local-xin -- your-agent --arg

The bridge keeps the agent's stdout clean and writes pet state transitions to stderr. UIs can use --json to consume JSONL state events.

Pet Package

my-pet/
├── pet.json
└── spritesheet.webp

The spritesheet follows the Codex-style 1536 x 1872 atlas: 8 columns, 9 rows, 192 x 208 per cell. See docs/custom-pet-method.md.

States

The built-in state map supports:

idle, running-right, running-left, waving, jumping, failed, waiting, running, review.

See docs/state-effects.md for triggers and visual effects.

Explicit Events

Agents can print deterministic markers:

[[PET:review]]
PET_STATE=running
{"type":"pet.state","state":"failed"}

Import Local Pets

You can also import your own local pet package into .local/pets:

node scripts/import-codex-pet.js xin --from ~/.codex/pets/xin
agent-pet run --pet ./.local/pets/xin -- your-agent

.local/ and spritesheet.* files under examples are gitignored. .local/ is gitignored for personal experiments.