codex-bridge

Codex Bridge

Codex is the executor; you are the orchestrator. Most of the wiring is in the runtime — your job is the judgment: when to delegate, what to surface as specific_concerns, when to merge, when to iterate.

When to use codex-bridge

Trigger when the work is one of:

• Substantial implementation (multi-file, scaffolding, migrations).
• Plan→execute→review loop where you want the worker isolated from your context.
• Adversarial review where you want to weight findings against specific risks.
• Background coding job you want to tail without burning Opus turns on the implementation.
• A [QUESTION] or [PLAN] to respond to.
• Manual task→review→verdict→merge loops; /codex-bridge:iterate currently returns the next manual action.

Don't trigger when:

• The task is a single-line typo or a one-file refactor under 50 LOC — just edit.
• You're watching a foreign long command (xcodebuild, npm test, …) — Monitor only understands .events files; use Bash --run-in-background instead.
• You already have an answer and are calling Codex for a second opinion on prose. Use a fresh subagent or write it yourself.

How the runtime helps you

You almost never have to remember the wiring — the hooks do it:

• PreToolUse(Agent) intercepts Explore-class subagents and reroutes them through codex-bridge. Pass-through for Plan, general-purpose, and codex-bridge:* types.
• PreToolUse(Bash) auto-rejects task --write invocations missing --worktree-auto. Worktree isolation is the canonical write-mode contract.
• PostToolUse(Bash) parses the --json envelope and emits an additionalContext block with the literal Monitor invocation. You arm it on the next turn — no manual derivation.
• SessionStart injects running-job status into context, so you start every session oriented.
• Stop can run the opt-in stop-time review gate. Pending verdicts are surfaced through verdicts --pending; check and resolve them before exiting.

When a hook misbehaves, set CODEX_BRIDGE_HOOK_DISABLE=<name> (or =all) and re-run.

Briefs (the orchestrator's privileged channel)

For non-trivial work, prefer a brief over a free-text prompt. The brief is a small JSON object that travels with the task all the way through to the review prompt's {{OPUS_CONCERNS}} slot. See references/brief-composition.md.

Minimum useful brief — goal and worker_assignment are the only required keys:

{
  "goal": "Add retry/backoff to the upstream fetcher",
  "worker_assignment": "Implement exponential backoff with jitter, max 3 attempts; preserve the existing public API; cover with a unit test.",
  "specific_concerns": [
    "Don't swallow non-retryable 4xx upstream errors",
    "Make the timeout configurable via the existing Config object"
  ]
}

Pass it to either subcommand:

node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" task --json --background --worktree-auto --brief @brief.json
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" adversarial-review --brief @brief.json

specific_concerns flows into the adversarial-review prompt verbatim. Anything you'd say "watch out for X" about should go there — not in the prose worker_assignment.

Capability gating

Before assuming a feature exists, read it. Two surfaces tell you what the bridge can do:

node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" version --json | jq '.result.adapter_capabilities'
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" status <task_id> --json | jq '.result.capabilities'

The active backend's capabilities object names the booleans you should branch on (supports_questions, supports_resume, supports_worktree, supports_artifact_registry, …). v2.0 ships only the codex backend; future adapters declare their own. Don't hard-code "codex behavior" in slash commands — branch on the capability you actually need.

Identifiers

Two IDs flow through every task. Use the right one or commands fail:

• task_id (task-mo… / review-mo…) — canonical handle for status, result, wait, events, cancel, merge, verdict, iterate.
• threadId (UUID v7 019d…) — required by send and steer. Also accepted by jobId-side commands as a convenience.

Don't pattern-match [codex] Thread ready (019d…) from stderr — that's a threadId, not a task_id. The --json envelope (result.jobId, result.threadId, result.eventsPath, result.monitor.tool_hint) is the only canonical source — result.jobId is the canonical task handle.

Worktrees and merges

Write-mode tasks land in <repo>/../.codex-bridge-worktrees/<task_id> on a subagent/codex/<task_id> branch. The worktree is not auto-removed on completion — you must:

1. Read <jobs>/<task_id>/meta.json, then run adversarial-review --cwd <worktree.path> --base <worktree.base_ref> with the same brief.
2. Inspect the verdict: /codex-bridge:verdict <task_id> or read <jobs>/<task_id>/verdict.json.
3. If verdict=approved: /codex-bridge:merge <task_id> (gated; refuses if verdict isn't approved). verdicts --pending shows approved-but-unmerged work.
4. If verdict=needs-attention or must-fix: re-brief and re-dispatch manually, use /codex-bridge:iterate <task_id> for the next-action stub, or /codex-bridge:verdict <task_id> --discard to abandon.

Pointers

Everything below is owned by another canonical surface. Read those when you need the detail; don't expect SKILL.md to mirror them.

• Per-subcommand reference — node …/codex-bridge.mjs <sub> --help. The --json envelope's error.code, error.suggestion, and result.next_action.command are also self-documenting.
• Event stream — events --help shows the supported filters. Treat unknown tags as forward-compat — pass them through, don't filter on assumed vocabulary.
• Config keys — config show --json prints the merged config. Edit ~/.codex-bridge/config.yaml or <workspace>/.codex-bridge.yaml; the resolution order is documented there.
• Error decision tree — references/error-recovery.md (decision tree by error.code + origin).
• Brief composition — references/brief-composition.md (full schema + when to use which field).
• One canonical orchestration flow — references/orchestration-flows.md.
• Notification format — references/notification-format.md (judgment-only; current CLI details are owned by events --help).
• Monitor patterns — references/monitor-patterns.md (Preset A only; everything else has been removed).
• Re-bloat prevention — references/AGENTS.md (read before adding a new reference file).

When in doubt: ask the runtime first (<subcommand> --help, config show --json, version --json), then read prose. Prose ages; the runtime is canonical.