Why HAYA Pet Exists

Codex Desktop made AI pets feel personal. The problem is portability: once a pet is generated there, it is useful only there.

HAYA Pet turns those pet assets into a shared runtime for the AI tools you actually use day to day:

Codex CLI       -> backend work
Claude Code     -> frontend work
Antigravity     -> infra work
Aider / Gemini  -> docs, scripts, experiments
Any command     -> still gets a session bubble

Instead of one pet per app, you get one pet for your whole AI workspace. It reacts to the selected or most urgent session, while compact bubbles show what each running client is doing.

The Candy

• Bring your Codex Desktop pets with you. HAYA Pet scans ~/.codex/pets, so Codex-compatible pet folders can be reused without rebuilding the character.
• Use one pet across many AI clients. Codex and Claude Code get richer live-status hooks; everything else can connect through the generic wrapper.
• See all active agents at a glance. Session bubbles show client, project, latest activity, and status: working, done, needs attention, or failed.
• Keep your terminal native. The default wrapper preserves normal terminal input. No broken Shift+Tab just to make the pet move.
• Stay local. HAYA Pet does not upload prompts, files, screenshots, or logs.

Quick Start

1. Install

From npm, when available:

npm install -g @hayasaka7/haya-pet

From source:

git clone https://github.com/HAYASAKA7/HAYA-PET.git haya-pet
cd haya-pet
npm install
npm link

Prefer not to link globally? Use the CLI directly:

node <repo>/apps/cli/src/haya-pet.js

2. Add A Pet

Put a Codex-compatible pet folder in ~/.codex/pets or ~/.haya-pet/pets.

On Windows, HAYA Pet also checks %USERPROFILE%\.codex\pets and %LOCALAPPDATA%\haya-pet\pets.

~/.codex/pets/my-pet/
    pet.json
    spritesheet.webp

Minimal pet.json:

{
  "id": "my-pet",
  "name": "My Pet",
  "spritesheet": "spritesheet.webp"
}

The spritesheet format is the Codex-compatible atlas used by this project: 1536 x 1872 pixels, 8 columns x 9 rows, 192 x 208 per frame.

Choose the pet:

haya-pet pets
haya-pet pets use my-pet

You can also switch pets from the tray menu.

3. Run Your AI Client Through HAYA Pet

The first haya-pet run starts the overlay automatically.

haya-pet run --client codex
haya-pet run --client claude-code
haya-pet run --client antigravity

# Any other CLI:
haya-pet run --client generic -- aider
haya-pet run --client generic -- gemini
haya-pet run --client generic -- your-ai-command --with --args

A bubble appears for the session. When the command exits, the bubble shows success or failure briefly, then fades.

What You Get On Screen

Screenshots

The global pet - reacting to the highest-priority session.	Session bubbles - one per active session, with status icons.
Folder collapsed - bubbles tucked away beside the pet.	Tray menu - show/hide, sessions, pets, reset position, quit.

Supported Clients

HAYA Pet has two ideas of support:

• Connection support: the client can be wrapped and shown as a session.
• Live-status support: the pet can react to in-session states like thinking, editing files, running tools, or waiting for approval.

Default behavior is intentionally conservative: HAYA Pet shows lifecycle status without changing how the terminal behaves. Richer live status is opt-in.

Live Status

For Codex and Claude Code, enable hooks once:

haya-pet hooks on
haya-pet run --client codex
haya-pet run --client claude-code

Check or disable the setting:

haya-pet hooks status
haya-pet hooks off

Why opt in? Both clients show a one-time trust prompt when hooks are added. HAYA Pet lets you decide when to approve that instead of surprising you in the middle of work.

Codex live status combines three sources: hooks report thinking/idle, a Codex-specific permission reporter maps approval requests from the session's resolved approvals_reviewer setting, and transcript watchers report tool/file activity plus guardian-review outcomes. With "Approve for me" the pet shows reviewing immediately; waiting for approval is reserved for Codex's manual "Ask for approval" mode.

Codex custom profiles are preserved. HAYA Pet installs its live-status hooks in $CODEX_HOME/hooks.json instead of passing its own -p profile, so launches such as haya-pet run --client codex -- codex --profile fugu keep both the selected Codex profile and HAYA live status.

Per-tool PreToolUse hooks still depend on an upstream Codex gap (openai/codex#16732); the transcript watcher covers that in the meantime.

For any client, you can ask HAYA Pet to infer rough activity from terminal output:

haya-pet run --observe --client generic -- aider

Use --observe only when you accept the PTY tradeoff. On Windows, ConPTY can break special input such as Shift+Tab, mouse scroll, and word-edit. The default non-observe mode keeps terminal input native.

Pet Controls

Commands

haya-pet run --client codex              # launch Codex with a pet session
haya-pet run --client claude-code        # launch Claude Code with a pet session
haya-pet run --client generic -- aider   # wrap any other command

haya-pet pets                            # list installed pets
haya-pet pets use my-pet                 # select a pet

haya-pet hooks on                        # enable live-status hooks where supported
haya-pet hooks status
haya-pet hooks off

haya-pet start                           # start the overlay explicitly
haya-pet stop                            # stop the overlay

If the overlay cannot start, the wrapped command still runs and keeps its real exit code. Disable auto-start with HAYA_PET_NO_AUTOSTART=1.

Requirements

Updates

HAYA Pet checks npm for a newer published version at most once a day (cached in state.json). When one exists, the CLI prints a one-line notice after your wrapped command exits, and the tray shows Update Available (x.y.z) — clicking it opens the package page. Updating is always your action:

npm install -g @hayasaka7/haya-pet

The check is best-effort (3s timeout, silent on failure, never blocks a run), skipped when output is piped, and fully disabled with HAYA_PET_NO_UPDATE_CHECK=1.

Troubleshooting

More fixes are in docs/troubleshooting.md, including repairing a broken Electron install.

Privacy

HAYA Pet is local-only by default. It does not upload prompts, files, screenshots, or session logs. The overlay stores only local state needed for pet selection, position, size, and short derived status summaries. The single outbound request it ever makes is the daily npm version check (a standard HTTPS request to registry.npmjs.org that sends no session data); disable it with HAYA_PET_NO_UPDATE_CHECK=1.

Documentation

Contributing

Run the full test suite:

npm test

The codebase is organized as one npm package with internal packages under packages/ and apps under apps/. Start with docs/architecture.md if you want to add a client adapter, touch the overlay, or work on pet rendering.

License

MIT. See LICENSE.