using-codex

# Using Codex from Claude Code `codex-bridge` runs OpenAI Codex through `codex app-server` and prints one compact JSON envelope. The full Codex output always lands in a file; the envelope carries only status, ids, usage, and a bounded `summary`. This is what keeps Claude tokens low: never relay Codex prose through a subagent when a file path will do. ## The one command ``` node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" run --preset <preset> --task "<one to three sentences>" ``` Envelope fields: `status` (completed | unconfirmed | failed | stalled | timeout | interrupted), `thread_id`, `turn_id`, `out_file` (full final message), `result_file` (full parsed object of a `--schema` run), `events_file`, `usage`, `duration_s`, `idle_timeout_s`, `hard_timeout_s` (null unless `--timeout` was given), `model_applied` (the model that actually ran), `summary`, `files_changed`, `commands_run`, `diff_file` (the turn's diff, when there was one), `questions` and `questions_file` (anything Codex asked and got no answer to), `error`. An `implement` run also carries the task contract: `outcome` (done | partial | blocked, downgraded by the bridge when the evidence does not support "done"), `checks`, `open_questions`, `contract_violations` and `continuation` (a resume handle when the work is not done). Branch on `outcome`, not on the prose. `unconfirmed` means the final answer arrived but the server could not confirm the turn ended: read `out_file`, but treat it as unverified. Other commands: `review`, `resume <thread|--last>`, `result [--last|run-id] [--full]`, `status [--last|run-id]`, `steer`, `threads`, `worktrees`, `doctor`, `server start|stop|status|release`, `presets`. Output is quiet by default; `--verbose` streams progress to stderr. Run `codex-bridge.mjs help` for flags. On the shared server a run collects only its own thread *and* turn, so a concurrent run's output can never land in this envelope. `--all-events` additionally records the rejected traffic in `events_file` for debugging; it is never attributed. ## How long a turn runs A turn takes as long as Codex needs; there is no wall-clock limit. The watchdog is `--idle-timeout` (default 600 s), which fires only when **no** event has arrived for that long, i.e. the turn is genuinely stalled rather than slow. A stalled run comes back as `status: "stalled"`, distinct from `timeout`. `--timeout` adds an optional absolute cap on the **whole command**, not on each phase: connecting, the handshake, model selection, opening the thread and the turn itself all share the one budget, so `--timeout 60` means the command is done in about a minute. Only a small bounded tail for interrupting and closing may follow it. ## Codex may delegate Codex spawns its own subagents when a task suits it, and their work is attributed back into the run: `commands_run` and `files_changed` include theirs, and `subagents[]` lists each one with its label and counts. Ask for it explicitly when a task splits cleanly ("delegate these three checks to parallel subagents, then consolidate"): it is one Codex turn and one Claude call regardless of how many subagents run. ## Pick a preset | Preset | Use for | Sandbox | Effort | Model | |---|---|---|---|---| | `consult` | second opinion, design critique, "try to refute this" | read-only | xhigh | default | | `review` | code review of a diff (`review` command) | read-only | high | default | | `plan` | implementation plan before coding | read-only | xhigh | default | | `implement` | make the change, run tests; thread persists for `resume` | workspace-write | high | sol, then terra | | `research` | facts that need live web search | read-only | medium | sol, then terra | | `quick` | lookups, small transforms, yes/no checks | read-only | xhigh | luna, then spark | `default` is a **tier**, resolved against the live catalog at run time: whatever Codex marks as its default model (gpt-6-astra at the time of writing), not a pinned id and not the user's `config.toml` pin. It is reserved for the short, judgement-heavy presets; `implement` and `research` name a cheaper candidate list so Astra is not spent on every long run, and `quick` runs a small model at high effort. `--model config` inherits the user's pin; `--model <id>` is sent as given. An effort the chosen model does not advertise is dropped rather than sent, so `ultra` only reaches a model that offers it. `model_applied` in the envelope says what actually ran. This table is a summary; `references/presets.md` is the authoritative matrix (timeouts, summary lengths, extras). Override per call with `--model`, `--effort`, `--sandbox` or `--write`, `--timeout`, `--schema`. Sandbox is always sent explicitly; the user's `danger-full-access` config never leaks into a run. ## When to delegate Delegate when a second model adds value or when the work is long and self-contained: independent review of a diff Claude wrote, refuting a hypothesis, a long implementation while Claude keeps working, research needing live web search, or a burst of parallel mechanical tasks. Do not delegate a two-minute edit; the round trip alone is twenty seconds. ## Writing the task (point, don't paste) Codex has full repository access. Name files, functions, and commands; do not paste their contents. Bridge threads read the project's `AGENTS.md`, or `CLAUDE.md` when there is none (per-thread `project_doc_fallback_filenames`; `claude_md_fallback: false` in settings turns that off), and carry the relay contract as developer instructions, so the task need not repeat either. The envelope's `instruction_sources` lists what was loaded. A good task is one to three sentences plus, if needed, the acceptance criterion: ``` --task "Refute this claim by reading scripts/lib/process.mjs: on Windows the vendored codex.exe is resolved before any shell spawn." --task "Implement --retries N for scripts/codex-bridge.mjs run (retry transport failures only). Add a node:test case in tests/. Run npm test." ``` The preset template already fixes the response contract (length caps, ordering, file:line references). For a long brief, write it to a file and pass `--task-file`. To invoke one of Codex's own skills explicitly, pass `--skill <name>` (repeatable): the name is resolved through `skills/list` for the working directory and sent as the documented skill input item, and an unknown or disabled name fails before any turn. ## Ordinary sessions: call the script directly Use Bash yourself. No subagent is needed. For anything over a minute, use `run_in_background: true`; the envelope arrives with the completion notification, and `result --last` re-prints it. Read `out_file` with Read only when `summary` was truncated or the detail matters. For an `implement` while you are editing the same checkout, add `--worktree`: Codex works in its own checkout branched from HEAD, the envelope's `diff_file` is the complete patch to apply or review, and your tree is untouched (a dirty checkout is refused unless you pass `--worktree-from HEAD`). `worktrees remove <run-id>` cleans up afterwards. A run in the background can be redirected with `steer --last --task "…"` (shared server only) and inspected with `status --last`, which also recovers a run whose process died by asking the server what became of the turn. Continue a persisted thread instead of re-explaining: `resume --last --task "Now add tests for the edge case you mentioned."` Threads from `consult`, `plan` and `implement` persist by default (named `[claude] <preset>: <task head>` in the user's Codex history); add `--persist` to any other preset. `threads prune --older-than 14` archives old bridge threads. A resumed thread keeps the sandbox, model and effort it ran under unless you pass a flag, so an `implement` thread stays writable; `--last` is scoped to this Claude session when the SessionStart hook ran. ## Fan-out: prefer the native runner For a fan-out where every stage is a Codex turn (review panels, sweeps, adversarial verification), use `scripts/codex-workflow.mjs`. It runs the whole thing in one Node process with no Claude agent in the loop, so nothing relays output, stages can run for as long as they need, and completed calls are cached for `--resume`: ``` node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-workflow.mjs" run \ "${CLAUDE_PLUGIN_ROOT}/workflows/review-panel.mjs" --args @lenses.json ``` Launch it with `run_in_background: true`; read `result` from the summary it prints. See `references/native-runner.md` for the script API and the bundled workflows. When your own judgement belongs between Codex stages, run one native workflow, read its `result.json`, decide, and launch the next: one Bash call per stage and no relaying agent. The Claude Workflow tool path (a Haiku agent forwarding one command line) was removed: an LLM call that copies stdout costs tokens and needed guard hooks to keep it honest, and the native runner covers every all-Codex fan-out. For fan-out over many small items, consider one Codex turn that does the fan-out itself with Codex subagents (on by default in current Codex as `multi_agent_v2`); that costs one Claude call instead of N. ## Concurrency and the shared server Each `run` spawns a private `codex app-server` (about 2 s startup plus MCP servers from the user's config). Parallel runs are independent processes. For many short calls, `server start` launches one loopback WebSocket server; `--via ws` or `shared_server: true` in settings routes runs through it, and `codex agents --remote ws://127.0.0.1:4517` lets the user watch them. Thread-scoped `--config` keys and `--search` apply on both transports (they travel in `thread/start.config`); process-scoped keys only reach a private server. ## Failure handling `status: failed` with `error_kind` from Codex (`UsageLimitExceeded`, `Unauthorized`, `ContextWindowExceeded`, `SandboxError`) or an HTTP error body. `RateLimitPreflight` means the account was already past `rate_limit_refuse_percent` and no turn was started; `rate_limit.resets_at` says when to retry. `timeout` means the turn was interrupted at `--timeout`; the partial `summary` is whatever Codex had said. Run `doctor` when nothing works. Codex usage counts against the user's ChatGPT or API limits. ## Additional resources - `references/presets.md`: preset matrix, template contracts, how to add a preset. - `references/protocol.md`: app-server methods the runtime uses, envelope schema, run store layout. - `references/native-runner.md`: the codex-workflow script API, run directory layout, and resume.