codex-bridge
a claude code plugin for handing real work to openai codex without losing track of the job.
claude stays the orchestrator. codex does the implementation, review, follow-up, and long-running work through the local codex app-server. codex-bridge adds the parts you usually end up wanting once this gets serious: background jobs, event logs, worktree isolation, structured briefs, review artifacts, verdicts, and gated merge.
what you get
/codex-bridge:task for delegating implementation, debugging, refactors, and multi-step work./codex-bridge:review for codex's normal code review./codex-bridge:adversarial-review for a steerable review that challenges the design and risk profile./codex-bridge:iterate for task -> review -> verdict -> follow-up loops./codex-bridge:status, /codex-bridge:events, /codex-bridge:wait, /codex-bridge:result, and /codex-bridge:cancel for background jobs./codex-bridge:verdict, /codex-bridge:verdicts, and /codex-bridge:merge for branch-bound review and gated landing.
the official openai codex plugin is still the clean default if you only want /codex:* reviews and simple delegation. codex-bridge is the heavier tool: use it when you want durable artifacts, worktree isolation, monitor-ready event streams, and explicit merge control.
requirements
- claude code with plugin support.
- node.js 22 or later.
- git.
- the codex cli on your path.
- a working codex login or provider config.
install codex if you do not already have it:
npm install -g @openai/codex
codex login
install
install the plugin in claude code:
/plugin marketplace add yigitkonur/codex-bridge
/plugin install codex-bridge@codex-bridge
/reload-plugins
then run:
/codex-bridge:setup
setup checks node, npm, codex, auth, backend capability support, and the optional stop review gate. if it says ready, you are good.
why two commands? claude code installs plugins from marketplaces. yigitkonur/codex-bridge is the github repo that provides the marketplace, and codex-bridge@codex-bridge means "install the codex-bridge plugin from the codex-bridge marketplace." @... is the marketplace name, not the github owner.
if you see this:
marketplace "yigitkonur" not found
you used the old owner-as-marketplace install shape. add the marketplace first, then install from it with @codex-bridge.
for a local checkout while developing:
/plugin marketplace add /absolute/path/to/codex-bridge
/plugin install codex-bridge@codex-bridge
/reload-plugins
if you are migrating from the old standalone skill under ~/.agents/skills/codex-bridge/, read migration.md.
contributors and agents use GSD under .planning/ as the only workflow
authority; public docs here are for install and runtime usage.
quick start
review your current work:
/codex-bridge:review --background
/codex-bridge:status
/codex-bridge:result
hand off an implementation task:
/codex-bridge:task fix the failing auth tests with the smallest safe patch
for file-changing work you want isolated from your main checkout:
/codex-bridge:task --write --worktree-auto --background fix the failing auth tests with the smallest safe patch
for non-trivial work, pair a brief with a real prompt:
/codex-bridge:task --write --worktree-auto --background --brief @brief.json implement the task described in the structured brief
run a stricter review:
/codex-bridge:adversarial-review --base main focus on race conditions, data loss, and rollback safety
run the closed loop:
/codex-bridge:iterate add retry/backoff to the upstream fetcher, cover it with tests, and stop when review approves
main commands
/codex-bridge:task
starts a codex task. by default the bridge uses plan mode, the configured sandbox, and the auto review pipeline.
use it for implementation, debugging, refactors, and bigger investigations. write-mode work should use worktree isolation; active plugin hooks surface Monitor/status context and may route Agent calls through the bridge, but the installed hook manifest does not currently register a Bash preflight gate.
useful patterns:
