cli-bridge

cli-bridge

If you want agents to actually use your CLI, this is the missing piece.

Project page: https://projects.mioli.dev/cli-bridge/ · Blog: https://blog.mioli.dev · Author: Stefano Mioli

You wrote the CLI, you mentioned it in CLAUDE.md, the agent used it twice and then went back to Bash. cli-bridge solves that by registering your tool's commands as real MCP tools that live in the agent's tool registry — outside the context window, where they don't decay under conversation pressure.

The problem

You built a CLI that does something useful. Maybe it queries a database, lints code, or manages infrastructure. You tell the agent about it in CLAUDE.md or your system prompt. It works for a while, then the agent quietly goes back to grep and Bash.

This happens because text instructions sit in the context window, and context is a lossy channel. When the conversation gets long or the task gets complex, the agent forgets your tool exists. It falls back to what it knows: shell commands.

MCP tools don't have this problem. They live outside the context window, in the tool registry. The agent sees them every time it decides which tool to call, regardless of how long the conversation is or how much pressure the context is under.

What cli-bridge does

cli-bridge lets you describe your CLI's interface in a JSON spec file. On startup, it reads the spec and registers each subcommand as a real MCP tool. The agent sees tool_foo and tool_bar in its tool list, not buried in a CLAUDE.md paragraph it might skip.

When the agent calls one of these tools, cli-bridge runs your binary via execFile (no shell), parses the output according to the spec, and returns structured content. Your CLI stays a CLI. It just also happens to be an MCP tool now.

This works with Claude Code, Codex, and anything else that speaks MCP.

Install

There are two paths. Pick one — they're not sequential.

Path A — Plugin (Claude Code, recommended)

One command, gets you the binary + MCP server registration + the /cli-bridge:register slash command:

/plugin marketplace add walkindude/cli-bridge
/plugin install cli-bridge@cli-bridge

Skip the rest of this section.

Path B — Standalone (npm / Codex / other MCP clients)

If you're not on Claude Code, or you want the binary without the plugin scaffolding:

1. Install the binary. Pick whichever fits:

npm install -g cli-bridge          # or pnpm / yarn / bun
mise use -g npm:cli-bridge@latest  # via mise
nix profile install github:walkindude/cli-bridge  # via nix

For source builds: git clone … && pnpm install && pnpm run build && npm link.

2. Register as an MCP server. For Claude Code, the canonical command is one line:

claude mcp add cli-bridge -s user -- cli-bridge

Or by hand — add to ~/.claude.json (user scope) or your project's .mcp.json:

{
  "mcpServers": {
    "cli-bridge": {
      "type": "stdio",
      "command": "cli-bridge"
    }
  }
}

For Codex — add to ~/.codex/config.toml:

[mcp_servers.cli-bridge]
command = "cli-bridge"

3. Restart your MCP client. Tools register at startup; new MCP servers don't appear in an already-running session.

Register a tool

A registered tool means cli-bridge knows where its spec is and what binary version it targets.

If you installed via Path A (plugin)

Use the slash command from inside Claude Code:

/cli-bridge:register <binary>

It tries the canonical path first, falls back to scraping --help if needed. Both paths write to ~/.config/cli-bridge/specs/<tool>/<version>.json.

If you installed via Path B (standalone)

You don't have the slash command. Two options:

• Canonical path (preferred for CLI authors who follow the convention). If your tool exposes <binary> cli-bridge-manifest (this is the convention — gosymdb is the reference), write the spec directly:

  mkdir -p ~/.config/cli-bridge/specs/<tool>
  <tool> cli-bridge-manifest > ~/.config/cli-bridge/specs/<tool>/$(<tool> --version | awk '{print $NF}').json
  

  After this, cli-bridge auto-refreshes the spec whenever the binary version changes. You'll see a [cli-bridge] auto-refreshed spec for <tool> to v<new> log line on the next startup. No manual re-registration needed for canonical-convention tools.