io.github.JoaoBerne/cli-bridge-mcp

cli-bridge

A Model Context Protocol server that lets the AI assistant you're talking to consult the other AI CLIs installed on your machine — Claude Code, Codex, Gemini, Mistral, opencode, Ollama, Apple fm, … Each lane spawns the official CLI as a subprocess: no API keys, no token extraction, read-only by default.

Dependencies: the Python stdlib and mcp (1.x or 2.x). No daemon.

What it does

ask_gemini(task="find the bug across ./src", cwd="path/to/repo")     # one lane (1M-token context)
ask_apple(task="what's wrong in this UI?", images=["shot.png"])      # vision, on-device, $0
ask_all(task="…")                                                    # every free lane in parallel + disagreement score
ask_cascade(task="…")                                                # cheapest→strongest, skips cooled-down lanes
ask_best(task="…", mode="deep")                                      # router picks; rate_lane teaches it
ask_build(lane="opencode", task="add retry with backoff")            # build in a throwaway worktree → diff
review_diff(base="origin/main", focus="security")                    # multi-model review, severity-ranked
debate(task="which migration strategy?", vote="borda")               # N blind answers, peer-ranked
workflow(preset="converge", task="is this migration safe?")          # author → blind arbiter → cross-family peers
git_text(kind="commit")                                              # Conventional Commit from the staged diff

Every ask_<lane> returns a thread id; reuse it (even on another lane) for a multi-model conversation that survives /compact. conversations lists or replays threads.

Tools

15 fixed tools + one ask_<lane> per installed CLI:

• Consult: ask_<lane>, ask_all, ask_cascade, ask_best, conversations, list_models
• Build: ask_build (mode=isolated → diff, mode=direct → zone-guarded writes; with mode=direct, async=true → steerable via job)
• Review: review_diff (focus=code|security), debate (vote=judge|borda), workflow (presets: refine_plan, map_review, research_verify, fanout_compare, converge, premortem, test_plan, challenge), git_text (kind=commit|pr)
• Operate: job (action=status|result|cancel|list|tail|steer), rate_lane, set_lane_cost, doctor, setup

CLI_BRIDGE_TOOLS=all adds batch_run (journaled fan-out) and reset_lane_state; CLI_BRIDGE_TOOLS=default,batch_run extends the default; a plain comma list is exactly those. Usage and lane health are MCP resources (cli-bridge://usage-summary, cli-bridge://lane-stats). Full reference: docs/TOOLS.md.

There is also a human CLI, cli-bridge doctor|ask|ask-all|ask-best|build|review-diff|security-review|test-plan|premortem|stats|usage|jobs|set-cost (--json where it makes sense). cli-bridge build <lane> "<task>" prints the worktree diff; --apply lands it as unstaged changes.

Writing code safely

• isolated (default): the delegate edits a throwaway git worktree and you get a diff. Your tree is untouched.
• direct: writes real files, but only inside the zone you declare, behind a per-zone lock with a post-turn zone-violation check; undo is zone-scoped. async=true makes it steerable (job action=tail|steer) with an executable Definition-of-Done (dod_cmd).

CLI_BRIDGE_VERIFY_PLAN_READONLY=1 flags (never reverts) a read-only delegate that wrote files anyway. Re-entry is depth-capped (CLI_BRIDGE_MAX_DEPTH, default 1). Delegates run in the caller's cwd, else CLI_BRIDGE_DEFAULT_CWD, else the host's MCP workspace root.

Install

Prerequisites: Python 3.12+, uv, and at least one AI CLI installed and logged in.

uvx --from cli-bridge-mcp cli-bridge doctor        # what cli-bridge can see (--deep probes each lane)

Wire it into your host:

• Claude Code: claude mcp add cli-bridge -- uvx cli-bridge-mcp (or the plugin: claude plugin marketplace add JoaoBerne/cli-bridge-mcp && claude plugin install cli-bridge@cli-bridge-mcp).

• Any other MCP host (Codex, Cursor, VS Code, Zed, Claude Desktop, …):

  { "mcpServers": { "cli-bridge": { "command": "uvx", "args": ["cli-bridge-mcp"] } } }

  Per-host config paths: docs/HOSTS.md. Full example with env vars: examples/mcp.example.json. GUI hosts launch servers with a minimal PATH; cli-bridge also searches the usual install dirs, or point a lane at its binary with CLI_BRIDGE_<LANE>_BIN=/full/path.

Restart the host, then ask it to consult a lane ("ask gemini to read ./src and find the bug"). cli-bridge-mcp is the server entry point; cli-bridge is the human CLI.

Configuration

Everything is env (set in the MCP server entry) or ~/.config/cli-bridge/config.json (env wins). The knobs that matter:

CLI_BRIDGE_PROFILE=balanced            # saver = free-only fan-out · balanced = paid when asked · max = best
CLI_BRIDGE_<LANE>_COST=free|limited|paid
CLI_BRIDGE_<LANE>_ENABLED=false        # hide a lane
CLI_BRIDGE_<LANE>_MODEL=<model-id>
CLI_BRIDGE_<LANE>_DAILY_LIMIT=<runs/day>          # enforced at spawn
CLI_BRIDGE_<LANE>_CREDITS_PER_1K=<credits>        # makes CLI_BRIDGE_DAILY_CREDIT_CAP enforceable
CLI_BRIDGE_<LANE>_MIN_INTERVAL_S=2     # anti-burst pacing for a rate-limited free tier
CLI_BRIDGE_TERSE=off|lite|full|ultra
CLI_BRIDGE_GUARD=off|warn|strict       # injection guard on delegate output
CLI_BRIDGE_CACHE_TTL_S=0               # >0 enables the response cache
CLI_BRIDGE_TRACE_FOOTER=off            # hide the JSON trace footer in reports
CLI_BRIDGE_TOOLS=all                   # tool surface (see above)

doctor --deep (or doctor(deep=true)) live-checks every free lane, its CLI version and its model list, and reports what changed since the previous deep probe: run it weekly and you learn about a renamed flag or a new model before a delegation fails.

set_lane_cost (or cli-bridge set-cost) records what a lane costs you, persisted to the config file. Cost tiers are sourced defaults, never read from your account (docs/COSTS.md); the full spend model is in docs/BUDGET.md.

Lanes

Built-in: Claude Code, Codex (gpt), Gemini (+ Antigravity agy), Mistral (Vibe), opencode, Ollama (local, $0), Apple Foundation Models (fm, on-device, $0), Qwen Code, Copilot, Cursor, Grok, and Apple PCC (hidden until APPLE_FM_SERVE_URL is set — it talks to a fm serve you start from Terminal yourself; see examples/apple-fm-serve.lane.json).

images=[…] works on the vision lanes (apple, ollama, opencode, gpt, gemini); whether the image is actually read depends on the model behind the lane.

Other CLIs are a few lines of JSON via CLI_BRIDGE_LANES_FILE: examples/local-runtime.lane.json (LM Studio, MLX, llama.cpp; runtime table in examples/local-first-host.md), examples/community-lanes.json (Aider, Goose, Plandex, Amp, Crush, Amazon Q, Droid), and any OpenAI-compatible endpoint via curl or the bundled cli-bridge-openai bridge (examples/openai-compatible.lane.json).

Known limitations

• No token or key extraction, but non-interactive use of a vendor CLI isn't formally sanctioned everywhere.
• Async jobs are in-process: a server restart marks running jobs interrupted. batch_run / workflow journal each task and resume via resume_id.
• The injection guard is heuristic. Treat delegate output as data.
• Token/credit figures are estimates (chars/4 × your CREDITS_PER_1K).
• Experimental lanes (qwen, copilot, grok, community, images=): doctor --deep checks each CLI's --help on your machine.

Development

uv venv && uv pip install -e . pytest pytest-asyncio ruff
pytest -q            # no real CLI or network needed
ruff check src/ tests/

Eval harness (deterministic scorer, outside the package): benchmarks/. History: CHANGELOG.md. Layout and rules: AGENTS.md, docs/ARCHITECTURE.md.

License

Apache 2.0