{
  "markdown": "<!-- mcp-name: io.github.JoaoBerne/cli-bridge-mcp -->\n<div align=\"center\">\n\n<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\">\n\n**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)\n\n</div>\n\n# cli-bridge\n\n![CI](https://github.com/JoaoBerne/cli-bridge-mcp/actions/workflows/tests.yml/badge.svg)\n![PyPI](https://img.shields.io/pypi/v/cli-bridge-mcp)\n![stars](https://img.shields.io/github/stars/JoaoBerne/cli-bridge-mcp?style=flat&color=yellow)\n![python](https://img.shields.io/badge/python-3.10%2B-blue)\n![license](https://img.shields.io/badge/license-Apache%202.0-green)\n![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-server-purple)\n![ban--safe](https://img.shields.io/badge/ban--safe-no%20token%20extraction-orange)\n\n**Your assistant is only as good as the one model you opened.** cli-bridge is a\n[Model Context Protocol](https://modelcontextprotocol.io) server that lets it borrow the *other* AI\nCLIs you already run — a bigger context, vision, a free second opinion from a *different vendor*, or a\ndelegated build that comes back as a reviewable diff.\n\n> **No API keys · no token extraction · no Node · no daemon · stdlib + `mcp` only.**\n\n### In one sentence\n\nYou're talking to one AI assistant. You've also installed and logged into others — Claude Code,\nCodex, Gemini, opencode, Ollama. **cli-bridge connects them**: when your assistant needs something\nit can't do alone, it asks one of the other CLIs and hands you the result.\n\n### The problem it solves\n\nWhatever assistant you're using has hard limits. It can't read a 2M-token repo in one pass, can't\nsee a screenshot, can't hand you a generated image, and can't check its own work without bias — but\n*some other CLI on your machine can do each of those*. cli-bridge is the bridge between them: it\nspawns the official CLI as a subprocess (exactly as you'd run it by hand — no keys, no token\nextraction) and returns the answer to your assistant.\n\nThe result: one assistant whose ceiling on every axis is the *best* tool in your toolbox, not the\none you happened to open.\n\n---\n\n## The 10-second demo\n\nYou're in Claude. Claude can't hand you an image. Codex can — natively with `gpt-image-2`, or by\nwriting a script that renders one. For a precise layout like a social card, have it script and run it:\n\n```\nask_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\")\n→ Codex writes assets/card.png · you get the path back, never a binary blob (artifact-return)\n```\n\nYour assistant just gained an ability it doesn't have. That's the whole idea — now scale it to\ngiant-context reads, vision, parallel grunt-work, and independent cross-vendor verification.\n\n_(Codex generates the image with **`gpt-image-2`**, a real text-to-image model built into the CLI —\ncounted against your ChatGPT plan's usage, no separate API key (image generation needs a **paid**\nplan; it's not on the Free tier). It comes back as a **path**, not a blob, because binaries travel by\nartifact-return, not the text channel. A build lane can also *render* charts, diagrams or SVGs by\nwriting code, when that's the better fit.)_\n\n### …and it delegates real work, safely\n\n`cli-bridge build <lane> \"<task>\"` hands the job to another model running in a **throwaway git\nworktree**, then gives you back a **diff** — your repo is never touched until you apply it yourself.\n\n<p align=\"center\">\n<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\">\n</p>\n\n---\n\n## What you get — the four levers\n\ncli-bridge isn't one feature, it's **four abilities your assistant gains**. Get these and every tool\nbelow slots into place:\n\n1. **Borrow** — reach a capability your assistant lacks (vision, a 1M-token context window, a file a\n   coding agent generates, a model that's simply better at *this*).\n2. **Spread** — when one subscription hits its limit, keep going on another lane you already pay for.\n3. **Offload** — fan laborious, parallel grunt-work across cheap/free lanes while you build elsewhere.\n4. **Verify** — have a *different vendor family* check the work, because a model can't catch its own\n   blind spots. This is the one thing a single-vendor tool structurally cannot do.\n\n---\n\n## What this unlocks\n\nEach block: one sentence of *when you reach for it*, the exact call, and *what you get back*.\n\n### Borrow abilities your assistant doesn't have\nEvery CLI has a different superpower, and each runs non-interactively — so cli-bridge can spawn it.\nBorrow the one your host lacks (it must be installed + logged in):\n\n| Superpower | Which CLI has it | Borrow it when |\n|------------|------------------|----------------|\n| **Images** | Codex (`gpt-image-2`, **no API key** — paid ChatGPT plan, not Free) | your host can't draw |\n| **Huge context** | Gemini (1M-token window) | a file/repo won't fit your host's context |\n| **Fresh knowledge** | Gemini (Google-Search grounding) · Grok (live web/X) ⚗️ | beat a stale cutoff: *\"what's the current API of `<lib>`?\"* |\n| **Vision** | `images=[…]` on Codex · opencode · Ollama · Apple · Gemini ⚗️ | analyse a screenshot or diagram |\n| **A free second opinion** | opencode · Ollama · Apple (local, $0) · Gemini (scarce free tier) | a $0 cross-check |\n| **Generated files** | any build lane → artifact-return | get a chart / PDF / diagram back **by path** |\n| **Video** ⚗️ | Grok (Imagine) — *if your installed CLI exposes it* (Veo isn't exposed by any official Gemini CLI extension) | you need a generated clip |\n\n```\nask_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)\nask_gemini(task=\"find the bug across ./src — read the files you need\", cwd=\"path/to/repo\")         # 1M-token context\nask_gemini(task=\"what's the current recommended API for <lib>? check the latest docs\")            # fresh knowledge (Search grounding)\nask_apple(task=\"what's wrong in this UI?\", images=[\"screenshot.png\"])                             # vision, on-device, $0, offline\n```\n\n**Vision, honestly:** `images=[…]` is no longer one vendor's feature. Five lanes take it and each\nlane declares its own shape as data, so you always just pass paths — an argv flag (`apple --image`,\n`gpt -i`, `opencode -f`) or a path folded into the prompt (`gemini @path`, `ollama` bare); a sixth\nlane is one field, not a code path. Caveat: whether the image is actually *read* depends on the\n**model** behind the lane, not the lane — on the same test image one free model transcribed every\nline and another answered *\"model lacks vision\"*. Full table in [`docs/TOOLS.md`](docs/TOOLS.md).\n\n⚗️ = experimental / depends on the installed CLI's current build (e.g. Grok Build is beta) — verify with `doctor --deep`.\n\n### Never stop working when you hit a limit\nWhen your main subscription caps out mid-task. `ask_cascade` falls through to another lane you already\npay for, skipping any lane that's cooled down after a quota/auth/timeout error.\n\n```\nask_cascade(task=\"finish wiring this endpoint\")   # cheapest→strongest; a cooled-down lane is skipped\nask_best(task=\"…\", mode=\"deep\")                   # let the router pick the most suitable available lane\n```\n\n### Offload the grunt work — in parallel, and cheap\nWhen the work is laborious but not hard (refactors, migrations, test coverage). Fan it out, journaled\nso a server restart resumes instead of restarting; delegate a build and keep working.\n\n```\nbatch_run(tasks=[...], dry_run=true)                       # cost envelope first — nothing is spawned\nbatch_run(tasks=[...], max_calls=20, max_credits=2.0)      # then run under a hard budget (resumable)\nask_build(lane=\"opencode\", task=\"add the landing page\", zone=\"frontend\", mode=\"direct\", async=true)   # delegate, keep building\njob_tail(job_id=\"…\")  ·  build_steer(job_id=\"…\", instruction=\"use Tailwind, not inline CSS\")\n```\n\n### Break self-confirmation — the 2026 problem one vendor can't solve\nWhen you need to *trust* a result. A model reviewing its own work (or a sibling's) just confirms its\nown blind spots. cli-bridge puts a **different model family** in the reviewer's seat.\n\n```\nworkflow(preset=\"jury\", task=\"is this migration safe?\", author_lane=\"gpt\")            # cross-family vote, fail-closed\nworkflow(preset=\"verify_repair\", task=\"add retry with backoff\",\n         builder_lane=\"gpt\", verifier_lane=\"gemini\")                                   # A builds, B reviews, loop to green\nsecurity_review(base=\"origin/main\")   ·   review_diff(base=\"origin/main\")              # OWASP, severity-ranked\n```\n\n### Get a real second opinion\nWhen you've reached a conclusion and want it pressure-tested, or several models side by side.\n\n```\nchallenge(task=\"I'm dropping the cache layer — here's why: …\")                         # one skeptic attacks it\nconsensus(task=\"which migration strategy is safest here?\")                             # N answer, peer-rank the best\nworkflow(preset=\"fanout_compare\", task=\"fix this failing test\", lanes=[\"gpt\",\"gemini\",\"opencode\"])\n```\n\n---\n\n## The toolbox\n\n~30 tools, grouped by intent — the headline ones:\n\n- **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`.\n- **Build** (opt-in write): `ask_build` — `mode=isolated`→diff · `mode=direct`→zone-guarded · `async`→steerable, behind an executable Definition-of-Done gate.\n- **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`, …\n- **Orchestrate & operate**: `batch_run` (durable, budget-capped fan-out), plus `usage_report`, `rate_lane`, `lane_stats`, `set_lane_cost`, `doctor`.\n\n**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.\n\nThere'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 <lane> \"<task>\"` returns a reviewable **diff** without touching your repo (`--apply` to land it as unstaged changes).\n\n---\n\n## What you actually get when you combine them\n\nOne assistant whose ceiling on **every axis is the ecosystem's best** — not the tool you opened this\nmorning: code with the strongest model, read ~1M tokens when yours is too short, answer with fresh\nknowledge past a stale cutoff, generate images/video, see screenshots, and fall back to a free/local\nlane when you're capped — spread across the subscriptions you already pay for.\n\nThe emergent property **no single CLI has: true cross-vendor control** — a *different vendor* in the\nreviewer's seat. Same-family subagents (Claude Code's, Grok's) can only self-confirm.\n\nThe honest seam: this unites **capabilities, not mind** — stateless spawns (no shared memory), spawn\nlatency/cost, uneven quality, and the host always drives. It's **orchestration, not fusion**: you\nconduct specialists, you don't get one brain with every power.\n\n→ Per-CLI strengths & limits (dated, churns fast): **[docs/COMPARISON.md](docs/COMPARISON.md)**.\n\n## Why cli-bridge (and not another \"call other models\" MCP)\n\n- 🛡️ **Ban-safe by design.** It spawns each model's **official CLI**, exactly as you'd run it by hand —\n  no OAuth-token extraction, no API-key reuse. Each CLI handles its own auth and billing.\n- 💸 **Cost-safe defaults you tune to your plan.** Out of the box `ask_all` / `ask_cascade` build a\n  *free* council and never touch paid quota unless you ask. Each lane ships a tier sourced from the\n  vendor's published plans (dated in [docs/COSTS.md](docs/COSTS.md), **never detected from your\n  account**); override per lane with `CLI_BRIDGE_<LANE>_COST=free|limited|paid`. Two caps are\n  **enforced at spawn** — `CLI_BRIDGE_<LANE>_DAILY_LIMIT` (runs/day, any lane) and\n  `CLI_BRIDGE_DAILY_CREDIT_CAP` — full model in [docs/BUDGET.md](docs/BUDGET.md).\n- 🔌 **Works from any host.** Claude Code, Codex, opencode, Cursor, VS Code (Cline/Continue), Zed —\n  anything that speaks MCP over stdio. The host's own lane is kept out of fan-out; hide it with\n  `CLI_BRIDGE_HIDE_HOST=1`. Even a **local model can be the host** — see\n  [`examples/local-first-host.md`](examples/local-first-host.md).\n- 🧭 **The cross-vendor edge is the moat.** Independent verification means a *different vendor* in the\n  reviewer's seat — the scarce thing as AI writes a larger share of code, and exactly what a\n  single-vendor tool can't offer.\n\n### Side by side\n\nHow the multi-model orchestrators differ on the axes that bite later — auth model, spend control,\nand what happens to your repo. (As of June 2026, read from each project's public repo/docs —\ncorrections welcome.)\n\n|  | [claude-octopus](https://github.com/nyldn/claude-octopus) | [PAL / zen-mcp](https://github.com/BeehiveInnovations/zen-mcp-server) | [deliberation](https://github.com/antonbabenko/deliberation) | **cli-bridge** |\n|---|---|---|---|---|\n| **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 |\n| **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 |\n| **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)) |\n| **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 |\n| **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) |\n| **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 |\n| **Runtime deps** | Node 18+, npm, bash | Python + pip packages | Node 18+, npm | **Python stdlib + `mcp`** |\n| **Hosts** | Claude Code-first (plugin; MCP server secondary) | any MCP host | any MCP host (+ Claude Code plugin) | any MCP host (+ a Claude Code plugin) |\n\nWhere they're stronger, honestly: claude-octopus ships a much larger workflow surface (49 commands,\n32 personas, CI reactions); PAL has the biggest community (~11.6k★) with a polished tool set; and\n**deliberation** is a focused, mature single-purpose governance tool that pioneered the\nblind-verdict / mandatory-dismissal-reason model — cli-bridge has since adopted exactly those guards\nas `workflow preset=converge` (and runs them over *anonymized cross-vendor* peers under enforced\nbudgets), but deliberation remains the more specialized product for that one job. cli-bridge's bet is\nbroader: **ban-safe auth, enforced budgets, cross-vendor verification, and delegation that can't wreck\nyour repo** — verified by its own shipped eval instead of claimed.\n\n---\n\n## How it works\n\n```\nhost (Claude/Codex/…) ──MCP──> cli-bridge ──spawn──> official CLI ──> model\n                                    │\n       keeps the host's own lane out of fan-out · only shows installed, enabled CLIs\n       kills the whole process tree on timeout/cancellation · redacts secrets\n       classifies errors (auth/limit/failed) · spills huge output to a file\n```\n\nNo network calls of its own. No keys stored. It runs the same binaries you already trust, in your\nworking directory, and hands the answer back.\n\n<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/JoaoBerne/cli-bridge-mcp/main/assets/demo.gif\" width=\"860\" alt=\"cli-bridge security-review demo: a committed auth bypass is caught by a cross-vendor council, merged into one severity-ranked report, $0 on free lanes\">\n\n_Real run, real-time: the Verify lever — `security-review` fans OWASP roles across several models\nin parallel (claude/gpt/opencode/ollama here); they flag a committed auth bypass **blocker**, and\n`usage` shows the receipts._\n\n</div>\n\n<details>\n<summary><b>The report it actually prints</b> — real run, $0 free lanes, reproducible in 2 commands</summary>\n\n<br>\n\nTwo *different vendors* independently flag the same bypass — that's the point: uncorrelated blind\nspots, not one model's opinion. Note what it does **not** hide: a reviewer came back empty, so the\nrecap says `3/4 answered` and the residual-risk line names the category nobody assessed.\n\n```\n# Security review (OWASP-aware)\n\n_Base: `HEAD~1` · reviewers: injection (Mistral (Vibe CLI)), auth & access control (OpenCode\n(gateway to many models)), data exposure & SSRF (OpenCode (gateway to many models)) · read-only_\n\n## Reviewers — 3/4 answered\n\n- ✅ **injection (Mistral (Vibe CLI))** _10927ms_ — 1 finding(s)\n- ✅ **auth & access control (OpenCode (gateway to many models))** _13875ms_ — 1 finding(s)\n- ❌ **secrets & crypto (Mistral (Vibe CLI))** _8465ms_ — empty\n- ✅ **data exposure & SSRF (OpenCode (gateway to many models))** _11792ms_ — 0 finding(s)\n\n**2 findings** (1 blocker, 1 high) — _block — blocker-level issues must be fixed before merge_\n\n_By type: 2 security_\n\n## Blocker\n\n- **Unauthenticated user granted admin access** `auth.py:3` — _single_ · OpenCode · _security_\n  require_admin returns True when user is None, meaning any unauthenticated/anonymous caller is\n  treated as admin. This bypasses the is_admin check entirely.\n  **Fix:** If user is None: raise PermissionError('authentication required')\n\n## High\n\n- **Insecure default for anonymous users** `auth.py:3` — _single_ · Mistral (Vibe CLI) · _security_\n  The function returns True for user=None, granting admin privileges to unauthenticated sessions.\n  This allows anonymous users to bypass admin checks.\n  **Fix:** Remove the `if user is None: return True` block and let the function raise\n  PermissionError for anonymous users.\n\n## Residual risk\n\nTreat with care — reviewer role(s) failed (secrets & crypto=empty); their categories are\nunassessed; this is a static review of the shown diff only — no runtime, dependency, or\ndeployment/secrets-config analysis was performed.\n```\n\nReproduce it on the throwaway fixture (a committed `if user is None: return True`, built in `/tmp`):\n\n```bash\nsh docs/demo/setup.sh                 # creates /tmp/demo-authz\ncd /tmp/demo-authz && cli-bridge security-review --base HEAD~1\n```\n\n_(Trace footer omitted — `CLI_BRIDGE_TRACE_FOOTER=off`. Lanes vary with what you have logged in.)_\n\n</details>\n\n---\n\n## Writing code safely: two modes\n\nWrites are contained, two ways — **you pick** review-gated or hands-off:\n\n- **`isolated` (default).** Edits in a throwaway git worktree and hands back a **diff**. Your working\n  tree is never touched.\n- **`direct`.** Writes real files, **but only inside a `zone` you declare**, behind a per-zone lock\n  with a post-turn zone-violation check. You in `backend/`, a delegate in `frontend/`, concurrently —\n  neither can scribble across your whole repo; undo is zone-scoped, never a global reset.\n\nAnd a tripwire for the *read-only* path: set `CLI_BRIDGE_VERIFY_PLAN_READONLY=1` and any `plan`\n(read-only) delegate that nonetheless writes to a git workspace gets a `⚠️ WORKSPACE MUTATION DETECTED`\nflag on its answer (surfaced, never auto-reverted — you decide).\n\nDelegate re-entry is depth-capped (`CLI_BRIDGE_MAX_DEPTH`, default 1) so a misconfigured delegate\ncan't fork-bomb the council.\n\n**Where a delegate runs.** Pass `cwd` and that wins. Leave it out and cli-bridge asks the host for\nits **MCP workspace root** — because hosts launch a user-scoped MCP server from your home\ndirectory, so the directory it inherits is an accident, and it decides both where an unscoped\n`build` delegate writes and where the delegate's own session file gets filed. Override with\n`CLI_BRIDGE_DEFAULT_CWD` if your host declares no roots.\n\n---\n\n## Installation (≈5 min)\n\n**Prerequisites**\n\n- **Python 3.10+** and **[`uv`](https://docs.astral.sh/uv/)** (`uvx` ships with it):\n  `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) · `winget install astral-sh.uv` (Windows).\n- **At least one AI CLI installed and logged in** — that's what cli-bridge borrows. Have any of:\n  Claude Code, Codex, Gemini CLI, opencode, Ollama (local, $0). You consult only the lanes you already have.\n\n**1. Check what cli-bridge can see** (no install — `uvx` fetches, runs, discards):\n\n```bash\nuvx --from cli-bridge-mcp cli-bridge doctor\n```\n\n`doctor` lists which CLIs are detected, their resolved paths, and cost tiers. `doctor --deep`\nvalidates each lane against its own `--help`.\n\n**2. Add it to your MCP host.** cli-bridge is an MCP server — it runs *inside* your assistant, not by\nhand. Point the host at the same command:\n\n- **Claude Code — as a plugin** (one-time, adds `/cli-bridge:council`, `/cli-bridge:review`,\n  `/cli-bridge:security`, `/cli-bridge:build`, `/cli-bridge:setup` and wires the MCP server):\n  ```bash\n  claude plugin marketplace add JoaoBerne/cli-bridge-mcp\n  claude plugin install cli-bridge@cli-bridge-mcp\n  ```\n- **Claude Code — MCP only** (no slash commands):\n  ```bash\n  claude mcp add cli-bridge -- uvx cli-bridge-mcp\n  ```\n- **Desktop apps — Claude Desktop, Hermes Desktop, …** cli-bridge is a plain stdio MCP\n  server, so any desktop MCP client runs it:\n  - **Claude Desktop**: Settings → Developer → Edit Config (`claude_desktop_config.json`),\n    add the `mcpServers` block below, restart the app.\n  - **Hermes Desktop** (Nous Research): Settings → MCP servers → Add → command `uvx`,\n    args `cli-bridge-mcp`.\n  - GUI apps launch servers with a **minimal PATH** — cli-bridge compensates by also\n    searching the usual install dirs (`/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`,\n    `~/.npm-global/bin`, …) for your CLIs. If a lane still shows \"NOT on PATH\" in `doctor`,\n    point it directly: `CLI_BRIDGE_<LANE>_BIN=/full/path/to/cli` in the server's `env`.\n- **Any other host** (Codex, Cursor, VS Code, Zed, …) — add to its MCP config\n  (`~/.claude.json`, `.mcp.json`, or the host's equivalent):\n  ```json\n  {\n    \"mcpServers\": {\n      \"cli-bridge\": {\n        \"command\": \"uvx\",\n        \"args\": [\"cli-bridge-mcp\"]\n      }\n    }\n  }\n  ```\n  Full example with env vars: [`examples/mcp.example.json`](examples/mcp.example.json).\n  Per-host config paths (Cursor, VS Code, Cline, Windsurf, Continue, Zed, Visual Studio, Neovim,\n  Xcode) and how to make your agent consult it on its own: [`docs/HOSTS.md`](docs/HOSTS.md).\n\n> Note: `cli-bridge-mcp` (the MCP server) is the host entry point; `cli-bridge` (no `-mcp`) is the\n> human terminal CLI you ran for `doctor` in step 1.\n\n**3. Use it.** Restart/reload your host and ask it to consult a lane — e.g. *\"use cli-bridge to get a\nsecond opinion from gpt\"* or *\"ask gemini to read ./src and find the bug\"*.\n\n### Lanes\n\n**Built-in:** Claude Code, Codex, Gemini (+ Antigravity `agy`), Mistral (Vibe), opencode, **Ollama\n(local models, $0, offline)**, **Apple Foundation Models (`fm`, on-device, $0, offline, unmetered)**,\nQwen Code, Copilot, Cursor (`cursor-agent`), Grok, and two opt-in lanes that stay hidden until you set\ntheir env var (so the ban-safe default surface is unchanged): **OpenRouter** (400+ models, needs\n`OPENROUTER_API_KEY`) and **Apple PCC** (`APPLE_FM_SERVE_URL`).\n\n> Apple PCC talks to a local `fm serve` over HTTP. `fm` refuses PCC to anything cli-bridge spawns —\n> it walks the caller's ancestry to the session boundary and checks that ancestor's code signature —\n> so start the server through Terminal instead, which you can do from anywhere, including from your\n> assistant: `osascript -e 'tell application \"Terminal\" to do script \"fm serve --port 1976\"'`.\n> Terminal becomes the parent, which is the chain `fm` trusts. Same HTTP pattern serves llama.cpp /\n> vLLM / LM Studio — the bundled `cli-bridge-openai` bridge now works keyless.\n> See [`examples/apple-fm-serve.lane.json`](examples/apple-fm-serve.lane.json).\n\n**Local runtimes** beyond Ollama — **LM Studio · MLX · llama.cpp** — ship as zero-code recipes:\npoint `CLI_BRIDGE_LANES_FILE` at [`examples/lmstudio.lane.json`](examples/lmstudio.lane.json),\n[`mlx.lane.json`](examples/mlx.lane.json), or [`llamacpp.lane.json`](examples/llamacpp.lane.json).\n(Several local runtimes of the *same* open weights give correlated answers — real council diversity\ncomes from distinct vendors, not a second local runtime.)\n\n**Community lanes** (`examples/community-lanes.json`, experimental + `limited` until you declare their\ncost): Aider, Goose, Plandex, Amp, Crush, Amazon Q Developer CLI, Droid.\n\n**Anything else is ~3 lines of JSON.** Add a custom lane, or wrap any OpenAI-compatible endpoint two\nways: spawn `curl` (key kept inside curl, never in argv), or use the bundled **`cli-bridge-openai`**\nstdlib bridge — set `availability_env` so the lane stays hidden until its key is exported. See\n[`examples/openai-compatible.lane.json`](examples/openai-compatible.lane.json) and\n[`examples/`](examples/) for recipes.\n\n---\n\n## The honest part\n\n\"More models = better\" is *fragile* — big models share training data, so their errors correlate. We\nmeasured our own central claim (`cli-bridge eval`, no LLM judge): a diverse council did **not** catch\nmore bugs than one strong model — it cut the false alarms **~2×**. Same catch rate, far less noise —\nwhich is exactly what keeps a reviewer trustworthy instead of muted. **Precision is the product, not\nrecall.** The harness ships, so you can confirm it on *your* CLIs — numbers either way in\n[docs/BENCHMARKS.md](docs/BENCHMARKS.md).\n\n---\n\n## Known limitations\n\n- **Ban-safe = no token/key extraction**, not a blanket guarantee — non-interactive use of a\n  provider's CLI isn't formally sanctioned everywhere and can change. Use your own accounts within\n  their terms.\n- **Async jobs are in-process** — a server restart marks running jobs `interrupted`. `batch_run` /\n  `workflow` are the exception: they journal each task and resume via `resume_id`.\n- **The injection guard is heuristic** — it catches high-signal patterns, not everything; treat\n  delegate output as data, not instructions.\n- **Token/credit figures are estimates** (chars/4 + your `CREDITS_PER_1K`), never exact.\n- **Cost tiers are sourced defaults, not detection** — vendor-plan facts are dated; `doctor` warns\n  when the snapshot is stale.\n- **Experimental** (`qwen`, `copilot`, `grok`, community lanes, `images=`): flags aren't\n  verified live — `doctor --deep` checks them against each CLI's `--help` on your machine.\n\n---\n\n## Roadmap\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for shipped history. Currently **exploring (not shipped)**: an\n**independent-oracle** verify mode (a cross-family lane writes tests from the *spec*, blind to the\nimplementation, so the test catches the bug instead of mirroring it) and tighter **limit-aware\nfailover**. Big inter-agent \"bus\" ideas (recursive spawn, shared state, wire protocol) are positioned\nhonestly as a *direction*, never sold as a shipped protocol — see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\n---\n\n## References\n\nThe design choices above aren't vibes — each maps to a finding in the literature. Every entry was\nchecked against its source (authors + venue), because a tool that sells \"honest cross-vendor\nverification\" should get its own citations right.\n\n| Paper | ID | What it backs here |\n|-------|----|--------------------|\n| Du et al. — *Improving Factuality and Reasoning via Multiagent Debate* | [2305.14325](https://arxiv.org/abs/2305.14325) | `debate`: models critiquing each other beat one model alone |\n| ReConcile — *Round-Table Conference Improves Reasoning* | [2309.13007](https://arxiv.org/abs/2309.13007) | `debate` convergence + confidence-weighted consensus |\n| Mixture-of-Agents | [2406.04692](https://arxiv.org/abs/2406.04692) | layered aggregation across diverse models (and its limits) |\n| Chain-of-Agents | [2406.02818](https://arxiv.org/abs/2406.02818) | role-specialized multi-agent pipelines |\n| CriticGPT — *LLM Critics Help Catch LLM Bugs* | [2407.00215](https://arxiv.org/abs/2407.00215) | `review_diff` / `security_review`: an LLM critic catches bugs humans miss |\n| Perez et al. — *Discovering Language Model Behaviors* (sycophancy) | [2212.09251](https://arxiv.org/abs/2212.09251) | why a same-family judge is weak → cross-vendor `jury` + peer anonymization |\n| Wynn, Satija & Hadfield — *Talk Isn't Always Cheap* | [2509.05396](https://arxiv.org/abs/2509.05396) | debate failure modes → fail-closed verdicts, bounded rounds |\n| CONSENSAGENT — *Consensus via Sycophancy Mitigation* (Findings of ACL 2025) | [ACL 2025](https://aclanthology.org/2025.findings-acl.1141/) | sycophancy in consensus → \"earn their seat\" / anonymized peers |\n| Maryanskyy — *When Agents Disagree: The Selection Bottleneck* | [2603.20324](https://arxiv.org/abs/2603.20324) | `consensus`: **selection > synthesis** (the deterministic peer-vote default) |\n\n> **A citation hygiene note.** *Talk Isn't Always Cheap* (2509.05396) is **Wynn, Satija & Hadfield** —\n> a popular council framework miscites it as \"Xiong et al.\" We double-check attributions before\n> repeating them, and flag it because honesty is the whole pitch.\n\n## Development\n\n```bash\nuv venv && uv pip install -e . pytest pytest-asyncio\npytest -q          # unit + integration (cross-host) tests; no real CLI or network needed\n```\n\n## License\n\nApache 2.0\n\n---\n\n<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/JoaoBerne/cli-bridge-mcp/main/assets/mark.gif\" width=\"84\" alt=\"cli-bridge\">\n\n<sub>one side · bridged to a council</sub>\n\n</div>\n",
  "bytes": 30854,
  "sha": "a98dc852dc6dc3db0cb8a09426271738a551c2aab40cce5b39b149a789bae676",
  "repo_slug": "joaoberne/cli-bridge-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_joaoberne_cli_bridge_mcp_0e0ad5cd/readme"
}