cli-bridge-mcp

<!-- mcp-name: io.github.JoaoBerne/cli-bridge-mcp -->
<div align="center">

<img src="https://raw.githubusercontent.com/JoaoBerne/cli-bridge-mcp/main/assets/banner.gif" width="860" alt="cli-bridge — your assistant borrows the powers of every AI CLI you already have: huge-context reads, vision, parallel builds, cross-vendor checks">

**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)

</div>

# cli-bridge

![CI](https://github.com/JoaoBerne/cli-bridge-mcp/actions/workflows/tests.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/cli-bridge-mcp)
![stars](https://img.shields.io/github/stars/JoaoBerne/cli-bridge-mcp?style=flat&color=yellow)
![python](https://img.shields.io/badge/python-3.10%2B-blue)
![license](https://img.shields.io/badge/license-Apache%202.0-green)
![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-server-purple)
![ban--safe](https://img.shields.io/badge/ban--safe-no%20token%20extraction-orange)

**Your assistant is only as good as the one model you opened.** cli-bridge is a
[Model Context Protocol](https://modelcontextprotocol.io) 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 <lane> "<task>"` 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.

<p align="center">
<img src="https://raw.githubusercontent.com/JoaoBerne/cli-bridge-mcp/main/assets/demo-borrow.gif" width="860" alt="cli-bridge build: opencode adds a function in a throwaway worktree and returns a reviewable diff; the real repo stays clean">
</p>

---

## 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*).
2. **Spread** — when one subscription hits its limit, keep going on another lane you already pay for.
3. **Offload** — fan laborious, parallel grunt-work across cheap/free lanes while you build elsewhere.
4. **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 `<lib>`?"* |
| **Vision** | `images=[…]` on Codex · opencode · Ollama · Apple · Gemini ⚗️ | analyse a screenshot or diagram |
| **A free second opinion** | opencode · Ollama · Apple (local, $0) · Gemini (scarce free tier) | 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 <lib>? check the latest docs")            # fresh knowledge (Search grounding)
ask_apple(task="what's wrong in this UI?", images=["screenshot.png"])                             # vision, on-device, $0, offline
```

**Vision, honestly:** `images=[…]` is no longer one vendor's feature. Five lanes take it and each
lane declares its own shape as data, so you always just pass paths — an argv flag (`apple --image`,
`gpt -i`, `opencode -f`) or a path folded into the prompt (`gemini @path`, `ollama` bare); a sixth
lane is one field, not a code path. Caveat: whether the image is actually *read* depends on the
**model** behind the lane, not the lane — on the same test image one free model transcribed every
line and another answered *"model lacks vision"*. Full table in [`docs/TOOLS.md`](docs/TOOLS.md).

⚗️ = 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_<lane>` (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-