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](/guides/administrator-setup/).

## Install the integration

Install Codex if it is not already available:

```bash
npm install --global @openai/codex
```

Then install the Chorus integration with the `chorus` CLI:

```bash
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](/guides/operator-onboarding/) and select `codex` as the
backend. Verify the connection in the foreground before using
[Operate the Chorus daemon](/guides/daemon-operations/) 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](/reference/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`):

```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](/guides/session-recovery/) 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](/guides/remote-control/) and
[Interrupt and resume a session](/guides/session-recovery/) 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:

```bash
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](/guides/session-recovery/#take-over-from-a-terminal)
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](/guides/troubleshooting/).