3af1d6d62f3a.Quick answer
Use the data-only companion-state.v1 event with one of six states—idle, working, waiting_for_input, reviewing, completed, or failed. Validate it locally and map it to the existing pet row without including prompt text, tool arguments, file paths, a network transport, or a background runtime.
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.
A map is not a runtime integration
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. A future CLI, MCP adapter, or desktop runtime needs its own opt-in, authentication, process, privacy, platform, update, and uninstall review before it can consume live events.
Completion checklist
- Event format is companion-state.v1
- Only allowlisted fields exist
- State maps to the expected row
- No task content is included
- Runtime and transport remain explicitly absent
Frequently asked questions
Does the simulator connect to Codex or MCP?
No. It is a browser-local state preview and strict JSON validator. The exported map does not include a transport or runtime.
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.