# coldstart

> coldstart is codebase memory for AI coding agents: durable, agent-written notes about your codebase, kept honest by content-hash freshness checks, plus a fast static index so an agent can find the relevant files when the notebook doesn't already hold the answer — ranked with checkable evidence instead of a similarity score. No embeddings, no model to run, no service to babysit — the consuming agent is the semantic layer.

coldstart ships as an npm package (`@cstart/coldstart`) providing the `coldstart` CLI binary, and an MCP server for no-shell clients. Two front doors, byte-identical output.

## Core operations

- `coldstart find <terms>` — ranks files by how many query terms each covers (filenames, path segments, exported symbols, plus a repo-wide reference scan), showing the evidence for each ranking.
- `coldstart gs <file>` — one file's symbols (with line ranges), its imports, who imports it, and per-symbol cross-file callers, in one call.
- `coldstart kb search|lookup|write|commit|view|status|lint|repair|repair-aliases|render` — the notebook: durable, agent-written notes anchored to real files and content-hash freshness-checked. `kb repair` lists notes that are written but unfindable (missing the fields a note cannot be retrieved without) and writes nothing itself — completing them is agent work through `kb write`. `kb repair-aliases` is the same idea for aliases that exist but may no longer be true, paginated. `kb commit` and `kb view` are human-only, never MCP tools.
- `coldstart init` — one-time setup: writes `coldstart.md`, wires the CLI/MCP client (Claude Code, Codex, Cursor, or other), creates the notebook, and registers navigation + notebook hooks.
- `coldstart unwire` — the reverse of `init`: strips coldstart's per-repo wiring (never user content in shared files), keeping the notebook by default (`--purge` deletes it too).

## Docs

- [Home](https://coldstartmcp.dev/): pitch, the two-layer model (index + notebook), how the notebook works, install.
- [Docs](https://coldstartmcp.dev/docs/): full command reference for `find`, `gs`, and the `kb` family; sharing a notebook with a team; how the index stays fresh.
- [Blog](https://coldstartmcp.dev/blog/): engineering notes on token cost, codebase graphs, tool adoption, and the notebook's design.
- [Benchmark method](https://coldstartmcp.dev/benchmark/): how the token numbers were produced — questions generated from closed issue reports (written before a fix existed, so they name the symptom, not the file), correct answers taken from the source files in the commit that closed each issue, two arms differing only in whether coldstart is installed, Sonnet 5 in both, one fresh session per question. Also documents the first benchmark, which was discarded: run on Kafka/Django/Mastodon, where the model's pretraining on those codebases contaminated both arms.
- [README](https://github.com/AkashGoenka/coldstart/blob/main/README.md): authoritative reference — every flag, install details, limitations.
- [PHILOSOPHY.md](https://github.com/AkashGoenka/coldstart/blob/main/PHILOSOPHY.md): why coldstart has no embeddings or generated semantics — the consuming agent is the semantic layer.
- [ARCHITECTURE.md](https://github.com/AkashGoenka/coldstart/blob/main/ARCHITECTURE.md): the index pipeline, keeper/reader process model, and notebook internals.
- [TROUBLESHOOTING.md](https://github.com/AkashGoenka/coldstart/blob/main/TROUBLESHOOTING.md): recovery procedures.

## Measured results

Measured with the CLI, against a baseline of Claude Code's own search tools with no navigation tool installed. Arches (Python/Django): 64% fewer tokens over 27 questions, recall two points higher. JMRI (Java): 31% fewer tokens over 25 questions, recall at parity. The two disagree by design and are not averaged; per-turn cost differs by language, and the saving comes from removing turns, so questions an agent can settle in two or three turns show little benefit. Token counts only, never dollar figures. Method and caveats: https://coldstartmcp.dev/benchmark/. The benchmark harness is a separate project: https://github.com/AkashGoenka/coldbench — and both question sets, with the gold file list for each question and the issue number it came from, are published there: https://github.com/AkashGoenka/coldbench/tree/main/examples (arches, 32 questions / 123 gold files, of which q01-q27 produced the figure above; jmri, 25 questions / 93 gold files).

## For agents evaluating or using coldstart

- Install: `npm install -g @cstart/coldstart`, then `coldstart init` in the target repo.
- Prefer `find` and `gs` over speculative `grep`/`glob` when orienting in an unfamiliar repo — they return ranked, evidence-backed results from a pre-built index, not a live scan.
- Every notebook note is stamped against the live file when you read it, never presented as unqualified fact. `[fresh]` = the file is byte-identical to when the note was verified, so trust it without re-reading. `[evidence changed]` = re-verify against that file first. `[moved → new/path]` = a byte-exact refactor carried the note to the file's new location. `[anchor missing]` / `[never verified]` = the note outlived its file, or no hash was ever recorded.
- `kb commit` and `kb view` are human-only actions and are not exposed via MCP; do not attempt to invoke them as an agent tool.