# agent-delegate-bridge

An MCP server that lets Claude Code and Codex delegate tasks to each other.

Claude Code (or Codex, or any MCP-capable desktop tool) registers this server
and calls the `delegate` tool. Claude tasks run through `claude -p` (which
reads the provider proxy env from the cc-switch host-creds file, so it works
from any caller); Codex tasks run through the Agent Client Protocol (ACP).

```
[Claude Code] --MCP(stdio)--> [agent-delegate-bridge] --claude -p-----> [Claude Code CLI]
[Codex]       --MCP(stdio)--> [agent-delegate-bridge] --ACP(stdio)-----> [codex-acp]
```

## Install

```bash
npm install -g agent-delegate-bridge
```

After installing, the `agent-delegate-bridge` binary is on your PATH.

## Register in Claude Code

```bash
claude mcp add bridge -- agent-delegate-bridge
```

## Register in Codex

```bash
codex mcp add bridge -- agent-delegate-bridge
```

(For development from source, use `node dist/index.js` instead of `agent-delegate-bridge`.)

## Usage

The `delegate` tool takes:

- `target`: `"codex"` or `"claude"` — which agent to delegate to
- `task`: the prompt for the target agent
- `cwd` (optional): working directory for the target agent
- `timeoutMs` (optional): max wait in milliseconds, 1000–600000 (default 120000) — raise it when the target is slow (e.g. a flaky network that retries before falling back)

Example prompt to Claude Code:

> Use the `delegate` tool with target "codex" to ask Codex to write a unit test for `src/util.ts`.

## Requirements

- Node.js 22+
- Codex CLI (for delegating to Codex)
- Claude Code (for delegating to Claude)
- The ACP adapters are fetched automatically via `npx`.

## Troubleshooting

### Codex delegation fails

- Ensure you are logged into Codex (`codex` CLI works and ~/.codex/auth.json exists).
- If `codex-acp` fails with authentication errors, run `codex login` (or re-authenticate) to refresh your session.
- The first `npx` run downloads the `@agentclientprotocol/codex-acp` package — this may take 30-60 seconds.
- If delegation fails with a network error, run `codex doctor`. If it reports provider endpoints as unreachable, your machine cannot access the ChatGPT API (you may need a proxy/VPN) — this is not a bridge issue.
- If delegation fails with "You've hit your usage limit", your ChatGPT/Codex account has run out of credits — wait for the quota reset or upgrade. This is an account-level limit, not a bridge issue.

### Claude delegation fails

- Ensure Claude Code is installed and `claude` is on your PATH.
- If your Claude is behind a cc-switch proxy, make sure cc-switch is running — the bridge reads the proxy env (ANTHROPIC_BASE_URL, token) from the cc-switch host-creds file so delegation works from any caller.
- If the proxy env can't be found, delegation falls back to `claude`'s own claude.ai login (OAuth must be valid).

### Delegation times out

The default timeout is 120 seconds. If the agent takes longer (e.g., complex tasks or slow network), the call will fail with a timeout error. For longer tasks, pass a larger `timeoutMs` to the `delegate` tool.

Note: the Codex side can hit a 120s timeout even for short prompts when the adapter keeps waiting — the most common cause is an account/usage error that the adapter never surfaces as a clean response. See "Codex delegation fails" above (usage limit, auth, network) before assuming a real hang.

## Publishing to npm

The npm package name is `agent-delegate-bridge`. (An older package, `bridge-mcp-server`, is deprecated — don't install it.)

From a clean checkout, `npm publish` builds `dist/` automatically via the `prepack` script, so the published tarball always matches the source. Typical flow:

```bash
npm version patch     # bump version (0.1.10 -> 0.1.11)
npm run build && npm test   # sanity check
npm publish           # prepack runs `npm run build` automatically
git push --follow-tags
```

- `dist/` is gitignored and not committed; the `prepack` hook rebuilds it on every publish, so you never ship a stale or empty build.
- When you change `src/`, bump the version and republish — otherwise the installed global binary keeps the old build.
- Verify the published contents before announcing: `npm pack --dry-run` lists the files that will go out.

## License

MIT