codex-bridge-v2-alpha

codex-bridge

A Claude Code plugin that delegates substantial coding work to OpenAI Codex through a hook-driven runtime. Claude orchestrates; Codex executes. Hooks intercept native Agent spawns, auto-arm Monitor on background dispatches, isolate write-mode tasks in per-task git worktrees, and surface running-job state into context — so the orchestrator rarely has to teach itself how to drive the bridge.

install

# 1. install Codex and sign in
npm i -g @openai/codex && codex login

# 2. install the plugin
/plugin install codex-bridge@yigitkonur

# 3. verify
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" setup --json | jq '.result.ready'

If setup reports true, you're done. Open Claude Code in any repo and ask it to "have Codex…" — the plugin takes over.

Migrating from the v1.x skill at ~/.agents/skills/codex-bridge/? See MIGRATION.md.

what's different from a typical Codex skill

The v1.x version of codex-bridge was a 22K-word user-level skill that taught Claude how to drive the bridge by reading prose. v2.0 turns most of that teaching into runtime enforcement:

• PreToolUse(Agent) intercepts Explore-class subagent spawns and reroutes them through codex-bridge for cheap-fast read-heavy work. Plan and general-purpose subagents pass through unchanged.
• PreToolUse(Bash) auto-rejects task --write invocations that omit --worktree-auto. Worktree isolation is the canonical contract for write-mode work; check result.isolation_mode because branch-only fallback, explicit --cwd, or user opt-out can still run in the requested checkout.
• PostToolUse(Bash) parses the --json envelope and emits the literal Monitor invocation as additionalContext — Claude arms it on the next turn without you having to teach the rule.
• SessionStart injects running-job status into context so every session boots oriented.
• Stop blocks if any approved-but-unmerged verdict is pending, with one-line resolution hints.

The skill is now ~3,600 words instead of 22,000. The runtime owns the wiring; SKILL.md owns the judgment.

three-line examples

# delegate substantial work, isolated in a worktree, with concerns flowing into review
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" task --background --write --worktree-auto --json --brief @brief.json "Read brief.json and implement its worker_assignment."

# adversarial review using the brief's specific_concerns as {{OPUS_CONCERNS}}
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" adversarial-review --scope branch --base main --brief @brief.json

# staged loop helper: returns next_action for manual task -> review -> verdict
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" iterate <task_id> --max 3 --brief @brief.json

The slash-command equivalents (/codex-bridge:task, /codex-bridge:adversarial-review, /codex-bridge:iterate) are preferred — the hooks fire on the underlying Bash invocations.

verdict and merge

Write-mode work doesn't auto-land. Each task produces a worktree at <repo>/../.codex-bridge-worktrees/<task_id> on a subagent/codex/<task_id> branch. Convert review findings into a verdict, then merge:

/codex-bridge:verdict <task_id> --set approved --summary "Tests green; concerns dismissed."
/codex-bridge:merge <task_id>             # gated; refuses if verdict ≠ approved

The Stop hook blocks session exit while approved-but-unmerged verdicts exist. /codex-bridge:verdict <task_id> --discard is the explicit "do nothing with this" sink.

brief schema

The brief is the canonical channel for non-trivial dispatch. It's a small JSON object that travels from dispatch through review:

{
  "goal": "Add retry/backoff to the upstream fetcher",
  "worker_assignment": "Implement exponential backoff with jitter, max 3 attempts; preserve the 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"
  ],
  "acceptance_criteria": ["npm test passes", "diff under 200 lines"]
}