cli-bridge-mcp

cli-bridge

一个 Model Context Protocol 服务，让你正在对话的 AI 助手能够咨询安装在你机器上的其他 AI 命令行工具——Claude Code、Codex、Gemini、Mistral、opencode、Ollama、Apple fm 等。每个通道都会将官方命令行工具作为子进程启动：无需 API 密钥，不提取令牌，默认只读。

依赖：Python 标准库和 mcp（1.x 或 2.x）。无需守护进程。

功能

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

每次调用 ask_<lane> 都会返回一个线程 ID；可重复使用该 ID（也可切换到其他通道），进行可跨越 /compact 的多模型对话。conversations 可列出或重放线程。

工具

15 个固定工具，另有每个已安装命令行工具对应的一个 ask_<lane>：

• 咨询：ask_<lane>、ask_all、ask_cascade、ask_best、conversations、list_models
• 构建：ask_build（mode=isolated → 差异；mode=direct → 受区域保护的写入；使用 mode=direct 时，async=true → 可通过 job 调整）
• 审查：review_diff（focus=code|security）、debate（vote=judge|borda）、workflow（预设：refine_plan、map_review、research_verify、fanout_compare、converge、premortem、test_plan、challenge）、git_text（kind=commit|pr）
• 运维：job（action=status|result|cancel|list|tail|steer）、rate_lane、set_lane_cost、doctor、setup

CLI_BRIDGE_TOOLS=all 会添加 batch_run（带日志的扇出执行）和 reset_lane_state； CLI_BRIDGE_TOOLS=default,batch_run 会在默认工具基础上添加 batch_run；仅指定逗号分隔列表时，则只启用列表中的工具。 用量和通道健康状态是 MCP 资源（cli-bridge://usage-summary、cli-bridge://lane-stats）。 完整参考： docs/TOOLS.md。

此外还提供人工使用的命令行工具：cli-bridge doctor|ask|ask-all|ask-best|build|review-diff|security-review|test-plan|premortem|stats|usage|jobs|set-cost（适用时可使用 --json）。cli-bridge build <lane> "<task>" 会输出工作树差异；--apply 会将其应用为未暂存的更改。

安全编写代码

• isolated（默认）：委托方会在临时的 git 工作树中编辑，并返回差异。你的工作树不会受到影响。
• direct：会写入实际文件，但仅限于你声明的 zone，并通过每个区域的锁以及任务结束后的区域违规检查加以保护；撤销操作仅限于该区域。async=true 会使其可调整（job action=tail|steer），并使用可执行的完成定义（dod_cmd）。

CLI_BRIDGE_VERIFY_PLAN_READONLY=1 会标记只读委托方擅自写入文件的情况（不会回退更改）。重新进入的深度受限（CLI_BRIDGE_MAX_DEPTH，默认值为 1）。委托方会在调用方的 cwd 中运行；若未设置，则使用 CLI_BRIDGE_DEFAULT_CWD；再否则使用宿主的 MCP 工作区根目录。

安装

前提条件：Python 3.12+、uv 以及至少一个已安装并登录的 AI 命令行工具。

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

将其接入你的宿主：

• Claude Code：claude mcp add cli-bridge -- uvx cli-bridge-mcp（或使用插件：claude plugin marketplace add JoaoBerne/cli-bridge-mcp && claude plugin install cli-bridge@cli-bridge-mcp）。
• 其他 MCP 宿主（Codex、Cursor、VS Code、Zed、Claude Desktop 等）：

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

  各宿主的配置路径： docs/HOSTS.md。包含环境变量的完整示例： examples/mcp.example.json。图形界面宿主启动服务时使用的 PATH 通常很精简；cli-bridge 也会搜索常见安装目录，或者通过 CLI_BRIDGE_<LANE>_BIN=/full/path 指定通道对应的二进制文件。

重启宿主，然后让它咨询某个通道（“让 gemini 阅读 ./src 并找出 bug”）。 cli-bridge-mcp 是服务入口；cli-bridge 是人工使用的命令行工具。

配置

所有内容均通过环境变量（在 MCP 服务入口中设置）或 ~/.config/cli-bridge/config.json 配置（环境变量优先）。 重要的配置项：

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（或 doctor(deep=true)）会实时检查每个免费通道、其 CLI 版本及模型列表，并报告自上次深度探测以来的变化：每周运行一次，就能在委派失败前发现重命名的标志或新模型。

set_lane_cost（或 cli-bridge set-cost）会记录某个通道对你的费用，并将其保存到配置文件中。费用等级采用来源默认值，不会读取你的账户信息 （docs/COSTS.md）；完整的支出模型请参阅 docs/BUDGET.md。

通道

内置通道：Claude Code、Codex（gpt）、Gemini（+ Antigravity agy）、Mistral（Vibe）、opencode、Ollama（本地，$0）、Apple Foundation Models（fm，设备端，$0）、Qwen Code、Copilot、Cursor、Grok，以及 Apple PCC（设置 APPLE_FM_SERVE_URL 后才会显示——它会连接你在终端中自行启动的 fm serve；请参阅 examples/apple-fm-serve.lane.json）。

images=[…] 适用于支持视觉的通道（apple、ollama、opencode、gpt、gemini）；是否实际读取图像取决于通道背后的模型。

其他 CLI 只需通过 CLI_BRIDGE_LANES_FILE 提供几行 JSON： examples/local-runtime.lane.json（LM Studio、MLX、llama.cpp；运行时列表见 examples/local-first-host.md）、 examples/community-lanes.json（Aider、Goose、Plandex、Amp、Crush、Amazon Q、Droid），以及任何通过 curl 或随附的 cli-bridge-openai 桥接程序接入的 OpenAI 兼容端点（examples/openai-compatible.lane.json）。

已知限制

• 不会提取令牌或密钥，但并非所有地方都正式认可对供应商 CLI 的非交互式使用。
• 异步作业在进程内运行：服务重启会将运行中的作业标记为 interrupted。batch_run / workflow 会记录每项任务，并通过 resume_id 恢复。
• 注入防护采用启发式方法。 请将委派输出视为数据。
• 令牌/额度数据为估算值（字符数/4 × 你的 CREDITS_PER_1K）。
• 实验性通道（qwen、copilot、grok、社区通道、images=）：doctor --deep 会在你的机器上检查每个 CLI 的 --help。

开发

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

评测框架（在软件包之外运行的确定性评分器）：benchmarks/。 历史记录：CHANGELOG.md。目录结构和规则：AGENTS.md、docs/ARCHITECTURE.md。

许可证

Apache 2.0