agent-bridge — orchestrate parallel AI coding agents from Claude (MCP server)

agent-bridge is an MCP server that turns a Claude conversation (Claude Desktop or Claude Code) into an orchestrator for parallel AI coding agents. Each agent runs in its own Tern terminal tab, on its own git worktree and branch. Agents can use any model available on your machine through omp (oh-my-pi), or run as Claude Code.

The orchestrator plans the work, starts the agents, follows their progress, reads their reports and diffs, and sends corrections. You don't copy-paste anything between the two.

Français

flowchart LR
  O["Claude Desktop / Claude Code<br/>(orchestrator)"] -- MCP tools --> B["agent-bridge"]
  B -- "tern new tab · send · capture" --> T["Tern session 'agents'<br/>one tab per agent"]
  B -- "git worktree add" --> W["worktree + branch agent/&lt;name&gt;"]
  T --> A["omp (any provider) or Claude Code<br/>model + thinking per agent"]
  A -- "session transcript" --> B
  W -- "git diff" --> B

Features

• Parallel coding agents, isolated. Each agent gets its own git worktree and branch (agent/<name>), so agents never step on each other or on your checkout.

• Any model, any provider. The default omp engine can use every model omp exposes on your machine: Anthropic, OpenAI / Codex, LiteLLM or other proxies, local models, and any other provider you configured. Claude Code is available as a second engine.

• Model choice that stays current. Set an exact model, or use auto:fast, auto:balanced or auto:frontier. The tiers are recomputed from the live model catalog, so a newly released model appears in them as soon as omp lists it. No vendor is favoured by default.

• You decide which models are used. Give the orchestrator rules such as "only use openai-codex/*" or "frontier = opus". It records them with set_model_policy, and the server enforces them on every start.

• Thinking level per task. Low reasoning for mechanical edits, high for design or hard bugs. You can switch an agent's model or thinking level mid-task; it keeps its full history.

• Pick up existing sessions. Discover omp and Claude Code sessions already running in any Tern window and drive them in place. Saved sessions can be reopened in a new tab with their full history.

• Hands-off monitoring. wait_for_agents returns when a turn ends. You get each agent's final report (a ## Report section), its commits, and a full diff that includes uncommitted edits. The server warns you when an agent looks stuck on an approval or dialog.

• Live view. Every agent is a normal Tern tab: watch it work, or type into it yourself.

Related MCP server: Agent Squad Bridge

Quick start

Requirements:

• macOS (what it is tested on; Linux should work wherever Tern and omp run, but is untested);

• Tern, running;

• omp, logged in to at least one provider;

• Claude Desktop, or Claude Code, as the orchestrator;

• git.

curl -LsSf https://raw.githubusercontent.com/merlinh0/agent-bridge/main/install.sh | sh

The installer:

1. installs uv if needed;

2. installs the agent-bridge command;

3. registers it in Claude Desktop and Claude Code (backing up the Claude Desktop config first);

4. runs agent-bridge doctor.

Then quit and reopen Claude Desktop.

uv tool install git+https://github.com/merlinh0/agent-bridge
agent-bridge install            # --no-desktop / --no-claude-code / --dry-run
agent-bridge doctor

Or register it yourself in claude_desktop_config.json:

{ "mcpServers": { "agent-bridge": { "command": "/absolute/path/to/agent-bridge", "args": ["serve"] } } }

Usage

Start a conversation in Claude Desktop and give it a goal:

You orchestrate my coding agents (agent-bridge tools).
Repository: ~/code/my-app. Goal: add CSV export to the reports page, with tests.
Model rules: only use openai-codex/* and anthropic/claude-sonnet-*; frontier tier = openai-codex/gpt-6.1-sol.
Split the goal into independent tasks, show me the plan, then start one agent per task with the right
model tier. Loop on wait_for_agents → get_agent → get_diff, send corrections, and ask me before cleanup.

Other things you can ask:

• "List the omp sessions running in Tern and take over the one working on the API."

• "Reopen yesterday's session on the landing page and ask it to finish the tests."

• "Restart the fix-cache agent on the frontier tier with high thinking."

Tools

Agent states: starting, working, idle (turn finished, waiting for you), exited, closed.

Model selection and policy

model accepts:

• an exact omp selector from list_models, such as openai-codex/gpt-6.1-sol or anthropic/claude-sonnet-5-5;

• for Claude Code, a Claude model or alias (opus, sonnet, haiku);

• an automatic tier: auto:fast, auto:balanced or auto:frontier.

thinking accepts off…max for omp, and low…max for Claude Code (passed as --effort). Levels a model doesn't support are rejected, and the error lists the valid ones.

How tiers are computed. The tiers come from the live catalog (omp models --json), so nothing is hard-coded:

1. Keep chat models that have a price.

2. Keep the newest version of each model family (an undated id wins over its dated copies).

3. Split by output price: the cheapest third is fast, the most expensive third is frontier, the rest is balanced.

Default thinking is low, medium and high respectively. Run list_models(refresh=True) or agent-bridge models --refresh to pick up a model that just launched. Free and local models are never auto-picked, but you can always select them by name.

Policy. The orchestrator calls set_model_policy when you state rules. They hold until the MCP server restarts, which usually means until you restart the app. For permanent defaults, put the same two keys in ~/.agent-bridge/config.json:

{
  "allowed_models": ["openai-codex/*", "anthropic/claude-sonnet-*", "claude-code/*"],
  "tiers": { "frontier": "openai-codex/gpt-6.1-sol" }
}

• allowed_models is a list of glob patterns. omp models match on their selector; Claude Code models match on claude-code/<model>. An empty list allows everything.

• tiers pins the model a tier stands for, instead of the automatic pick.

• With an allowlist, an agent started without a model gets auto:balanced from the allowed models instead of the engine's default.

• Disallowed models are refused when an agent starts, resumes or switches model.

Configuration

FAQ

How do I run several Claude Code or AI coding agents in parallel without conflicts? Each agent works in its own git worktree on its own branch, so file edits and commits never collide. Merge the branches you accept (git merge agent/<name> or a PR), then call stop_agent(cleanup=True).

Can agents use GPT, Codex, local or other non-Anthropic models? Yes. The omp engine uses every model omp exposes on your machine. list_models shows them all, and the auto tiers mix vendors by price.

Does it work with claude.ai in the browser? No. claude.ai only reaches public HTTPS MCP servers, which would mean exposing control of your terminal to the internet. Use Claude Desktop or Claude Code.

What about tool approvals? By default, agents follow your normal approval settings. When one is waiting, capture_screen shows it and press_keys answers it. auto_approve=true (omp --auto-approve / claude --dangerously-skip-permissions) removes the stops. It is refused until you run agent-bridge auto-approve on yourself; see Security.

How is this different from Claude Code subagents? Subagents live inside one session and one checkout. agent-bridge agents are full, independent sessions you can watch and type into, each on its own branch and its own model, and they survive restarts. Existing sessions can be adopted.

Claude Code asks "Do you trust this folder?" It asks once per repository. The agent stays in starting with a warning, and press_keys(["Down", "Enter"]) answers yes.

Security

The orchestrator reads text written by the agents (reports, diffs, terminal screens), so a hostile repository or web page could try to steer it through them. The server is built with that in mind:

• Tool arguments are treated as untrusted. Agent names are validated, session files must be real transcripts from the omp / Claude Code session stores, and nothing is passed through a shell or parsed as a command-line option.

• auto_approve is off until you enable it with agent-bridge auto-approve on in a terminal. No MCP tool can flip that switch.

• Nothing is typed into a pane that no longer runs the agent. If an adopted session exits and leaves your shell behind, the next message resumes the session in a new tab instead.

• Cleanup never guesses. stop_agent(cleanup=True) refuses when the worktree has uncommitted files or unmerged commits, or when it cannot check. Adopted sessions are never deleted.

• State is private. ~/.agent-bridge is created with owner-only permissions.

What it does not protect against:

• Agents run as you. An agent can do whatever its engine's approval settings allow, in the repository you point it at. Only start agents on repositories you trust.

• The model policy is a rule for the orchestrator, not a sandbox. The orchestrator can change it with set_model_policy, and an adopted session keeps the model it already runs on.

• Approving a prompt with press_keys runs that command. Read the screen first.

Please report vulnerabilities privately through GitHub's "Report a vulnerability" button on the repository's Security tab.

Limitations

• Claude Code as an engine is less tested than omp. Starting, reading state and sending keys were checked live; a full Claude Code turn was not.

• A live Claude Code pane does not say which session it runs. The bridge takes the session id from the command line when there is one, otherwise the most recent transcript of that directory, and refuses when several were active recently.

• State is read from the transcript. An agent waiting on a dialog stays working; the warning after 90 s without activity is the signal to look at its screen.

• Auto tiers rank models by price. Price is a proxy for capability, not a benchmark; pin a model per tier when you disagree.

Troubleshooting

Run agent-bridge doctor first.

Development

uv run --group dev pytest
uv run --group dev ruff check src tests
uv run agent-bridge serve      # stdio MCP server

Issues and pull requests are welcome.

License

MIT