CALM

# CALM — Coding Agent Liveness Map

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/Eilodon/CALM/actions/workflows/ci.yml/badge.svg)](https://github.com/Eilodon/CALM/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/%40eilodon%2Fcalm-mcp?label=npm)](https://www.npmjs.com/package/@eilodon/calm-mcp)
![Languages](https://img.shields.io/badge/languages-24%20parsed%20%C2%B7%2013%20call--graph%20by%20default%20%C2%B7%2012%20formal--verified-informational)

**A live, graph-verified map of your codebase — so an AI coding agent can edit with its eyes open instead of grepping in the dark.**

Real call graphs instead of vector-similarity guesses. Compiler-verified edges wherever a compiler is available. Hard safety gates on the write path itself, not just warnings an agent is free to scroll past. Every number in this README is measured — by CALM's own tools, against CALM's own codebase, with a reproducible benchmark suite behind it.

**New here?** [Quick start](#quick-start) gets you running in under a minute — no clone, no Rust toolchain, works with [Claude Code, VS Code, Cursor, Windsurf/Devin Desktop, Codex, Antigravity, and JetBrains](#quick-start). **Comparing tools in this category?** Jump straight to [Proof, not promises](#proof-not-promises). **Want the internals?** [`docs/architecture.md`](docs/architecture.md) covers multi-tier indexing, the SCIP/LSP overlay system, the concurrency model, and the sanitization layer in full.

| | |
|---|---|
| **Coverage** | 24 languages parsed · 13 with full call graphs by default (6 zero-config + 7 more via the default `tier0-5` bundle) · 12 with a formal/compiler-verified upgrade path |
| **Safety** | the only one of 5 live MCP servers benchmarked that *refused* an unconfirmed edit to a verified hub symbol |
| **Efficiency** | 29x–241x fewer tokens than a naive read-the-files baseline on multi-file tasks ([benchmark](benchmarks/b4_token_efficiency/)) |

---

## The problem

An AI agent that edits code without knowing who calls the function it's about to change will, sooner or later:

- Delete "dead code" that a dozen other files still call.
- Change a signature and miss half its call sites.
- Refactor a symbol it assumed was minor — and discover, after breaking the build, that it was the hub the whole module leaned on.

None of that is a reasoning failure. It's a *visibility* failure: the agent never had a map. Give it one, and the guessing stops.

## Why "CALM"

Most coding agents operate the way anyone would in an unfamiliar codebase with only `grep`: no sense of what's wired to what, no way to know if touching this function ripples into fourteen others. That's not confidence — it's fast guessing.

CALM stands for **Coding Agent Liveness Map**. *Liveness*, because the map is never a stale snapshot — it watches the filesystem, reindexes incrementally as files change, and reports in every response how fresh it currently is (`scanning → parsing → building_edges → ready`). *Map*, because it's an actual graph — call edges, import edges, hub/coreness metrics — not a flat text index pretending to be one. Hand an agent a live, trustworthy map of the terrain, and it stops flailing. It gets calm.

## What you get

- **The agent stops guessing who depends on what.** `callers`/`callees`/`edit_context` show every known caller before a change ships. Full tree-sitter call graphs cover **13 languages out of the box**: Python, TypeScript, JavaScript, Java, Rust, and Go with zero configuration, plus C, C++, C#, Ruby, PHP, Shell, and R via the default `tier0-5` grammar bundle. Eleven more (Kotlin, Swift, Scala, Dart, Lua, Elixir, Haskell, OCaml, Zig, PowerShell, Groovy) parse behind opt-in `--features lang-X` build flags — 24 languages parsed in total (see [multi-tier indexing](docs/architecture.md#multi-tier-indexing)).
- **Edits that can't silently break things.** Every write is hash-verified against the exact line range and syntax-checked before it ever touches disk. Hub and high-fan-in symbols hard-refuse a write until the agent has reviewed the callers and explicitly confirmed — a policy only a tool with a real dependency graph can enforce, and one no other server in [CALM's competitor benchmark](#benchmarked-against-four-other-live-mcp-servers) enforced.
- **Every edge tells you how much to trust it.** Call edges are confidence-graded (`textual → inferred → resolved → formal`), and when your compiler can double-check the graph, CALM asks it to: SCIP overlays (`rust-analyzer`, `scip-go` — including multi-module `go.work` workspaces — `scip-python`, `scip-ruby`, and more) and live LSP overlays (`gopls`, `clangd`) upgrade best-guess edges to compiler-verified ground truth across 12 languages, with zero behavior change on a machine that doesn't have the toolchain installed.
- **A codebase that grades itself.** `fitness_report` turns hub concentration, dead code, complexity, and architecture-boundary violations into a queryable, CI-enforceable signal instead of a one-off audit — and `remember`/`recall` keep decisions and gotchas available across sessions.
- **Plays well with others, and stays on your machine.** A cross-process edit lock and single-writer indexing model mean two editor sessions on the same repo don't corrupt each other's writes or double-index — under the shared daemon, sessions can even see each other coming. No code leaves your machine for indexing, search, or editing; the default embedding model is vendored into the binary at build time (zero network at runtime), with a rare, opt-out-able fallback download only if that vendored copy is ever unusable. MIT-licensed.

## Where CALM fits

"Code intelligence for AI agents" is a real category now, built up by open-source pioneers — Aider, Serena, Sourcegraph/Cody, and others — that proved an agent works better with real code structure under it than with grep and good intentions. CALM builds on that foundation with a different center of gravity: most tools in the category **inform the read path** — better search, better navigation, better context. CALM also **guards the write path**. The same graph that answers "who calls this?" enforces "you don't change it until you've looked": pre-edit context is mandatory, hub edits demand an explicit confirmation grounded in a real caller, and every write is hash- and syntax-verified before it lands.

The trade-off is stated plainly: CALM's full-call-graph tier out of the box is 13 languages, not the 40+ some pure-LSP tools reach — though with 24 languages parsed and 12 carrying a compiler-verified upgrade path, the gap is narrower than it looks. What the trade buys is the part most distinctly CALM's own: confidence-graded edges, hard pre-edit gates, and a codebase that grades its own health — each backed by a number you can reproduce yourself ([Proof, not promises](#proof-not-promises)).

### Is CALM the right fit?

**Good fit:** agents that edit code directly, not just answer questions about it · single-repo codebases in a Tier-0/Tier-0.5 language · projects running multiple MCP clients (see [supported clients](#quick-start) below) against the same repo · local-first users who don't want to depend on an embedding API.

**Not the fit today:** multi-repo/cross-repo enterprise search — tools purpose-built for that scale (Sourcegraph/Cody among them) will serve you better · a language nowhere in CALM's current 24-language tree-sitter set.

## Quick start

**Supported clients** — CALM works with any MCP client that speaks stdio; these are wired up or documented today:

| Client | Modes | Fastest install |
|---|---|---|
| **Claude Code** | CLI · Web · IDE | `claude mcp add --transport stdio calm -- npx -y @eilodon/calm-mcp serve` |
| **VS Code** | IDE (native MCP / Copilot Agent mode) | `code --add-mcp '{"name":"calm","command":"npx","args":["-y","@eilodon/calm-mcp","serve"]}'` |
| **Cursor** | IDE · Cloud (Background Agent) | [Add to Cursor →](cursor://anysphere.cursor-deeplink/mcp/install?name=calm&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBlaWxvZG9uL2NhbG0tbWNwIiwic2VydmUiXX0=) |
| **Windsurf / Devin Desktop** | IDE · Cloud | edit `~/.codeium/windsurf/mcp_config.json` |
| **Codex** (OpenAI) | CLI · IDE | `codex mcp add calm -- npx -y @eilodon/calm-mcp serve` |
| **Antigravity** (Google) | CLI · IDE | edit `~/.gemini/config/mcp_config.json` |
| **JetBrains AI Assistant** | IDE | via UI settings |

Full walkthrough for every client above, including exact global-config snippets for the ones that need one — [`docs/mcp-client-setup.md`](docs/mcp-client-setup.md).

**Using CALM on your own project** — no clone, no Rust toolchain:

```json
{
  "mcpServers": {
    "calm": {
      "command": "npx",
      "args": ["-y", "@eilodon/calm-mcp", "serve"]
    }
  }
}
```

Drop that into `.mcp.json` (Claude Code/Cursor) or `.vscode/mcp.json` (VS Code uses a top-level `"servers"` key instead of `"mcpServers"`, same shape otherwise) at your project root. Claude Code plugin instead: `/plugin marketplace add Eilodon/CALM` then `/plugin install calm@CALM`.

Prefer a native binary over npx? `curl -fsSL https://raw.githubusercontent.com/Eilodon/CALM/main/scripts/install.sh | sh`, then run `calm setup` from inside your project — it writes the same MCP config automatically, pointing at the binary you just installed. Add `calm setup --npx` instead to write the portable `npx` entry (shareable/committable — teammates and CI don't need the binary, and it tracks the published release).

**Developing on CALM itself** (this repo):

```bash
# 1. Build the binary
cargo build --release -p calm-cli

# 2. Initialize config for your project
calm init --project-root .

# 3. Build the index (embeds symbols too, if semantic search is enabled in config.json)
calm index --project-root .

# 4. Run the MCP server over stdio — incremental reindex kicks in automatically if an index already exists
calm serve --project-root .
```

This repo ships ready-made config f