Codex

Codex has a first-party Chorus integration with tools, workflow skills, and hooks. It is also a supported Chorus daemon backend.

Before you install, create an agent key by following Prepare agent access.

Install the integration

Install Codex if it is not already available:

npm install --global @openai/codex

Then install the Chorus integration with the chorus CLI:

npm install --global @chorus-aidlc/chorus
chorus agents add --agents codex

Enter the Chorus URL and agent key when prompted. chorus agents add installs the Codex plugin, writes CHORUS_URL, CHORUS_API_KEY, and CHORUS_AGENT_PROFILE into ~/.codex/.env, and sets bearer_token_env_var = "CHORUS_API_KEY" in ~/.codex/config.toml, so Codex reads its key from the environment and the config file never contains it.

Apply configuration to an existing App Server

From Chorus 0.21.1, after credentials and MCP configuration are successfully written, interactive setup can offer to restart an already running Codex App Server with the saved environment. This is not the Chorus daemon. All Codex paths respect CODEX_HOME (default ~/.codex).

• A restart can interrupt other Codex sessions and active work. The prompt defaults to No; only an explicit y or yes authorizes it.
• Non-interactive sessions, --yes, and CHORUS_DAEMON_HEADLESS=1 defer the restart. The general --yes flag does not authorize interrupting sessions.
• If no App Server is running, setup does not start one. Unsupported commands, unknown state, failed configuration, or a declined identity overwrite defer the restart rather than guessing. Plugin-only updates skip this step.
• A failed restart leaves the saved configuration intact. A successful restart reports only the command result, not a new credential, MCP-tool, or model verification.

If you defer, save work in affected sessions and rerun chorus agents add --agents codex from an interactive terminal without --yes when it is safe. A supported running server will offer the dedicated prompt again and use the saved environment. Simply reopening the terminal UI may reconnect to the same old server. Then follow the connection check below. Setup does not upgrade Codex to obtain restart support.

Enable remote start

Skip this section if you only use Chorus from an interactive Codex session. Otherwise, follow Connect an agent runtime and select codex as the backend. Verify the connection in the foreground before using Operate the Chorus daemon to keep it online.

Daemon behavior in 0.20.0

Daemon wakes now use one isolated codex app-server --listen stdio:// process per turn. The minimum verified baseline is codex-cli 0.157.1; older versions are unverified, and missing protocol support fails the wake. There is no codex exec fallback or backend switch. If you use a custom CODEX_HOME, install the Chorus integration there too. Updating Chorus plugins does not upgrade the Codex CLI itself.

Model options and session continuity

Daemon args support model selection (--model / -m) and permitted -c / --config settings such as model_reasoning_effort. Other options, including --oss, image inputs, and unknown switches, fail before launch. Transport, cwd, permission, and managed MCP controls are protected. Use supported config settings or explicit foreground commands through the CLI; chorus agents run --type codex -- exec ... and ... -- resume ... retain their existing behavior.

The daemon resumes stored threads, including threads from the earlier exec backend, with the current working directory and permission policy.

• Replacement threads: only a definitive “no rollout found” response starts a replacement thread, once, with a continuity notice in the conversation. Other resume errors stop the wake and keep the stored link between the Chorus session and the Codex thread.
• Stored session records: if the daemon cannot read its stored session record, it starts fresh with a warning; if it cannot save one, it warns that future continuity may be reduced.
• New messages queue for later turns; they do not steer a running turn.
• Token usage is reported for the current turn only. If a resumed thread has no reliable starting count, that turn’s usage is left out rather than counting the thread’s history.

Restricted mode and tool approvals

--chorus-only keeps Codex read-only, with interactive approvals and network access disabled for the turn. Native requests for approval or user input are denied; requests that cannot be safely rejected fail the wake. Questions should go through Chorus comments or elaboration. On the verified Codex version, Chorus MCP tools that require approval can also be rejected, including chorus_checkin. A completed turn does not prove that its MCP calls succeeded.

If you choose to allow check-in, put this explicit tool allowance in ~/.codex/config.toml (or the agent’s CODEX_HOME/config.toml):

[mcp_servers.chorus.tools.chorus_checkin]
approval_mode = "approve"

This allowance was verified for new and resumed threads on 0.157.1 while read-only mode and disabled interactive approvals remained in effect. It permits only check-in; comments and task updates require their own explicit allowance and verification. Put these rules in Codex configuration, not daemon args. The daemon does not approve requests on your behalf.

Interrupts and troubleshooting

An authorized interrupt sends turn/interrupt; cancellation during startup closes the transport. The daemon then performs bounded process-tree cleanup. On Windows this needs Windows PowerShell (Get-CimInstance) and taskkill.

For startup or protocol failures, check codex --version, login, model/config settings, and local session storage permissions. Initialization has a 30-second limit, setup RPC responses 60 seconds, and cleanup 10 seconds. A running turn has no inactivity or total runtime timeout: use Interrupt if it is stuck. CLOSED is informational only. A turn that failed, was interrupted, or never reported an outcome is not a success, even if the process exits with code 0. See Interrupt and resume a session for the recovery flow.

Verify the connection

Open Codex and ask it to check in to chorus. Confirm that the response shows the expected agent identity and permissions. You can also use /plugins and /hooks to confirm that the Chorus plugin and hooks are enabled.

For daemon mode, open Settings → Agents in Chorus and confirm that the expected host and working directory are online.

Capabilities and limits

• The integration provides Chorus MCP tools, workflow skills, and Codex hooks.
• Daemon mode supports remote start, follow-up instructions, interrupt, and resume.
• Codex does not provide a pre-spawn hook, so Chorus workflow skills explicitly manage sub-agent sessions.
• Remote work inherits the local user’s access. Register only trusted working directories.

Use Start work on a remote agent and Interrupt and resume a session for shared operating procedures.

Resume from the terminal

To take over a live conversation from your own terminal, copy its session ID from the chat UI (Copy session ID in the transcript header) and run, from the conversation’s working directory:

codex exec resume <thread_id>

Codex generates its own thread ID, so the copied value is that thread ID — not a Chorus-supplied session ID. It is exactly what Chorus passes back to Codex when it resumes a run. See Interrupt and resume a session for the full flow.

Common issues

• codex is not found: install @openai/codex globally and re-run chorus agents add.
• Old credentials after configuration, or missing CHORUS_API_KEY: check .env under the actual CODEX_HOME and rerun chorus agents add --agents codex; use the safe App Server restart flow above. Rotate the key only if it is invalid or revoked.
• Plugin or hooks are disabled: enable them in /plugins and /hooks, then restart Codex.
• Daemon is offline: run chorus daemon status, then see Troubleshoot agent connections.