Cli Bridge Mcp

English · [Français](docs/i18n/README.fr.md) · [简体中文](docs/i18n/README.zh-CN.md) · [Español](docs/i18n/README.es.md) · [Português (BR)](docs/i18n/README.pt-BR.md) · [日本語](docs/i18n/README.ja.md) · [Deutsch](docs/i18n/README.de.md)

cli-bridge

Your assistant is only as good as the one model you opened. cli-bridge is a Model Context Protocol server that lets it borrow the other AI CLIs you already run — a bigger context, vision, a free second opinion from a different vendor, or a delegated build that comes back as a reviewable diff.

> No API keys · no token extraction · no Node · no daemon · stdlib + mcp only.

In one sentence

You're talking to one AI assistant. You've also installed and logged into others — Claude Code, Codex, Gemini, opencode, Ollama. cli-bridge connects them: when your assistant needs something it can't do alone, it asks one of the other CLIs and hands you the result.

The problem it solves

Whatever assistant you're using has hard limits. It can't read a 2M-token repo in one pass, can't see a screenshot, can't hand you a generated image, and can't check its own work without bias — but some other CLI on your machine can do each of those. cli-bridge is the bridge between them: it spawns the official CLI as a subprocess (exactly as you'd run it by hand — no keys, no token extraction) and returns the answer to your assistant.

The result: one assistant whose ceiling on every axis is the best tool in your toolbox, not the one you happened to open.

---

The 10-second demo

You're in Claude. Claude can't hand you an image. Codex can — natively with gpt-image-2, or by writing a script that renders one. For a precise layout like a social card, have it script and run it:

ask_build(lane="gpt", task="generate a 1200×630 social card to assets/card.png — write a script that renders it, then run it", zone="assets")
→ Codex writes assets/card.png · you get the path back, never a binary blob (artifact-return)

Your assistant just gained an ability it doesn't have. That's the whole idea — now scale it to giant-context reads, vision, parallel grunt-work, and independent cross-vendor verification.

(Codex generates the image with gpt-image-2, a real text-to-image model built into the CLI — counted against your ChatGPT plan's usage, no separate API key (image generation needs a paid plan; it's not on the Free tier). It comes back as a path, not a blob, because binaries travel by artifact-return, not the text channel. A build lane can also render charts, diagrams or SVGs by writing code, when that's the better fit.)

…and it delegates real work, safely

cli-bridge build "" hands the job to another model running in a throwaway git worktree, then gives you back a diff — your repo is never touched until you apply it yourself.

---

What you get — the four levers

cli-bridge isn't one feature, it's four abilities your assistant gains. Get these and every tool below slots into place:

1. Borrow — reach a capability your assistant lacks (vision, a 1M-token context window, a file a

coding agent generates, a model that's simply better at this).

1. Spread — when one subscription hits its limit, keep going on another lane you already pay for.
2. Offload — fan laborious, parallel grunt-work across cheap/free lanes while you build elsewhere.
3. Verify — have a different vendor family check the work, because a model can't catch its own

blind spots. This is the one thing a single-vendor tool structurally cannot do.

---

What this unlocks

Each block: one sentence of when you reach for it, the exact call, and what you get back.

Borrow abilities your assistant doesn't have

Every CLI has a different superpower, and each runs non-interactively — so cli-bridge can spawn it. Borrow the one your host lacks (it must be installed + logged in):

| Superpower | Which CLI has it | Borrow it when | |------------|------------------|----------------| | Images | Codex (gpt-image-2, no API key — paid ChatGPT plan, not Free) | your host can't draw | | Huge context | Gemini (1M-token window) | a file/repo won't fit your host's context | | Fresh knowledge | Gemini (Google-Search grounding) · Grok (live web/X) ⚗️ | beat a stale cutoff: "what's the current API of `?"* | | **Vision** | Gemini (images=[…]`) ⚗️ | analyse a screenshot or diagram | | A free second opinion | Gemini (free daily tier) · opencode · Ollama (local, $0) | a $0 cross-check | | Generated files | any build lane → artifact-return | get a chart / PDF / diagram back by path | | Video ⚗️ | Grok (Imagine) — if your installed CLI exposes it* (Veo isn't exposed by any official Gemini CLI extension) | you need a generated clip |

ask_build(lane="gpt", task="generate a 1200×630 social card to assets/card.png", zone="assets")   # Codex image → file by path, no API key (paid ChatGPT plan)
ask_gemini(task="find the bug across ./src — read the files you need", cwd="path/to/repo")         # 1M-token context
ask_gemini(task="what's the current recommended API for ? check the latest docs")            # fresh knowledge (Search grounding)
ask_gemini(task="what's wrong in this UI?", images=["screenshot.png"])                             # vision (experimental)

⚗️ = experimental / depends on the installed CLI's current build (e.g. Grok Build is beta) — verify with doctor --deep.

Never stop working when you hit a limit

When your main subscription caps out mid-task. ask_cascade falls through to another lane you already pay for, skipping any lane that's cooled down after a quota/auth/timeout error.

ask_cascade(task="finish wiring this endpoint")   # cheapest→strongest; a cooled-down lane is skipped
ask_best(task="…", mode="deep")                   # let the router pick the most suitable available lane

Offload the grunt work — in parallel, and cheap

When the work is laborious but not hard (refactors, migrations, test coverage). Fan it out, journaled so a server restart resumes instead of restarting; delegate a build and keep working.

batch_run(tasks=[...], dry_run=true)                       # cost envelope first — nothing is spawned
batch_run(tasks=[...], max_calls=20, max_credits=2.0)      # then run under a hard budget (resumable)
ask_build(lane="opencode", task="add the landing page", zone="frontend", mode="direct", async=true)   # delegate, keep building
job_tail(job_id="…")  ·  build_steer(job_id="…", instruction="use Tailwind, not inline CSS")

Break self-confirmation — the 2026 problem one vendor can't solve

When you need to trust a result. A model reviewing its own work (or a sibling's) just confirms its own blind spots. cli-bridge puts a different model family in the reviewer's seat.

workflow(preset="jury", task="is this migration safe?", author_lane="gpt")            # cross-family vote, fail-closed
workflow(preset="verify_repair", task="add retry with backoff",
         builder_lane="gpt", verifier_lane="gemini")                                   # A builds, B reviews, loop to green
security_review(base="origin/main")   ·   review_diff(base="origin/main")              # OWASP, severity-ranked

Get a real second opinion

When you've reached a conclusion and want it pressure-tested, or several models side by side.

challenge(task="I'm dropping the cache layer — here's why: …")                         # one skeptic attacks it
consensus(task="which migration strategy is safest here?")                             # N answer, peer-rank the best
workflow(preset="fanout_compare", task="fix this failing test", lanes=["gpt","gemini","opencode"])

---

The toolbox

~30 tools, grouped by intent — the headline ones:

• Consult (read-only): ask_ (one model), ask_all (every free lane in parallel + a disagreement score), ask_cascade (resilient fall-through), ask_best (router), consensus, challenge.
• Build (opt-in write): ask_build — mode=isolated→diff · mode=direct→zone-guarded · async→steerable, behind an executable Definition-of-Done gate.
• Review & verify: review_diff, security_review (findings tagged by severity and category — security / correctness / scope / ambiguity / performance / ops), debate, and workflow(preset=…) — converge (governance loop: an independent arbiter commits a blind verdict, anonymized cross-vendor peers review, every issue is adjudicated with a reason, then revise-or-converge), jury (cross-family k-of-N vote, fail-closed), verify_repair, fanout_compare, …
• Orchestrate & operate: batch_run (durable, budget-capped fan-out), plus usage_report, rate_lane, lane_stats, set_lane_cost, doctor.

Full reference — every tool, every flag: [docs/TOOLS.md](docs/TOOLS.md) (or cli-bridge --help). Run CLI_BRIDGE_LEAN=1 for a curated ~12-tool surface.

There's also a human CLI — cli-bridge doctor|ask|build|review-diff|eval|… — the same engine from your terminal or CI (--json everywhere); cli-bridge build "" returns a reviewable diff without touching your repo (--apply to land it as unstaged changes).

---

What you actually get when you combine them

One assistant whose ceiling on every axis is the ecosystem's best — not the tool you opened this morning: code with the strongest model, read ~1M tokens when yours is too short, answer with fresh knowledge past a stale cutoff, generate images/video, see screenshots, and fall back to a free/local lane when you're capped — spread across the subscriptions you already pay for.

The emergent property no single CLI has: true cross-vendor control — a different vendor in the reviewer's seat. Same-family subagents (Claude Code's, Grok's) can only self-confirm.

The honest seam: this unites capabilities, not mind — stateless spawns (no shared memory), spawn latency/cost, uneven quality, and the host always drives. It's orchestration, not fusion: you conduct specialists, you don't get one brain with every power.

→ Per-CLI strengths & limits (dated, churns fast): [docs/COMPARISON.md](docs/COMPARISON.md).

Why cli-bridge (and not another "call other models" MCP)

• 🛡️ Ban-safe by design. It spawns each model's official CLI, exactly as you'd run it by hand —

no OAuth-token extraction, no API-key reuse. Each CLI handles its own auth and billing.

• 💸 Cost-safe defaults you tune to your plan. Out of the box ask_all / ask_cascade build a

free council and never touch paid quota unless you ask. Each lane ships a tier sourced from the vendor's published plans (dated in [docs/COSTS.md](docs/COSTS.md), never detected from your account); override per lane with CLI_BRIDGE__COST=free|limited|paid. Two caps are enforced at spawn — CLI_BRIDGE__DAILY_LIMIT (runs/day, any lane) and CLI_BRIDGE_DAILY_CREDIT_CAP — full model in [docs/BUDGET.md](docs/BUDGET.md).

• 🔌 Works from any host. Claude Code, Codex, opencode, Cursor, VS Code (Cline/Continue), Zed —

anything that speaks MCP over stdio. The host's own lane is kept out of fan-out; hide it with CLI_BRIDGE_HIDE_HOST=1. Even a local model can be the host — see [examples/local-first-host.md](examples/local-first-host.md).

• 🧭 The cross-vendor edge is the moat. Independent verification means a different vendor in the

reviewer's seat — the scarce thing as AI writes a larger share of code, and exactly what a single-vendor tool can't offer.

Side by side

How the multi-model orchestrators differ on the axes that bite later — auth model, spend control, and what happens to your repo. (As of June 2026, read from each project's public repo/docs — corrections welcome.)

| | claude-octopus | PAL / zen-mcp | deliberation | cli-bridge | |---|---|---|---|---| | How other models are reached | hybrid: CLI spawn, OAuth-subscription reuse, or API keys | API keys (providers) + CLI spawn (clink) | CLI spawn (Codex/Gemini) + API keys (Grok, OpenRouter) | official CLI subprocess by default — each CLI keeps its own auth; optional opt-in API lanes | | API keys needed | optional fallback | for most providers | for Grok & OpenRouter | never by default — opt-in API lanes stay hidden until you set their key | | Spend control | session-only cost gate (OCTOPUS_MAX_COST_USD; no cross-session history) | none found | none found | enforced: per-lane daily run limit + daily credit cap + per-invocation budget, persisted ([docs/BUDGET.md](docs/BUDGET.md)) | | Consensus governance | — | — | blind verdict + mandatory reason for each dismissal | converge: blind arbiter verdict, reasoned adjudication, no-self-approval — over anonymized cross-vendor peers, all 3 guards enforced in code | | Delegated edits | in-place | in-place (bypass/yolo flags) | in-place (workspace-write experts) | throwaway worktree → diff (your repo untouched), or zone-guarded direct mode (+ opt-in read-only-write guard) | | Survives host restart / /compact | session-scoped state | in-memory threads (TTL) | opt-in on-disk; in-memory by default | sqlite: conversations, jobs, fan-out journal | | Runtime deps | Node 18+, npm, bash | Python + pip packages | Node 18+, npm | Python stdlib + mcp | | Hosts | Claude Code-first (plugin; MCP server secondary) | any MCP host | any MCP host (+ Claude Code plugin) | any MCP host (+ a Claude Code plugin) |

Where they're stronger, honestly: claude-octopus ships a much larger workflow surface (49 commands, 32 personas, CI reactions); PAL has the biggest community (~11.6k★) with a polished tool set; and deliberation is a focused, mature single-purpose governance tool that pioneered the blind-verdict / mandatory-dismissal-reason model — cli-bridge has since adopted exactly those guards as workflow preset=converge (and runs them over anonymized cross-vendor peers under enforced budgets), but deliberation remains the more specialized product for that one job. cli-bridge's bet is broader: ban-safe auth, enforced budgets, cross-vendor verification, and delegation that can't wreck your repo — verified by its own shipped eval instead of claimed.

---

How it works

host (Claude/Codex/…) ──MCP──> cli-bridge ──spawn──> official CLI ──> model
                                    │
       keeps the host's own lane out of fan-out · only shows installed, enabled CLIs
       kills the whole process tree on timeout/cancellation · redacts secrets
       classifies errors (auth/limit/failed) · spills huge output to a file

No network calls of its own. No keys stored. It runs the same binaries you already trust, in your working directory, and hands the answer back.

Real run, real-time: the Verify lever — security-review fans OWASP roles across several models in parallel (claude/gpt/opencode/ollama here); they flag a committed auth bypass blocker, and usage shows the receipts.

---

Writing code safely: two modes

Writes are contained, two ways — you pick review-gated or hands-off:

• isolated (default). Edits in a throwaway git worktree and hands back a diff. Your working

tree is never touched.

• direct. Writes real files, but only inside a zone you declare, behind a per-zone lock

with a post-turn zone-violation check. You in backend/, a delegate in frontend/, concurrently — neither can scribble across your whole repo; undo is zone-scoped, never a global reset.

And a tripwire for the read-only path: set CLI_BRIDGE_VERIFY_PLAN_READONLY=1 and any plan (read-only) delegate that nonetheless writes to a git workspace gets a ⚠️ WORKSPACE MUTATION DETECTED flag on its answer (surfac

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JoaoBerne
• Source: JoaoBerne/cli-bridge-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.