AgentBridge

A uniform interface to the coding-agent CLIs you already have installed and logged in to: Claude Code, Codex, OpenCode, Antigravity (agy), pi, Cursor, Grok, Gemini, Devin, any Agent Client Protocol agent, and HTTP models such as Ollama.

AgentBridge spawns the real CLI, normalizes its events, results, errors, sessions and permissions, and exposes the result as a command line, a TypeScript library, an MCP server, and an OpenAI/Anthropic-compatible HTTP proxy. It uses each tool's own login. It does not need API keys and has no runtime dependencies.

ab ask claude "Review src/auth.ts for security bugs"
ab ask codex  "Write tests for it" --permissions edit
ab ask claude "Large refactor" --fallback codex,pi      # next agent takes over on a rate limit
ab race "Fix the flaky test" claude:haiku codex opencode # first accepted answer wins

Node.js 22 or newer. Linux, macOS and Windows. MIT licensed.

Coding agent reading this repository? Read README_AI.md for operational instructions.

Contents

• Why it exists

• Install

• Quickstart

• Core concepts

• Agents calling agents (MCP bridge)

• Fallback and quota-aware routing

• Harness proxy (ab serve)

• Other features

• Supported agents

• Security and privacy

• Documentation

• Development

Related MCP server: subway-mcp-server

Why it exists

Each coding-agent CLI has its own flags, configuration directories, session model, permission model and output format. Combining them means maintaining shell glue, and when one hits a usage limit mid-task you start over in another tool.

AgentBridge puts one contract in front of all of them, so that:

• one command, library call or MCP tool drives any agent with the same options (model, effort, permissions, session, timeoutMs, cwd);

• an agent can delegate to another agent as a subagent, with permissions that can only narrow;

• a task can move to the next agent in a chain when the first one is rate limited or out of quota;

• existing applications that speak the OpenAI or Anthropic API can use an agent harness as their backend.

Install

npm install -g @rodolfonobrega/agentbridge     # provides `ab` and `agentbridge`
# or, without installing:
npx @rodolfonobrega/agentbridge setup

From source:

git clone https://github.com/rodolfonobrega/agentbridge.git
cd agentbridge
npm ci && npm run build && npm link

You need at least one supported agent CLI installed and logged in (claude, codex, opencode, agy, pi, ...) or a reachable Ollama server. Missing agents are skipped, not errors.

Updating. npm update -g @rodolfonobrega/agentbridge updates the package but not copies of the agentbridge-delegate skill already installed into agent skill directories. Run ab setup and choose the skill option to refresh them. AgentBridge warns on stderr, in interactive use, when an installed copy is stale; it never updates skills or agent configuration on its own.

Quickstart

ab setup            # detects installed agents, installs the MCP bridge and skill, sets a permission ceiling
ab doctor           # checks each CLI, login and model list; add --live for one tiny real call per agent
ab ask claude "Reply with exactly: PONG"
ab run opencode "Explain main.js" --stream

From code:

import { ask, run, fanout, race } from '@rodolfonobrega/agentbridge';

const r = await ask('claude', { prompt: 'Say hi', model: 'haiku' });
console.log(r.text, r.usage, r.sessionId);

const { winner } = await race(['claude:haiku', 'codex', 'opencode'], { prompt: 'Name three primes' });
const { results } = await fanout(['claude:haiku', 'codex'], { prompt: 'Review src/auth.ts' });

Core concepts

One option set. model, effort (low to max, mapped per agent), permissions, cwd, timeoutMs, systemPrompt, jsonSchema, session, mcpServers, env, extraArgs, fallback. Each adapter maps them onto the CLI's own flags; options an agent cannot honor are rejected or reported, not silently dropped.

Normalized output. Streaming events (text, tool, usage, fallback, ...) and a final result (text, sessionId, usage, model, structured, fallback). Failures are typed: NOT_INSTALLED, NOT_LOGGED_IN, TIMEOUT, ABORTED, BAD_OPTION, RATE_LIMITED, AGENT_FAILED. jsonSchema output is validated and repaired with one retry.

Permissions. read-only (default), plan, edit, full. AgentBridge requests the level through each harness's own controls (Claude permission modes, Codex sandbox modes, OpenCode/pi/agy tool rules). Enforcement strength differs by agent, and generic adapters may rely on prompt guidance, so read-only is not an operating-system sandbox. edit allows file changes but no shell commands; use full for tasks that must run commands. An operator-set ceiling bounds everything, including subagents. See harness validation.

Sessions. new, ephemeral, continue (by id, or latest for the working directory) and fork where the agent supports it. The agent's own session store is used, so sessions are visible in that tool's resume list.

Telemetry. Runs, tokens, cost and context pressure are recorded locally under ~/.agentbridge/ and shown by ab ps, ab top, ab stats and the dashboard (ab ui). See docs/TELEMETRY.md.

ab ui, shown with sample data from scripts/demo-data.mjs.

Agents calling agents (MCP bridge)

ab install <target> registers an MCP server (ab bridge) with Claude Code, Codex, OpenCode, Antigravity, pi, Cursor, VS Code, Zed, Windsurf or Claude Desktop (ab install all for every installed one). The host agent then gets ask_<agent> (blocking) and dispatch_<agent> (returns a run id) tools, plus wait_run, check_run, cancel_run, list_runs, retain_run, release_run, send_message, check_messages and checkpoint tools.

• Install scope defaults to the current project; pass --scope user for a global install.

• Delegation depth is capped by AGENTBRIDGE_MAX_DEPTH (default 2). A subagent can never exceed its caller's permissions.

• Results carry an HMAC attestation line ([agentbridge] ...); filter it from answer text.

• wait_run blocks at most 30 seconds per call. A wait timeout does not stop the run. There is no completion push: poll until done, error, lost or cancelled.

• send_message/check_messages are a mailbox, not prompt injection into a running agent.

• Subagents do not inherit the host's MCP servers or skills by default; see README_AI.md.

The bundled agentbridge-delegate skill teaches host agents how to use these tools.

Fallback and quota-aware routing

# Error-driven: on RATE_LIMITED, try the next agent
ab ask codex "Refactor the auth flow" --fallback claude,pi,ollama:qwen2.5-coder:14b

# Quota-aware: require 30% remaining on the primary, 15% on agy, 20% on codex
ab run claude "Implement the change" --permissions edit --min-remaining-percent 30 \
  --fallback 'agy@15:gemini-3.8-flash-low,codex@20,ollama:qwen2.5-coder:14b'

# Wait up to 45 minutes for a measured quota reset
ab run claude "Review the release" --wait-for-quota --max-quota-wait 2700

• HTTP 429/529 and provider quota errors map to RATE_LIMITED (with retryAfterMs when known). Change the triggering codes with --fallback-on.

• Measured quota percentages exist for Claude, Codex, Antigravity and, conditionally, Gemini OAuth. Unknown or unsupported measurements never count as available quota. See the provider support matrix.

• Without a quota flag or @N threshold, quota is not checked and only errors trigger fallback.

• A run is not retried on another agent after tools have already run under edit or full, because the work may have been partially applied. The result reports fallback: { used, attempts, contextLost }.

• The same policy is available in the library (quotaPolicy), MCP dispatch tools and the proxy.

Harness proxy (ab serve)

ab serve --port 8787 --token "$TOKEN"

ab serve exposes the agent CLIs as an OpenAI-compatible (/v1/chat/completions, /v1/responses) and Anthropic-compatible (/v1/messages) HTTP server. Select the harness with the model name: claude/haiku, codex/gpt-5, agy/gemini-3.8-flash-low, pi/<provider>/<model>, opencode/<provider>/<model>, ollama/<model>.

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8787/v1", api_key="local")
client.chat.completions.create(model="claude/haiku", messages=[{"role": "user", "content": "Hello"}])

A harness proxy, not a provider proxy

LiteLLM, OpenRouter-style gateways and similar tools are provider proxies: they translate one API into many providers' HTTP APIs and need an API key per provider. The unit they route to is a model endpoint.

AgentBridge's proxy is a harness proxy: the unit it routes to is an installed coding-agent CLI (Claude Code, Codex, ...), authenticated by the login that CLI already has. Each request is executed by spawning that CLI, not by calling the vendor's HTTP API. This exists for cases a provider proxy cannot cover:

• Subscription logins. Claude and Codex plans are usable through their CLIs but not through the raw API. A provider proxy cannot use them; a harness proxy can. This may conflict with a provider's terms for consumer plans; read Terms of service before use.

• Harness behavior. Each CLI brings its own agent loop, tools, sandbox and session handling. Agent mode (/agent/v1) lets the harness edit files in an isolated git worktree and returns a diff you apply explicitly. Callers that already isolate their own work (an optimizer running one evaluation per folder, for example) can send x-ab-sandbox: none to run the harness directly in the folder instead.

• One surface for existing software. Tools that only speak the OpenAI or Anthropic protocol (SDKs, notebooks, evaluation and optimization frameworks, editors) can use any installed harness, with the same fallback and quota policy as the CLI.

What follows from this design, stated plainly:

• Latency includes CLI start-up (seconds).

• The default API mode is plain chat with the CLI's tools off, but it is still the CLI executing the request, so temperature, top_p, seed and penalties are accepted and ignored (listed in the x-agentbridge-ignored response header). max_tokens and stop are enforced by the proxy approximately.

• Token usage comes from the CLI when it reports it and is estimated otherwise.

• Client tool calling works (natively for Claude, emulated for the other harnesses), but replies are buffered rather than streamed.

If you have API keys and want a high-throughput gateway to model endpoints, use a provider proxy. If you want to use the harnesses you are logged in to from software that expects an API, use this. Full reference: docs/PROXY.md.

Other features

Command and option details: docs/REFERENCE.md.

Supported agents

Cursor, Grok, Gemini, Devin and generic ACP agents are supported through their CLIs when installed. Pass --offline (or offline: true) to disable network tools where the harness allows. Details and caveats: docs/REFERENCE.md.

Security and privacy

• Local only. There is no remote analytics. Run history, stats and checkpoints are stored under ~/.agentbridge/ and in your repository. The only network traffic is what the agent CLIs and configured endpoints themselves send to their providers.

• Dashboard and proxy bind to loopback, check the Host header against DNS rebinding, and accept an optional bearer token (--token or AGENTBRIDGE_TOKEN). Agent mode refuses to start without a token.

• Credentials. The attestation key reaches subagents through the process environment only, never on disk or in argv.

• Defaults are conservative. Permissions default to read-only; widening is explicit.

• Process supervision. Agent stderr is held in a bounded ring buffer, and on timeout or abort the whole process tree is killed (process groups on POSIX, taskkill /T /F on Windows).

Threat model and reporting: SECURITY.md.

Terms of service

AgentBridge drives the CLIs with your own logins. Providers may restrict automated use of consumer or subscription plans. Use it for personal, local work, do not expose the proxy to other people, and use API keys where your provider requires them. The account pool (--accept-tos-risk) is off by default and is your responsibility.

Documentation

Development

npm ci
npm run build
npm test            # offline suites; no agent or login required
npm run accept      # drives the real, logged-in CLIs you have installed; others are skipped

Contributions, especially new adapters, are welcome. See CONTRIBUTING.md, which also describes the release process, and docs/EXTENDING.md.

License

MIT