Agent Bridge

Codex supervises Claude Code and DeepSeek Harness. Bridge itself does not call LLM.

Let Codex be the only supervisor. Claude Code or DeepSeek Harness does the implementation. You review, verify, and apply in Codex.

One Command

npx -y codex-agent-bridge

Then start a new Codex session. You will see the bridge_* tools.

This command will: install the runtime to ~/.agent-bridge, write Codex Skill and MCP (using local node.exe, not npx.cmd), and run doctor once.

To update, run the same command again. To uninstall:

npx -y codex-agent-bridge uninstall
npx -y codex-agent-bridge uninstall --purge

--purge will delete ~/.agent-bridge.

Prerequisites

We don't handle

• Won't install Claude Code / DeepSeek Harness for you

• Won't change their model / provider / reasoning effort

• Won't call any LLM

Whichever Worker is available, that one will be dispatched. When none are available, doctor will indicate.

Related MCP server: cc-agent

What it does

Codex  ──bridge_run──►  Claude Code / DeepSeek Harness
  ▲                         │
  │      ReviewPacket       │  在独立 worktree 里改代码
  │      verification       │  不得 commit / push / merge
  └──── bridge_apply ◄──────┘

Closed loop:

bridge_run
→ WAITING_FOR_INPUT 时 bridge_respond
→ AWAITING_REVIEW + ReviewPacket
→ bridge_approve     任务分支 checkpoint，不是完成发布
→ bridge_apply       cherry-pick 到当前分支，不是 merge

Turn end ≠ task completion. Diff only recognizes baseCommit vs worktree.

bridge_run only selects worker: claude or deepseek (debugging can use replay / fake). Do not pass model / provider / effort.

If DeepSeek Harness is not in a common path, set AGENT_BRIDGE_DEEPSEEK_ROOT.

Usage Notes

• The target must be an independent git repository. Each bridge_* call carries the same project. The task UUID field name is task.

• Only one Writer per project at a time. A second writer returns CORE_LOCK_HELD.

• After modifying MCP, you must start a new Codex session; old sessions won't see the new tools.

• A corrupted tasks.json will result in TASK_STORE_CORRUPTED, not treated as an empty store.

Publishing a New Version

Local npm publish always requires 2FA; this is an npm rule and cannot be made passwordless like git push.

The correct approach is: change version → tag → push, and GitHub Actions uses Trusted Publishing to publish to npm, no password needed.

One-time setup (only needed once): Open codex-agent-bridge npm settings → Trusted Publisher → GitHub Actions, fill in:

After that, each time:

# 先改 package.json 里的 version，提交
git tag v1.2.0
git push origin main --tags

Developing from Source

npm install
npx tsx src/cli.ts setup --dev
npm test

--dev makes MCP point to the current repository instead of ~/.agent-bridge.

Documentation

The repository directory may still be called Agent Relay. The product name is Agent Bridge. The npm package name is codex-agent-bridge.