mcp-cli

# mcp-cli A sidecar-daemon + MCP bridge designed to give CLI/IDE-based AI agents (Claude Code, Codex, etc.) deep access to a project's filesystem, git state, and source code **without paying the per-call fork/exec tax** of traditional shell-tool wrappers. ## Headline Numbers Significant wins across both major agents measured on 2026-04-21 (analysis of `openai/codex@rust-v0.122.0`). ### [Codex](bench/codex-forkexec/results/2026-04-21-rust-v0.122.0-sandbox-ablation.md) * **−44 %** Wall-clock (209s → 117s) * **−66 %** `execve` calls (64 → 22) * **−64 %** Input tokens (1.9M → 0.7M) ### [Claude Code](bench/claudecode-forkexec/results/2026-04-21-rust-v0.122.0.md) * **−5 %** Wall-clock (even on cold pass) * **−82 %** `execve` calls (85 → 15) * **−14 %** Output tokens **Warm-cache bonus:** Re-running tasks on a resident daemon saves an additional **650k–950k tokens** per pass via tree-sitter parse and grep result caching. There is now a matching Claude Code twin benchmark under [`bench/claudecode-forkexec/`](./bench/claudecode-forkexec/): same target workload, but three passes (`baseline`, `cold mcp-cli`, `warm mcp-cli`) so the daemon's cross-session cache payoff is visible too. The Codex run above is still the headline result in the README; the Claude Code twin broadens the measurement surface beyond a single agent and is the next place to fold into the top-level story. ## Architecture ``` +---------------------+ stdio (MCP) +----------------------+ | Claude Code / | <-------------------------> | mcp-cli-bridge | | Codex / IDE | | (MCP stdio server) | +---------------------+ +----------+-----------+ | UDS + length-prefixed JSON-RPC | +----------v-----------+ | mcp-cli-daemon | | - mmap VFS | | - libgit2 | | - grep-searcher | | - (future) tree- | | sitter, LSP | +----------------------+ ``` * **`crates/protocol`** - shared JSON-RPC request/response types between bridge and daemon. * **`crates/daemon`** - long-lived `mcp-cli-daemon` process that owns the project. Listens on a Unix Domain Socket and exposes in-process tools: * `fs.read` - mmap-backed file read (no `read(2)` per call). * `fs.snapshot` / `fs.changes` - incremental sync. The daemon runs an inotify (Linux) / FSEvent (macOS) watcher with a gitignore-aware filter, maintains a monotonic version cursor, and returns coalesced created/modified/removed events since a client-supplied version. If the client falls too far behind, the response sets `overflowed: true` so the client can re-scan instead of silently missing events. * `git.status` - libgit2 status (no `git` fork/exec). * `search.grep` - ripgrep's `grep-searcher` library over the project tree. * **`crates/mcp-bridge`** - small `mcp-cli-bridge` stdio binary that the agent spawns. Translates MCP `tools/call` requests into UDS calls. Cheap to spawn, but the heavy state stays in the daemon. ## Why this shape Every traditional shell-wrapped tool call (`cat`, `git status`, `rg ...`) costs a `fork` + `exec` + page-table setup + library loading + syscall stream + tear down. For an agent that issues hundreds of small reads per task, that's dominated by kernel overhead, not useful work. By keeping a single hot daemon: * File reads come from an `mmap` already in the page cache - the kernel only pages in on misses; no per-call `read` syscall stream. * Git, search, and (planned) parse operations stay in-process, so the kernel sees one long-lived process instead of thousands of short-lived ones. * The bridge stays tiny and the per-call cost is a UDS round-trip on a single pre-warmed socket. This is the foundation for later layers (incremental inotify diffs, tree-sitter indexing, language-specific backends like clangd / rust-analyzer reuse). ## Build ```sh cargo build --release ``` Artifacts under `target/release/`: `mcp-cli-daemon`, `mcp-cli-bridge`, and the `mcp-cli` installer. ## Install One-command registration for the agents the installer knows about: ```sh # Claude Code + Codex at once (auto-spawns the daemon on first tool # call; no always-on process needed). target/release/mcp-cli install ``` For **codex specifically**, also pass `--prefer-mcp` so codex actually routes through the daemon instead of preferring its own built-in Bash (this is the configuration the headline numbers were measured under): ```sh target/release/mcp-cli install --target codex --prefer-mcp ``` `--prefer-mcp` writes `[features] shell_tool = false` to `~/.codex/config.toml` (so codex stops emitting Bash tool calls for `cat` / `rg` / `git` / etc.) and sets per-tool `approval_mode = "approve"` for every mcp-cli tool (so codex doesn't prompt for approval in non-interactive `codex exec`). Without `--prefer-mcp`, codex still *mounts* mcp-cli but keeps reaching for Bash — see the v1 benchmark writeup for evidence. The daemon auto-spawns per project root on the bridge's first connect and idle-exits after 30 min of inactivity; you don't need to run anything by hand. To always keep one resident, see [`doc/services/`](./doc/services/). ## Status See [`doc/ROADMAP.md`](./doc/ROADMAP.md) and [`doc/TODO.md`](./doc/TODO.md). * **Done (M0–M6 + parts of M7)** — Daemon/Bridge skeleton, incremental watch sync, tree-sitter indexing (`rust`, `python`, `c`, `cpp`, `ts`, `go`), drop-in `mcp-cli install`, per-cwd auto-spawn, reconnect-on-dead, `mimalloc` + buffer pooling, full M5 performance benchmarks, and `git.log` / `git.diff` RPCs. * **In Progress (M7)** — Token-killer compaction (`?compact` on `git.status`, `search.grep`, `fs.scan`; `?strip_noise` on `fs.read`), metrics telemetry, and the generic `tool.run` wrapper. * **Open (M8–M10)** — Write-path with optimistic concurrency (`fs.apply_patch`), advanced structural tools (dependency graphs, dynamic folding), and deep git/process management.