Skip to content

Codex members

Operational doc for cafleet member panes that run the OpenAI Codex CLI (codex) instead of Claude Code (claude). cafleet supports both binaries side-by-side; this file covers the codex-specific surface.

For the multi-backend overview and selection rules, see the Coding agents Concepts page.

Overview

A codex member is a cafleet member whose agent_placements.coding_agent value is "codex". The Director selects the backend at member-create time:

cafleet --fleet-id <fleet-id> member create --agent-id <director-agent-id> \
  --name Codex-A --description "<one-sentence purpose>" --coding-agent codex

The default is --coding-agent claude. A single Director may spawn claude, codex, and opencode members in the same fleet — the broker, message lifecycle, and tmux primitives behave identically for all three. See Opencode members for opencode-specific operational detail.

Spawn flags

When --coding-agent codex is in effect, cafleet spawns the member pane with:

codex --ask-for-approval never --sandbox workspace-write <prompt>
  • --ask-for-approval never disables interactive approval prompts. Combined with --sandbox workspace-write, this is the codex equivalent of Claude Code's --permission-mode dontAsk: routine permission prompts auto-resolve, the Bash tool is enabled, and the member runs cafleet (and any other shell command) directly.
  • --sandbox workspace-write confines codex to writing files within the current workspace. See https://developers.openai.com/codex/agent-approvals-security for the upstream description of the approval / sandbox combo.
  • --model <m> is appended immediately before the prompt when cafleet member create --model <m> is supplied (e.g. codex --ask-for-approval never --sandbox workspace-write --model gpt-5.4-mini <prompt>). Any string passes through verbatim — the codex binary itself rejects unknown models, so newly released models work without a cafleet release. Example models (not enforced by cafleet): gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark. When the flag is omitted, no model tokens are emitted and codex uses the model set in its configuration.

[!IMPORTANT] Codex's --sandbox workspace-write blocks writes outside the workspace, including cafleet's default SQLite DB at ~/.local/share/cafleet/cafleet.db. Operators must add the cafleet DB directory to sandbox_workspace_write.writable_roots in any config.toml codex reads, such as ~/.codex/config.toml:

[sandbox_workspace_write]
writable_roots = ["/home/<you>/.local/share/cafleet"]

Use the absolute path matching CAFLEET_DATABASE_URL or the default XDG location.

Refer to the same upstream page for the canonical write-up of the --ask-for-approval and --sandbox flags.

Required codex CLI version

cafleet has been validated against codex-cli 0.128.0. Earlier versions may not accept the --ask-for-approval / --sandbox flags in the form cafleet uses; in that case the spawn will fail or the resulting pane will refuse non-interactive operation.

If codex --version reports an older version, upgrade per the upstream install instructions at https://developers.openai.com/codex/.

If the codex binary is not on PATH, cafleet member create --coding-agent codex exits 1 with Error: binary codex not found on PATH. Install codex, confirm with codex --version, and retry.

cafleet usage from inside a codex pane

Codex members cannot load Claude Code skills, so their spawn prompt points them at this page instead. The same cafleet CLI surface works from a codex pane unchanged:

cafleet --fleet-id <fleet-id> message poll --agent-id <my-agent-id>
cafleet --fleet-id <fleet-id> message send --agent-id <my-agent-id> \
  --to <director-agent-id> --text "..."
cafleet --fleet-id <fleet-id> message ack --agent-id <my-agent-id> --task-id <task-id>

Members substitute the literal ids from their spawn prompt; there is no env-var fallback.

For the full broker CLI reference (register, send, broadcast, poll, ack, cancel, show, agent listing, deregister, member commands), see CLI options.

The ! shell-shortcut convention

Codex CLI honors a leading-! shell shortcut on its input line, which cafleet's bash-via-Director fallback uses — see Bash routing.

Pane-title asymmetry

Only claude sets the pane title to the member name; locate codex panes via cafleet member list (the pane_id column is ground truth) — see Coding agents.

Verification recipe (manual smoke test)

Gated on local install of both claude and codex binaries. Run from inside a tmux session. The recipe pastes literal ids: fleet 1, Director 2, members 4 (claude) / 5 (codex) — your ids will differ.

cafleet fleet create --label codex-smoke --coding-agent claude
# Expect: a '<fleet_id> director=<director_id> admin=<admin_id>' line.
# Note the fleet and Director ids — the steps below use 1 and 2.

cafleet --fleet-id 1 member create --agent-id 2 \
  --name Claude-Smoke --description "claude smoke member" --coding-agent claude
cafleet --fleet-id 1 member create --agent-id 2 \
  --name Codex-Smoke --description "codex smoke member" --coding-agent codex

cafleet --fleet-id 1 member list
# Expect: two rows, backend column shows 'claude' and 'codex' respectively.

cafleet --fleet-id 1 message send --agent-id 2 \
  --to 5 --text "ping"
# Expect: the codex pane receives the 2-line inline preview and the member ack-loops correctly.

cafleet --fleet-id 1 member exec \
  --member-id 5 "git status --short"
# Expect: '! git status --short' lands in the codex pane and the command runs.

cafleet --fleet-id 1 member delete --member-id 5
cafleet --fleet-id 1 member delete --member-id 4
cafleet fleet delete 1

This recipe is not part of the automated test suite — it is the manual verification path before shipping changes that touch the codex backend.