Codex Bridge for Claude Code

Use Codex as a second engineering agent from inside Claude Code—without a leaked background daemon, hidden write access, or an untraceable job lifecycle.

Codex Bridge is an independent Claude Code plugin for delegating repository questions, code reviews, plan checks, adversarial second opinions, and explicitly authorized implementation tasks to an existing local Codex CLI.

It is inspired by the use case of OpenAI's codex-plugin-cc, but uses an independently implemented direct-process architecture.

At a glance

	Codex Bridge
Best for	Developers who use both Claude Code and Codex CLI
Default access	Read-only
Write access	Only /codex-bridge:task --write
Background model	One directly owned Codex process per job
Persistent daemon	None
Credentials	Reuses the user's Codex CLI authentication; never copies it
Platforms	Windows, macOS, and Linux with Node.js 20.11+

Why this project exists

Claude Code and Codex often catch different problems. Using both manually, however, means leaving the current workflow, copying context between tools, and losing a clear record of which agent is still running or allowed to write.

Existing bridges have also used shared detached brokers and centralized mutable state. Public upstream reports describe orphaned process chains, stale running jobs, and session-environment contamination.

Codex Bridge solves the coordination problem with a smaller operating model:

Codex Bridge uses a smaller operating model:

• no app-server broker or persistent daemon
• one directly owned Codex CLI child per job
• append-only state per job, with no shared mutable state file
• PID liveness and heartbeat-derived failed, stalled, and orphaned states
• no SessionStart or SessionEnd hooks
• prompts sent to Codex over stdin, not command-line arguments
• redacted prompt previews and lifecycle-only event storage
• read-only by default; only task --write grants workspace-write
• one active writer per workspace

See the evidence-backed upstream analysis for the full comparison and tradeoffs.

What it is—and is not

Use Codex Bridge when you want a bounded second opinion, review, or implementation task inside a repository already open in Claude Code.

It is not:

• a replacement for Claude Code or Codex CLI;
• a hosted service or API proxy;
• a shared long-running agent server;
• an automatic deployer or GitHub publisher;
• permission to bypass either tool's safety controls.

Requirements

• Claude Code with plugin support
• Node.js 20.11 or newer
• Git
• A locally installed and authenticated Codex CLI

Codex Bridge does not copy, inspect, or manage Codex credentials.

If Codex CLI is not installed, the official npm installation is:

npm install -g @openai/codex
codex --version

Run codex once and complete its normal sign-in flow before installing the bridge.

Install in Claude Code

This repository is a Claude Code marketplace; it is not an npm package. Run these commands inside Claude Code:

/plugin marketplace add Teide131/codex-bridge-cc
/plugin install codex-bridge@codex-bridge-community
/reload-plugins

Verify the local runtime without granting write access:

/codex-bridge:doctor

The doctor is diagnostic only. It never installs software or changes authentication.

The first useful smoke test is:

/codex-bridge:ask summarize this repository's architecture

Claude Code's marketplace flow is two-step: adding a marketplace makes its catalog available; installing the plugin activates this specific package. See the official Claude Code plugin installation guide.

Typical workflow

# 1. Ask for an independent read-only assessment
/codex-bridge:challenge pressure-test the retry strategy

# 2. Check the job lifecycle if it runs in the background
/codex-bridge:status

# 3. Read the redacted final result
/codex-bridge:result task-...

# 4. Grant workspace writes only for a bounded implementation task
/codex-bridge:task --write fix the confirmed retry bug with the smallest patch

Read-only commands never become write-capable because of wording inside the prompt. --write is a separate, explicit capability choice.

Commands

Command	Access	Purpose
/codex-bridge:doctor	Read-only	Check Node, Git, workspace, state path, and Codex CLI invocation.
/codex-bridge:ask	Read-only	Ask a lightweight repository question.
/codex-bridge:review	Read-only	Run native Codex review on uncommitted work, a base diff, or a commit.
/codex-bridge:challenge	Read-only	Pressure-test an implementation or design.
/codex-bridge:plan-review	Read-only	Verify feasibility, ordering, rollback, and test coverage.
/codex-bridge:task	Read-only by default	Delegate a bounded task. Add --write only for explicit edits.
/codex-bridge:status	Read-only	Show recent jobs or inspect one job.
/codex-bridge:result	Read-only	Read one final, redacted result.
/codex-bridge:cancel	Explicit cancellation	Request cooperative cancellation of one identified job.

Examples:

/codex-bridge:ask explain the authentication flow
/codex-bridge:review --base main --background
/codex-bridge:challenge question the retry and cache invalidation design
/codex-bridge:plan-review review docs/migration-plan.md
/codex-bridge:task investigate the flaky test
/codex-bridge:task --write fix the flaky test with the smallest safe patch
/codex-bridge:status
/codex-bridge:result task-...
/codex-bridge:cancel task-...

How it works

Claude Code command
       |
       v
Codex Bridge validates arguments and workspace boundary
       |
       v
one directly owned `codex exec` or `codex review` child
       |
       +--> append-only lifecycle events + heartbeat + PID evidence
       |
       v
redacted final result returned to Claude Code

There is no shared broker and no daemon to rescue. Each job owns its own state and process relationship. A workspace-level atomic lease allows at most one active writer while still permitting read-only review jobs.

Direct CLI

The bridge runtime is also directly callable:

node plugins/codex-bridge/scripts/bridge.mjs doctor
node plugins/codex-bridge/scripts/bridge.mjs ask "explain the data flow"
node plugins/codex-bridge/scripts/bridge.mjs review --uncommitted
node plugins/codex-bridge/scripts/bridge.mjs task --write "implement the approved parser change"

For shell-sensitive text, prefer UTF-8 base64:

node plugins/codex-bridge/scripts/bridge.mjs ask --prompt-base64 '<base64>'

Runtime behavior

Each workspace maps to a SHA-256-derived local state directory. Each job gets an immutable metadata file, append-only JSONL lifecycle events, optional PID records, one cancellation request, and one final result.

The full task prompt is not stored. State contains only a SHA-256 digest and a redacted preview. Raw Codex reasoning, command output, and repository content are not copied into bridge state.

Background cancellation is cooperative: the worker sees a unique request file and terminates only the process tree it created. If the worker is already dead while a child PID appears alive, the bridge reports orphaned and refuses to kill that PID blindly because it may have been recycled.

Safety boundaries

Codex Bridge never adds:

• danger-full-access
• --yolo
• approval bypasses
• external publishing or deployment permissions
• automatic installation, login, or credential changes

--write means Codex may edit the current workspace. It does not authorize GitHub pushes, deployment, billing, credential changes, destructive actions, or writes outside the repository.

Updating

Refresh the marketplace and reload plugins inside Claude Code:

/plugin marketplace update codex-bridge-community
/reload-plugins

Troubleshooting

• /plugin is unknown: update Claude Code, restart it, and retry.
• Marketplace not found: confirm the repository is reachable, then rerun /plugin marketplace add Teide131/codex-bridge-cc.
• Plugin command not found: run /reload-plugins after installation or update.
• Doctor cannot invoke Codex: run codex --version, then run codex directly and complete its sign-in flow.
• Job reports stalled or orphaned: inspect /codex-bridge:status <job-id>; the bridge deliberately refuses to kill an unverified PID.

Current status and limits

• Version 0.1.0 is the first public release candidate.
• The test suite uses a deterministic fake Codex executable and does not require network access or a real account.
• Live invocation through the packaged Windows Codex desktop executable is not confirmed because Windows returned EPERM; use a separately installed, authenticated Codex CLI.
• Cancellation is cooperative, and a verified process may take a short time to exit.

Development

npm ci
npm run verify

Tests use a fake Codex executable and do not require network access or a real account.

Contributions are welcome. Read CONTRIBUTING.md, and report security issues according to SECURITY.md. Please do not include credentials, private repository content, or raw agent transcripts in public issues.

License

MIT