Connect Codex¶

In Connect → Configure agent → Agent harness → Codex, name the system, environment and surface. Select Copy setup prompt, then paste it into Codex in the project you want to connect. The prompt includes your connection settings and asks Codex to install the helper, preserve existing hooks and check delivery. It contains no API key. Codex guides you through private key entry and reviewing hook trust; those steps still require you when they have not already been done.

Manual installation expands the original download and installation commands. Both paths use the same native hooks and your existing Codex login; no OpenAI API key is needed.

Setup¶

Tested against the hook contract in Codex CLI 0.153.4. The installer requires macOS or Linux and Python 3.10+, with no extra Python packages. Use a current Codex runtime with hooks enabled; desktop clients must use that same local project/config layer. Remote hosts need their own installation and tenant key.

Run from the selected project folder:

curl --fail --output planisphere_codex.py \
  https://api.planisphere.ooo/docs/examples/python/planisphere_codex.py
python3 planisphere_codex.py install \
  --system-id my-codex-project \
  --environment development \
  --surface codex

The installer asks for a tenant key from Keys, or reads PLANISPHERE_API_KEY if already set. It copies itself and saves the connection settings and key in ~/.local/state/planisphere/codex/<project-path-hash>/. That directory is private (0700); the key file is 0600 and outside the repository. It merges four background handlers into the project's .codex/hooks.json, preserving unrelated handlers and saving a dated backup of the original file. It does not modify global Codex settings, replace your login, or restart sessions. Repeating installation updates settings without adding duplicate hooks. Project hook commands contain absolute paths for this machine; do not distribute them unchanged to teammates. Each machine should install its own connection.

Review and trust the new definitions in Codex's /hooks UI. The project config layer must also be trusted. Start a new session in this project, complete a turn, then run from the same folder:

python3 planisphere_codex.py status

Background hooks may still be finishing. Inspect failed, skipped and last_outcome. Copy last_action_key into Connect's Check receipt step. It checks a record already received by your tenant and matches the connector, system, environment and surface. A session-start receipt alone is not accepted as proof of activity. The check makes no model call and creates no fake evidence. No events means no confirmed connection; check hook trust, project scope, administrative hook restrictions and runtime support.

Captured evidence¶

Hook	Record	Committed content
SessionStart	`session_started`	Session context; working directory hashed
UserPromptSubmit	`prompt_submitted`	Submitted prompt hashed locally
PostToolUse	`tool_used`	Tool input and available output hashed locally
Stop	`agent_response`	Latest assistant message hashed when available

Hashes use canonical JSON (UTF-8, sorted keys, compact separators, JSON string quotes included). Session context groups records within the tenant; turn and tool-call identifiers are committed when supplied. Model, tool name, app and environment labels are metadata subject to tenant retention policy. The helper does not read transcripts or files referenced by hook payloads.

PostToolUse observes supported local tools, including failed commands. The common hook contract does not report universal success or duration; those fields are explicitly unknown, never inferred from a callback firing. Stop is the latest final message exposed by the hook, not every model token or intermediate response. Hosted tools and specialized tool paths may not produce hook events. Separate subagent lifecycle capture, interruption capture, replay of historical sessions and complete institution-wide coverage are outside this first version.

Delivery and removal¶

Hooks run in the background and return empty JSON without approval decisions or extra model context. Network and rate-limit/server failures receive up to three attempts with a stable request body and idempotency key within that invocation. Capture failures are reported without raw content and do not block Codex work. occurred_at is the local hook observation time, not a measured tool start time.

Outcomes append to a private receipts.jsonl file; status summarizes up to 1,000 recent outcomes. This is a delivery log, not a durable queue: failed payloads are not retained for replay, and a killed hook can leave no final outcome. Receipt logs remain on this machine until removed; rotate them as needed. One verified receipt establishes that event arrived, not complete coverage or ongoing health.

To disconnect, disable the four Planisphere handlers in /hooks, or remove only their groups from project .codex/hooks.json. Remove the corresponding private state directory when you no longer need its key or receipts. Revoke a dedicated connector key in Keys if it is no longer used.

Hook configuration and coverage follow the official Codex hooks documentation.