{
"markdown": "# CALM — Coding Agent Liveness Map\n\n[](LICENSE)\n[](https://github.com/Eilodon/CALM/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/@eilodon/calm-mcp)\n\n\n**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.**\n\nReal 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. Measured claims in this README are tied either to a current CALM snapshot or to benchmark artifacts; repo-specific values change as the codebase changes.\n\n**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.\n\n| | |\n|---|---|\n| **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 when the provider/toolchain is available |\n| **Safety** | the only one in the published five-server benchmark that *refused* an unconfirmed edit to a verified hub symbol |\n| **Efficiency** | task-specific token savings versus a naive read-the-files baseline; see the [benchmark artifacts](benchmarks/b4_token_efficiency/) |\n\n---\n\n## The problem\n\nAn AI agent that edits code without knowing who calls the function it's about to change will, sooner or later:\n\n- Delete \"dead code\" that a dozen other files still call.\n- Change a signature and miss half its call sites.\n- Refactor a symbol it assumed was minor — and discover, after breaking the build, that it was the hub the whole module leaned on.\n\nNone of that is a reasoning failure. It's a *visibility* failure: the agent never had a map. Give it one, and the guessing stops.\n\n## Why \"CALM\"\n\nMost 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.\n\nCALM 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.\n\n## What you get\n\n- **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)).\n- **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 the published [competitor benchmark](#benchmarked-against-four-other-live-mcp-servers) found no other server enforcing.\n- **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`) can upgrade best-guess edges to compiler-verified ground truth across 12 supported language integrations when their provider/toolchain is available; unavailable providers sit out without changing the base behavior.\n- **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.\n- **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 and needs no runtime network when those weights are valid; if they are unavailable, a runtime fallback download is allowed by default and can be disabled for strict offline operation. MIT-licensed. *(One more opt-in exception: building with `--features otel` and setting `OTEL_EXPORTER_OTLP_ENDPOINT` exports span attributes — file paths, symbol names, tool names, timing, never source bodies — to your own collector. Off by default; see [docs/architecture.md](docs/architecture.md#observability-optional) and use `https://` collectors only.)*\n\n## Where CALM fits\n\n\"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\": hub/high-risk edits require fresh pre-edit context plus explicit confirmation grounded in a real caller; the policy can be widened to every edit, and every write is hash- and syntax-verified before it lands.\n\nThe 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 when their providers are available, 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)).\n\n### Is CALM the right fit?\n\n**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.\n\n**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.\n\n## Quick start\n\n**Supported clients** — CALM works with any MCP client that speaks stdio; these are wired up or documented today:\n\n| Client | Modes | Fastest install |\n|---|---|---|\n| **Claude Code** | CLI · Web · IDE | `claude mcp add --transport stdio calm -- npx -y @eilodon/calm-mcp serve` |\n| **VS Code** | IDE (native MCP / Copilot Agent mode) | `code --add-mcp '{\"name\":\"calm\",\"command\":\"npx\",\"args\":[\"-y\",\"@eilodon/calm-mcp\",\"serve\"]}'` |\n| **Cursor** | IDE · Cloud (Background Agent) | [Add to Cursor →](cursor://anysphere.cursor-deeplink/mcp/install?name=calm&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBlaWxvZG9uL2NhbG0tbWNwIiwic2VydmUiXX0=) |\n| **Windsurf / Devin Desktop** | IDE · Cloud | edit `~/.codeium/windsurf/mcp_config.json` |\n| **Codex** (OpenAI) | CLI · IDE | `codex mcp add calm -- npx -y @eilodon/calm-mcp serve` |\n| **Antigravity** (Google) | CLI · IDE | edit `~/.gemini/config/mcp_config.json` |\n| **JetBrains AI Assistant** | IDE | via UI settings |\n\nFull 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). Running inside a devcontainer/Codespace where stdio forwarding doesn't reach? See [`docs/http-transport.md`](docs/http-transport.md) (advanced, remote-dev only, opt-in, loopback by default).\n\n**Using CALM on your own project** — no clone, no Rust toolchain:\n\n```json\n{\n \"mcpServers\": {\n \"calm\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@eilodon/calm-mcp\", \"serve\"]\n }\n }\n}\n```\n\nDrop 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`.\n\nPrefer 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). It pins to this binary's own version by default for reproducible cold installs; pass `--track latest` to always resolve npm's newest release instead.\n\n**Developing on CALM itself** (this repo):\n\n```bash\n# 1. Build the binary\ncargo build --release -p calm-cli\n\n# 2. Initialize config for your project\ncalm init --project-root .\n\n# 3. Build the index (embeds symbols too, if semantic search is enabled in config.json)\ncalm index --project-root .\n\n# 4. Run the MCP server over stdio — incremental reindex kicks in automatically if an index already exists\ncalm serve --project-root .\n```\n\nThis repo ships ready-made config for Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`), and VS Code (`.vscode/mcp.json`) — all three point at `scripts/mcp-launcher.sh`, a shared launcher that finds an already-built binary, downloads a checksum-verified prebuilt release if you're on a matching git tag, or builds from source if nothing is available yet. Clone the repo and it just works — no manual build step required first.\n\n> **Note:** `calm serve` automatically adds `.calm/` to `.gitignore` on startup so the index database never gets committed.\n\n## Example: an agent's actual workflow\n\n```\nagent: repo_overview()\n → current files/symbols and `indexing_phase=ready` are reported live\n\nagent: \"I need to change getUserByEmail\"\n → locate(\"getUserByEmail\") # find the file + symbol metadata\n → source(\"getUserByEmail\") # read just the function body, not the whole file\n → edit_context(\"getUserByEmail\") # MANDATORY before any edit\n → the live caller count and risk assessment determine whether the agent reviews callers before touching the signature\n → edit_symbol(\"getUserByEmail\", expected_hash=..., new_text=...)\n → risk_assessment=high, is_hub=true, no confirm:true → refused, with an explanation\n → edit_symbol(..., confirm=true, reason=\"checked getUserByToken, still returns the same shape\")\n # reason must cite a real caller edit_context returned — writes for real, reindexes immediately\n → diff_impact(staged=true) # verifies blast radius before commit\n```\n\n## Proof, not promises\n\nThe table below is a CALM snapshot observed on 2026-08-12 from this checkout. Re-run `repo_overview()` and `fitness_report()` to refresh it; repo-specific values change as the codebase changes. Benchmark ratios are task-specific and remain in the benchmark artifacts:\n\n| Metric | Measured value |\n|---|---|\n| Codebase indexed | **366 files, 6,050 symbols** — 15 language families present in this repo alone |\n| Hub concentration (`hub_pct`) | 7.38% — 271 hub symbols (gate: ≤ 20%) |\n| Dead-code rate (`dead_code_pct`, coverage-aware) | 5.04% (gate: ≤ 10%) |\n| Hotspot risk (`hotspot_risk`, churn × complexity, worst file) | **0.90 — currently above gate (≤ 0.80), fitness_report() reports FAIL** — being investigated rather than hidden or threshold-relaxed; see [`fitness_report`](#39-mcp-tools-for-ai-agents)/`calm fitness-check` |\n| Edge coverage (`edge_coverage_pct`) | 72.39% of symbols have at least one call edge (gate: ≥ 60%) |\n| High-complexity functions (`high_complexity_pct`) | 2.8% (gate: ≤ 15%) |\n| Architecture fit (`avg_distance`, Martin/OOD) | 0.28 average distance from the main sequence (gate: ≤ 1.00) |\n| Ambiguous symbol boundaries (`boundary_ambiguous_count`) | 0 (gate: ≤ 0) |\n| Architecture boundary violations (`boundary_violations`) | 0 (gate: ≤ 0) — the `watcher → tools` import previously flagged here was fixed by relocating the shared `RwLockExt`/`LockExt` traits it needed out of `tools/common.rs` into their own `sync_ext` module |\n| Config drift (`config_drift_count`) | 0 (gate: ≤ 0) — the current docs/config path declarations resolve cleanly |\n| Token efficiency vs. a naive read-the-files baseline | Benchmark-specific; see [methodology](benchmarks/b4_token_efficiency/) rather than treating one task's ratio as a repo-wide constant |\n| Full test suite (default features) | see [Testing](#testing) below |\n\n\nCompetitor-benchmark methodology and per-language caveats
\n\n### Benchmarked against four other live MCP servers\n\n`benchmarks/b11_extended_competitor_ab/` installs and calls four established open-source code-intelligence MCP servers — CodeGraph, Semble, grepai, and Serena — against an isolated git worktree of this repo, 5 repeats per task, with a correctness oracle for every task. The goal isn't a leaderboard; it's checking CALM's claims against real, running prior art instead of a marketing page.\n\nWhat the runs showed: CALM matched the best result on caller-recall and blast-radius tasks, and was the only one of the five servers whose pre-edit safety gate actually *refused* a risky, unconfirmed edit rather than merely being able to describe the risk after the fact. Not every number flatters: on one token-efficiency task CALM's compression ratio was the lowest of the five — correctness stayed at the ceiling there too, and the number is published as measured. That is this project's standing benchmark policy: unflattering results ship alongside good ones ([benchmarks/README.md](benchmarks/README.md)). Full methodology, every task, and the raw per-tool numbers live in the benchmark's own README.\n\n### Language coverage, measured not asserted\n\n`benchmarks/resolution/` runs a tier-distribution baseline (resolved / inferred / textual / ambiguous split — no oracle, one real OSS repo per language) across the 19 newly-added or Tier-0.5 languages, reported as-is: Kotlin (89.6%) and OCaml (86.3%) land mostly in the `ambiguous` tier from common short method-name collisions; Dart produces symbols but zero call edges — a documented limitation of that tree-sitter grammar, not a bug; Tier-2 type inference is wired only for the original Tier-0 languages so far. Full per-language table in the benchmark's own README.\n\n \n\n## How CALM works\n\nFull technical detail lives in [`docs/architecture.md`](docs/architecture.md) — including the design philosophy behind why every response carries `suggested_next` and why the risky steps are hard-gated instead of just recommended. Section-by-section summary:\n\n- **[Multi-tier indexing](docs/architecture.md#multi-tier-indexing)** — 13 languages with full call graphs by default, 11 more parsed behind opt-in grammar features, 24 in total.\n- **[A call graph you can actually trust](docs/architecture.md#a-call-graph-you-can-actually-trust)** — every edge is labeled by confidence (`resolved`/`inferred`/`formal`/`textual`); SCIP and LSP overlays can upgrade edges to compiler-grade ground truth across 12 supported integrations when their providers/toolchains are available; unavailable providers sit out.\n- **[Search that actually finds things](docs/architecture.md#search-that-actually-finds-things)** — FTS5 + semantic embeddings fused via Reciprocal Rank Fusion, plus real grep/glob straight off disk for files the indexer never parses.\n- **[Editing with an actual safety net](docs/architecture.md#editing-with-an-actual-safety-net)** — hash-verified writes, syntax validation before anything touches disk, and a three-part gate (fresh `edit_context`, `confirm:true`, a grounded `reason`) on hub/high-risk symbols.\n- **[Concurrency & reliability](docs/architecture.md#concurrency--reliability)** — a shared daemon, cross-process edit lock, and single-instance indexing lock mean multiple editor sessions on one repo don't corrupt or duplicate work.\n- **[The codebase grading itself](docs/architecture.md#the-codebase-grading-itself)** — 11 fitness metrics, coverage-aware dead-code detection, declared architecture boundaries, doc-drift detection.\n- **[An agent that remembers, and knows when it's stuck](docs/architecture.md#an-agent-that-remembers-and-knows-when-its-stuck)** — durable cross-session notes, git co-change mining, a stuck-loop signal.\n- **[Safe by default](docs/architecture.md#safe-by-default)** — credential-shaped content is redacted in `source`/`understand`, prompt-injection-shaped content is flagged, and `scan_text` covers external text; local-first by default with an explicit embedding fallback.\n\n## Crate layout\n\n- `crates/calm-core/` — the index engine: `tree-sitter` parsing, SQLite schema, the multi-tier resolver (conservative → inferred → formal/Stack-Graphs, SCIP, or LSP), graph algorithms (coreness, hub detection), FTS5/semantic search, analysis (hotspots, coverage, codeowners, diff-impact, dead-code), fitness metrics, gitignore management.\n- `crates/calm-server/` — the MCP server (`rmcp` over stdio or a unix-socket daemon), exposing 40 tools plus the incremental file watcher.\n- `crates/calm-cli/` — the CLI: `calm init`, `calm index`, `calm serve`, `calm connect`, `calm setup`, `calm fitness-check`, `calm guard`, `calm doctor`.\n\n## CLI reference\n\n```bash\ncalm init --project-root . # writes .calm/config.json with defaults\ncalm index --project-root . # one-shot full index (Scanning → Parsing → BuildingEdges → Ready)\n # also embeds symbols+chunks if semantic_search.enabled=true\ncalm serve --project-root . # MCP server over stdio + incremental reindex + file watcher\ncalm serve --project-root . --listen unix:/path/to/daemon.sock # run as a shared daemon (opt-in)\ncalm connect --project-root . # lightweight forwarder to an already-running daemon (opt-in, Unix)\ncalm serve --project-root /project --db-path /data/index.db # separate DB path (container deployment)\ncalm serve --project-root . --preset orient # register only the \"orient\" phase's tools\ncalm doctor --project-root . # validates config, DB (symbols/files/metrics history), git\ncalm setup --project-root . # writes/merges MCP config (.mcp.json/.cursor/.vscode) pointing at this binary\ncalm fitness-check --project-root . # CI gate, exits 1 on failure\ncalm fitness-check --project-root . --json # JSON output\ncalm fitness-check --project-root . --config thresholds.toml # custom thresholds\ncalm guard --project-root . # pre-commit/CI gate on the staged diff, exits 1 if aggregate risk >= --fail-on (default: high)\ncalm guard --project-root . --fail-on medium --json # stricter threshold, machine-readable output\ncalm guard --project-root . --base origin/main # review this branch/PR against a base ref instead of the staged diff\ncalm guard --project-root . --commits HEAD~3..HEAD # raw commit range, passed straight through to git diff\ncalm value-report --project-root . # real counts from .calm/audit.log: risky edits blocked, risk distribution on what was applied\ncalm value-report --project-root . --json # machine-readable output\ncalm scip-run --project-root . --lang go # force one SCIP provider to run now, bypassing refresh policy\ncalm scip-run --project-root . # --lang omitted = run every provider (\"rust,go,python,javascript,java,csharp,php,ruby,c\")\ncalm index --project-root . --scip-file build/index.scip --sub-root services/api # ingest a pre-built SCIP index (CI/sandboxed, no external indexer install needed)\n```\n\n## 40 MCP tools for AI agents\nCLI presets filter tools by workflow phase: `orient`, `trace`, `edit`, `compound`, `full` (default) via `calm serve --preset` or the `preset` field in `config.json` — or compose a custom set from toolset (module) names, e.g. `--preset \"trace,security\"` or `--preset \"full,-edit\"` (see AGENTS.md for the full toolset list). Every response carries `suggested_next` to point at the next step — full detail on each tool and the complete workflow lives in [AGENTS.md](AGENTS.md).\n\n| Group | Tools |\n|---|---|\n| Orient | `repo_overview`, `hotspots`, `fitness_report` (health snapshot — same metrics as `calm fitness-check`, queryable mid-session), `indexing_status`, `test_gap_hotspots` (ranks symbols by coreness × dead-code/test-coverage confidence — where test-writing effort pays off most) |\n| Locate | `locate`, `search`, `file_overview` |\n| Inspect | `source`, `symbol_info`, `understand`, `symbols_batch` (source + callers/callees for several exact `qualified_name`s in one round trip) |\n| Trace | `callers`, `callees` (ordered, capped, etag-cacheable on hub symbols), `path`, `dependencies`, `reference_impact` (merges call edges, import edges, and a textual grep into one classified rename/removal reference list — broader but coarser than `callers`/`dependencies` alone) |\n| Edit | `edit_context` (mandatory before any edit), `edit_lines`/`edit_symbol` (the one write tool for arbitrary content — hash-verified; a hub/high-risk touch is refused unless `edit_context` ran for that exact symbol this session, `confirm:true` is passed, and `reason` cites a real caller `edit_context` returned), `format_files` (rustfmt via stdin only — never a positional file arg, so it can't trigger rustfmt's own crate-wide `mod`-tree discovery and reformat files outside its own `paths` list; no confirm/edit_context gate since formatting can't change semantics), `pattern_debt_register`/`pattern_debt_status` (anchor a duplicated bug pattern by qualified_name via `search(kind=\"similar\")`, re-check later for `open`/`resolved`/`anchor_lost`), `diff_impact` (mandatory before commit) — `edit_context` and `diff_impact` are hook-enforced under Claude Code (see `.claude/hooks/calm-nudge.sh`); `session_context`'s `pending_diff_impact` is the equivalent signal on any other MCP client |\n| Change (authority) | `plan_change`/`review_change` — a reviewable-change facade over the edit gate: `plan_change` declares a `ChangeIntent` (what you're about to do, why) as a durable, reviewable record; `review_change` mints a signed `ReviewAuthority` for it once `approved:true` (client self-attestation, sufficient for low/medium risk only) or refuses outright when a real `PolicyEngine`/`RiskVector` evaluation classifies the change as needing independent human review — spending the authority via `edit_lines`/`edit_symbol` re-verifies it fresh, not just at mint time |\n| Txn (admin) | `batch_status` (aggregates a caller-supplied list of `tx_id`s from several `edit_lines`/`edit_symbol`/`format_files` calls into one view — counts by state, whether any failed), `edit_transaction_status`, `maintenance_status`, `retry_maintenance`, `repair_consistency`, `verify_change` (WS-6 first slice: on-demand cargo check for an opt-in-verified edit) — transaction/maintenance-outbox diagnostics for the WS-1 durable edit-transaction journal that `edit_lines`/`format_files` now write through; registered under their own `txn` toolset, included in the `edit` preset (not `orient`/`trace`/`compound`) |\n\n| Recover | `session_context`, `remember`, `recall` |\n| Advanced | `scip_refresh`, `lsp_refresh` — force one or every SCIP/LSP provider to run now, bypassing the automatic refresh policy. `scan_text` — run the same prompt-injection/credential heuristics `source`/`understand` use against *any* text you supply (a WebFetch/WebSearch result, a subagent's report, pasted content) — local and offline, independent of any hosted LLM safety classifier. `set_toolset` — narrow or reset which tools *this session* exposes at runtime, without restarting the server (the safety floor — orient+guardrails+recover+edit — is always kept). All four: `full` preset only, not in the four workflow-phase presets above — deliberate manual/rare-use escape hatches, not steps in the default flow |\n\n### MCP Prompts — workflows packaged as slash-commands\n\nDistinct from the `tools` above — MCP Prompts (`prompts/list`, `prompts/get`) return a single ready-made instruction message for a workflow you repeat often; MCP clients surface them as slash-commands:\n\n| Prompt | Argument | Packaged workflow |\n|---|---|---|\n| `review_symbol` | `symbol` | `locate` → `source` → `edit_context` (mandatory) → risk summary before touching anything |\n| `debug_symbol` | `symbol` | `understand` → `callers(max_depth=3)` → check `test_files`/`dead_code_confidence` |\n| `onboard_area` | `path` | `repo_overview` → `file_overview`/`dependencies` → `hotspots` scoped to that path |\n| `review_pr` | `range` | `diff_impact(commits=range)` → `hotspots` (overlap check) → `fitness_report` → aggregate risk summary before merge |\n| `calm_workflow` | *(none)* | No-argument orientation to the full Stage 1-8 tool workflow — for a client that never auto-loads AGENTS.md, or a mid-session refresher |\n\n## One-line CI: the CALM Guard GitHub Action\n\n[`action.yml`](action.yml) wraps `calm index` + `calm guard` as a reusable composite action -- one-line adoption for a repo that just wants blast-radius review on every PR, no MCP client involved:\n\n```yaml\n- uses: Eilodon/CALM@main\n with:\n fail-on: high # default; \"low\"/\"medium\" also accepted\n```\n\nOn a `pull_request` event it auto-detects the PR's base branch (fetching just that ref, since a default shallow checkout won't have it) and reviews the merge-base-relative range; on a plain `push` it reviews `before..after`. Both are overridable with `base`/`commits` inputs matching `calm guard`'s own `--base`/`--commits` flags (see [CLI reference](#cli-reference) above) -- set one explicitly for anything the auto-detection doesn't cover (`workflow_dispatch`, a merge-queue event, etc.). Requires an npm-published `@eilodon/calm-mcp` release reachable from the runner; nothing else to install.\n\n## Fitness check — the CI gate\n\nRun for real in `.github/workflows/ci.yml`'s `fitness-check` job on every push/PR — `calm index` first (a fresh checkout has no `.calm/index.db` yet), then `calm fitness-check --project-root . --config thresholds.toml`. That `--config` flag is not optional: without it, `[[boundaries]]` and `[config_drift]` are silently treated as \"no rules declared\" rather than erroring — only the numeric thresholds have a real default.\n\n`calm fitness-check` measures 11 metrics against thresholds declared in `thresholds.toml`:\n\n| Metric | What it measures | Effective threshold |\n|---|---|---|\n| `hub_count` | Count of symbols classified as hubs | ≤ 1000 |\n| `hub_pct` | % of symbols that are hubs (scale-invariant) | ≤ 20.0% |\n| `avg_coreness` | Average k-core coreness across the graph | ≤ 15.0 |\n| `dead_code_pct` | % of symbols with \"high\" dead-code confidence | ≤ 10% |\n| `hotspot_risk` | Highest hotspot score in the codebase | ≤ 0.80 in this repo (`thresholds.toml` override; built-in default ≤ 0.75) |\n| `edge_coverage_pct` | % of symbols with at least one call edge | ≥ 60% |\n| `high_complexity_pct` | % of functions/methods with McCabe cyclomatic complexity > 10 (AST-based; Tier-0.5 languages always report complexity 1) | ≤ 15.0% |\n| `avg_distance` | Martin/OOD average distance from the main sequence — how far each file's abstractness sits from the ideal implied by its instability (Ca/Ce) | ≤ 1.00 |\n| `boundary_violations` | Count of `import_edges` violating a declared `[[boundaries]]` rule | ≤ 0 |\n| `boundary_ambiguous_count` | Count of symbols with an ambiguous line boundary (shared with a neighbor) — `edit_symbol` replace on these is refused until resolved | ≤ 0 |\n| `config_drift_count` | Count of doc file-path references (declared via `[config_drift].doc_paths`) pointing at nothing real | ≤ 0 |\n\nUnless noted above, the table uses built-in numeric defaults; this repo's checked-in `thresholds.toml` is the effective CI policy. Every `calm fitness-check` run also snapshots metrics to the DB so `edit_context` can show a trend (delta versus the previous day).\n\n### Architecture boundaries — `[[boundaries]]`\n\nDeclare \"module A must not import module B\" directly in `thresholds.toml` (same file as `[thresholds]`), matched by path prefix (not glob/regex). Note this is for layering Rust's own crate/module boundaries *don't* already enforce — declaring \"calm-core must not import calm-server\" would be a no-op, since Cargo's dependency graph makes that structurally impossible already:\n\n```toml\n[[boundaries]]\nfrom = \"crates/calm-core/src/indexer/\"\nto = \"crates/calm-core/src/analysis/\"\nreason = \"indexer (extraction) must stay upstream of analysis (dead-code, hotspots, fitness) — not the other way around\"\n```\n\n`calm fitness-check` reports each violation concretely (the real from/to path, the rule, and the reason) outside `--json` mode; the default `max_boundary_violations = 0` means a rule you bothered to declare is one you actually keep.\n\nThis repo's own `thresholds.toml` currently declares two: the one above, plus `crates/calm-server/src/watcher.rs` → `crates/calm-server/src/tools/` (\"the background reindex/watch loop must not depend on the MCP tool-handler layer it runs independently of\") — both hold at 0 violations.\n\n## Deployment\n\n- `cargo build --release` → static (musl on Linux) binaries via `.github/workflows/release.yml`, 5-target matrix with `SHA256SUMS` + build-provenance attestation for every asset: `x86_64-unknown-linux-musl`, `aarch64-unknown-linux-musl`, `aarch64-apple-darwin`, `x86_64-apple-darwin`, `x86_64-pc-windows-msvc`. `scripts/mcp-launcher.sh`/`scripts/install.sh` download and checksum-verify the right platform's build automatically on supported targets when checkout is on (or you're installing) a matching git tag; untagged, offline, or unsupported-platform paths fall back to an existing binary or a source build.\n- `Containerfile`, multi-stage (`rust:alpine` → `scratch`) — a single static binary, no runtime image needed, published to `ghcr.io/eilodon/calm-mcp` (tagged by version + `latest`) on every git tag push.\n- `compose.yaml` ships a hardened example (`read_only`, `cap_drop: ALL`, `no-new-privileges`, `pids_limit: 64`, `mem_limit: 256m`).\n- The default embedding model's weights are vendored into the binary via `include_bytes!` — `build.rs::ensure_embedding_weights` fetches `crates/calm-core/assets/potion-code-16m/*.safetensors` from Hugging Face Hub and checksum-verifies it once at *compile* time, so a normal `cargo build`/release binary needs no network I/O at runtime when those weights are valid. No Git LFS is involved (the repo carries zero LFS content).\n\n\nWhat happens if the build-time fetch fails (offline build, etc.)
\n\n`cargo build` still **compiles successfully** — `build.rs` writes a small placeholder stub in place of the real weights instead of failing the build. Loading that stub **at runtime** fails (\"failed to parse safetensors\"), so `Embedder::load` automatically falls back to a one-time Hugging Face Hub download of the same model (cached locally afterward; the default config allows this fallback, while `semantic_search.allow_network_fallback = false` keeps the runtime strictly offline). If that fallback is disabled or also unavailable, `indexing_status` reports `embeddings_status: \"failed\"` and `search(kind=\"semantic\"/\"hybrid\")` degrades to FTS-only — no crash, just no semantic search until the model is available and you rebuild or re-run.\n\n \n\n## Runtime and transport\n\n- **Default mode is MCP stdio.** The launcher uses the shared Unix daemon when invoked without extra launcher arguments on Unix; custom invocations, CI, and Windows can use one-process `calm serve`.\n- **HTTP is opt-in.** `calm serve --http` binds to `127.0.0.1:8787` by default. Non-loopback exposure requires `--allow-remote` and a non-empty `CALM_HTTP_TOKEN` sent as a Bearer token.\n- **Remote HTTP is read-only.** CALM forces the effective preset to `remote-safe` — every tool that declares `read_only_hint = true`, computed from the tool router itself rather than a hand-maintained list, so it can't silently miss a newly added state-mutating tool; terminate TLS at a reverse proxy. The built-in HTTP transport caps request body size and concurrent requests as defense-in-depth, but has no real rate limiting or per-IP DoS protection, so do not expose it directly to an untrusted network.\n\n## Testing\n\n```bash\ncargo test --workspace # unit + integration (embeddings is a default feature, included)\ncargo test --test parity_test test_formal_edges # Stack Graphs regression corpus\n```\n\nEleven CI jobs run on every PR (verified against `.github/workflows/ci.yml`'s own job list, not hand-counted): `verify` (fmt/clippy/test/audit), `calm-guard-dogfood` (dogfoods [`action.yml`](action.yml) against this repo's own PRs — `continue-on-error: true`, shadow mode while new), `stack-graphs-corpus` (formal-resolver parity), `txn-crash-injection` (WS-1's crash-injection suite — kills the process at every reachable `TxState` transition, real `SIGKILL`), `embeddings` (clippy + test with the `embeddings` feature), `no-stack-graphs-formal` (clippy + test with `stack-graphs-formal` off — the only CI coverage of the `resolver::formal` stub that feature gate compiles to), `all-languages` (fixture-repo indexing across all 24 parsed languages, plus `lsp-overlay`), `js-client-interop` (cross-checks the tool schema against a real JS MCP SDK client, not just Rust's own), `otel-http-features` (clippy + test with the `otel`/`http` features, plus a guard against `opentelemetry` core version skew), `fitness-check` (runs `calm fitness-check` against this repo's own index — see [Fitness check](#fitness-check--the-ci-gate) below), `status-drift` (fails the build if `docs/status.generated.md` is stale, if any hand-authored doc's tool count drifted from it, or if the benchmark claims registry is structurally inconsistent).\n\nThe workspace contains 1,000+ tests; the latest CI `verify` job is the source of truth for pass/fail. A handful of `#[ignore]`d live-binary integration tests (e.g. `rust-analyzer`/`scip-go`/`scip-java`) need external tools not installed in every environment.\n\n## Further reading\n\n- [`docs/architecture.md`](docs/architecture.md) — the full technical deep-dive: multi-tier indexing, SCIP/LSP overlays, search internals, the edit safety net, concurrency, self-grading, memory, sanitization, and the design philosophy behind it all.\n- [`docs/comparison.md`](docs/comparison.md) — methodology-first positioning write-up against other tools in this category.\n- [`docs/what-external-users-get.md`](docs/what-external-users-get.md) — exactly what an `npx`/npm/MCP-Registry install gives you, as distinct from this repo's own dev checkout: install/distribution mechanics, the full tool and toolset breakdown, the edit safety layer, language coverage, and what never ships externally.\n- [`docs/`](docs/) — resolver internals, migration plans, and other design notes not covered by `docs/architecture.md` above.\n- [`docs/adr/`](docs/adr/) — individual architecture decision records (Stack Graphs scope, the formal-resolver approach, the LSP-optional confidence upgrade, the daemon+forwarder concurrency model).\n- [`docs/mcp-client-setup.md`](docs/mcp-client-setup.md) — every MCP client install path in detail, including Windsurf/Devin Desktop and Codex global config.\n- [`docs/http-transport.md`](docs/http-transport.md) — the opt-in remote/HTTP transport (`calm serve --http`): loopback-by-default, the fail-closed `--allow-remote` + token requirement, why remote exposure forces a read-only preset, and the TLS/reverse-proxy expectation.\n- [`AGENTS.md`](AGENTS.md) — the full tool-by-tool workflow guide this project's own agents follow.\n- [`KNOWN_LIMITATIONS.md`](KNOWN_LIMITATIONS.md) — an honest list of what CALM doesn't do yet (single-language unsandboxed verification, no multi-file change-set, no reference-impact tool, risk classification with no change-kind signal, and more), and why each is deliberately deferred rather than half-built.\n- [`benchmarks/`](benchmarks/) — the measurement suite behind benchmark claims in this README, and a few more: `b2_call_graph_quality/` (precision/recall vs. a SCIP oracle), `b3_search_quality/` (hybrid RRF vs. FTS-only vs. raw grep, NDCG@10), `b4_token_efficiency/` (token cost vs. a naive baseline, per task), `b6_tool_call_efficiency/` (round-trips: naive multi-call vs. one MCP call), `b7_task_correctness/` (real rename refactors across 6 language corpora — fd/Rust, flask/Python, express/JS, zod/TS, gin/Go, spring-petclinic/Java — checked against an independent pass/fail oracle, not an LLM judge), `b11_extended_competitor_ab/` (real calls against 4 other live MCP servers, not self-reported numbers), `b12_tier1_tier2_tool_correctness/` (9 tools driven live over JSON-RPC against 6 external OSS repos, ground-truthed against regex/`git grep`), `resolution/` (tier-distribution baseline across 19 real OSS repos, one per language). Unflattering results are published alongside good ones on purpose — `benchmarks/README.md` states that policy.\n\n## License\n\n[MIT](LICENSE)\n",
"bytes": 38877,
"sha": "57e2293cf4df4cc1c04b36882377766567d8e9391e66da05525161659b3dc6ad",
"repo_slug": "eilodon/calm",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_eilodon_calm_mcp_bc6a8a21/readme"
}