611c10176a27.Quick answer
Use the data-only companion-state.v1 event with one of six states—idle, working, waiting_for_input, reviewing, completed, or failed. Keep Pet packages transport-free; if live calls are needed, review and register the separate local stdio MCP Bridge, which accepts no task text or arbitrary metadata.
Six states cover the portable agent lifecycle
The codextheme.tools companion event format defines idle, working, waiting_for_input, reviewing, completed, and failed. They map to the pet atlas rows for idle, working, waiting, review, wave, and failed. Completion uses a restrained wave instead of inventing a new row; movement and the sixteen v2 look directions remain separate visual controls.
The event deliberately excludes task content
A state event contains only format, sequence, state, trigger, and an optional fixed lookDirection. The strict parser rejects unknown fields, including prompt text, tool arguments, file paths, model names, and arbitrary metadata. The browser simulator does not send the event to the site or retain it after the page closes.
Animation timing follows the real row contract
The preview uses each row's actual populated columns and duration sequence. Idle plays six cells, wave four, jump five, waiting/working/review six, and the full run and failed rows eight. This avoids cycling into intentionally transparent unused cells and gives creators a more accurate local QA surface.
The exported map is still not executable
The exported companion-map.json is documentation-only. It does not start a daemon, listen on loopback, connect MCP, read Codex task content, or install anything. Pet packages therefore remain data-only and safe to inspect independently.
The optional Bridge is a separate local process
The source-visible Companion Bridge exposes three narrow tools over stdio MCP and a token-protected 127.0.0.1 browser overlay. Its schema accepts only the six states, a monotonic sequence, and an optional fixed idle direction. It does not accept arbitrary text, prompts, code, paths, commands, tool arguments, logs, or credentials. Registration and removal are explicit, and no MCP client is claimed to call every lifecycle state automatically.
Completion checklist
- Event format is companion-state.v1
- Only allowlisted fields exist
- State maps to the expected row
- No task content is included
- Pet package map remains transport-free
- Optional Bridge registration is explicit and reversible
Frequently asked questions
Does the simulator connect to Codex or MCP?
No. The simulator and exported map stay browser-local and transport-free. The optional source-visible Companion Bridge is a separate stdio MCP process that must be explicitly reviewed and registered.
Which pet animation represents completion?
Completed maps to the existing wave row as a restrained acknowledgement. The protocol does not invent a tenth standard action row.
Can an event contain the current prompt or file path?
No. Unknown fields are rejected. The portable event intentionally excludes task text, tool arguments, file paths, model identity, and arbitrary metadata.