Harness Bridge

Harness Bridge connects coding-agent harnesses through MCP so one harness can query, review, explain, and delegate implementation work to another.

It currently ships two adapters:

The adapter boundary keeps harness-specific execution, sessions, models, and capabilities separate while preserving a consistent set of task-oriented MCP tools.

Execution contract

Only connect Harness Bridge to projects and harnesses you trust with the permissions of your user account.

Prerequisites

• Claude Code CLI, installed and authenticated

• OpenAI Codex CLI, installed and authenticated — version 0.147.0 or newer for the default app-server backend (older versions still work with HARNESS_BRIDGE_CODEX_BACKEND=exec)

• Node.js 18 or newer

Quick start

Configure both routes and install the bundled skills and Codex teammate agent:

npx @rbutera/harness-bridge setup

Configure one route without installing extras:

npx @rbutera/harness-bridge connect claude --to codex
npx @rbutera/harness-bridge connect codex --to claude

The compatibility forms remain available:

npx @rbutera/harness-bridge setup claude
npx @rbutera/harness-bridge setup codex
npx @rbutera/harness-bridge setup --skip-extras

setup claude means “configure Claude Code as the calling harness”; setup codex configures Codex as the caller.

Manual configuration

Claude Code calls Codex

claude mcp add codex -s user -- npx @rbutera/harness-bridge serve codex

Project-local .mcp.json:

{
  "mcpServers": {
    "codex": {
      "type": "stdio",
      "command": "npx",
      "args": ["harness-bridge", "serve", "codex"]
    }
  }
}

Codex calls Claude Code

Add this to ~/.codex/config.toml:

[mcp_servers.claude]
command = "npx"
args = ["harness-bridge", "serve", "claude"]
tool_timeout_sec = 600

Tools

Each adapter exposes the same task categories with a harness-specific prefix:

All tools accept workingDirectory. Both adapters support deliberate multi-turn continuity, but through different parameters:

• Codex tools accept an optional threadId. Omit it to start a fresh thread; pass back the threadId a prior call returned to continue that conversation.

• Claude tools accept an optional threadKey. Omit it for independent calls; reuse a stable key to continue one conversation.

Either way, keyless (or threadId-less) calls are independent and run fully parallel; calls that continue the same conversation are serialized so two turns never race one thread.

For Codex, omit model unless a specific override is required so the current default from ~/.codex/config.toml applies.

Continuing a Codex conversation

Every Codex response that carries a thread ends with a trailing line:

threadId: 0199a1b2-c3d4-...

Echo that id back on the next call to continue the same thread:

// first call — omit threadId to start fresh
{ "prompt": "Summarize the auth module." }
// response ends with:  threadId: 0199a1b2-c3d4-...

// follow-up — pass the id back to continue
{ "prompt": "Now suggest a refactor.", "threadId": "0199a1b2-c3d4-..." }

Thread state lives in Codex's own storage, so resume works across bridge restarts, Claude sessions, and reboots.

Bundled skills and agent

setup can install:

• a /codex skill for Claude Code

• a codex-teammate agent for Claude Code

• a /claude skill for Codex-compatible agent directories

Install them individually with:

npx @rbutera/harness-bridge install skill claude --global
npx @rbutera/harness-bridge install skill codex --global
npx @rbutera/harness-bridge install agent --global

Use --local instead to install into the current project.

Configuration

The previous BRIDGE_* and CODEX_BRIDGE_* names remain accepted for compatibility. New configuration should use HARNESS_BRIDGE_*.

Codex backends

The app-server backend is the default. It keeps one persistent Codex process, supports first-class threads, and can interrupt active turns. After every turn the bridge unsubscribes the thread so the app-server unloads its per-thread MCP stack while the thread stays resumable. It requires codex >= 0.147.0; a missing or too-old codex produces an actionable error naming the fix.

To opt back into the legacy codex exec backend (one subprocess per call):

HARNESS_BRIDGE_CODEX_BACKEND=exec npx @rbutera/harness-bridge serve codex

The legacy CODEX_BRIDGE_BACKEND name is also accepted, and the value app-server remains valid as an explicit no-op. Both backends use the same unrestricted execution policy. Threads created under one backend are not guaranteed to resume under the other.

Migrating from claude-codex-bridge

See MIGRATION.md for the package, command, configuration, and environment-variable changes. MCP server names and tool names are unchanged.

Development

git clone https://github.com/rbutera/harness-bridge.git
cd harness-bridge
pnpm install
pnpm check

pnpm check runs formatting, lint/type checking, all tests, the production build, and package linting.

Origin and license

Harness Bridge began from Dunqing’s claude-codex-bridge v0.3.1. The original Git history and authorship are preserved; ORIGIN.md records the lineage and subsequent divergence.

Licensed under the MIT License.