coldstart

coldstart is a tool that provides self-maintaining, persistent codebase memory for AI coding agents. It consists of two layers: the notebook and navigation, designed so that agents such as Claude Code, Codex, and Cursor no longer have to re-explore the codebase in every session.

Purpose

When AI coding agents try to understand a codebase, they often waste a large number of tokens finding the right files and re-deriving what was already figured out in a previous session. coldstart focuses on solving these two problems: quickly locating files relevant to a task, and preserving the codebase knowledge that agents write down after real tasks so it can be reused in later tasks.

Main capabilities

Notebook (coldstart kb)

The notebook is a repository-local knowledge base located at .coldstart/notebook/, written and read by agents. Notes come in three forms: file notes (explaining a file's purpose, either as a single summary or as per-symbol facets for hub files), flow notes (ordered steps and invariants spanning files), and lessons learned (pitfalls, rules, defect causes, rationale, or confirmed absences). Every note carries anchors, that is, the specific file paths and symbols its claims depend on.

Notes reach agents in three ways:

• Summaries: they appear in find results and are a past agent's verified overview of a file; [fresh] means the file is byte-identical to when it was verified and can be relied on directly.
• Recall on prompt (optional hook): notes whose titles, aliases, or anchors match the incoming prompt are presented as a compact title + key points + paths block, with a hard cap, and as reference data. If there is no match, nothing is injected.
• kb search / kb lookup: a search engine for the notebook, and exact address lookup before editing a file (path [symbol]).

Trustworthiness mechanism: each anchor carries a content hash when written, and the index rechecks as the code changes. Drifted notes display [evidence changed: <path>], prompting the agent to re-verify, so that outdated knowledge is downgraded to a labeled assumption rather than a confident error. Notes are stored in an append-only .raw event log (committable, merged as a union, and reconcilable across parallel branches without conflicts), while Markdown notes are derived, mechanically regenerated, and gitignored. Writes are gated: the concept of a new note is first compared against a search of existing notes, and the agent must explicitly merge (--into <id>) orDeclared as new (--new). Concurrent session safety: each note independently appends to the log, new note IDs are created exclusively, shared file notes are merged losslessly, and rendering is atomic. If an agent discovers an error in a note within its context, it should correct or retract it immediately.

Navigation (coldstart find / coldstart gs)

Navigation is a fast static index of file paths, symbol names, exports, and the import/call graph, able to answer "which files are relevant to this task?" in milliseconds, and provide checkable evidence rather than similarity scores.

• find: locate the files corresponding to a concept. Pass in all salient identifiers from the task (symbols, domain nouns, half-remembered rare tokens); find ranks by the number of terms each file covers, and shows the terms each file defines and imports, along with a preview of the lines where terms cluster. In speed it competes with raw grep; repository-level reference traversal is based on ripgrep (available in PATH, bundled, or from the editor; COLDSTART_RG can override), with git grep / grep fallback; the ranking page comes from a prebuilt index rather than a scan. Flags: --path GLOB, --tests, --via, --json.
• gs: drill into a single file. One call returns the file's symbols (with line ranges), 1-hop internal imports, who imports it, and the cross-file callers of each symbol. Flags: --symbol a,b, --match TERM, --view symbols|imports|importers|callers, --json.
• graph: for humans rather than agents. Generates a self-contained HTML file and opens it; each indexed file is a point on a sphere, positioned by directory, and clicking shows its connections, with relationships labeled by name. No dependencies, no server, no build step, and data never leaves the local machine. Flags: --out PATH, --no-open, --json.

Usage

Requires Node.js 18+. Run coldstart init to complete all setup for navigation and the notebook. It asks about the experience mode (cli recommended, or mcp) and the client, then writes agent-facing guidance into the client's own rules file, connects the client, and sets up the notebook (skeleton, git wiring, and capture/recall hooks for Claude Code, Codex, and Cursor). You can use --experience / --client to skip the prompts. The client is never auto-detected; it is always chosen by the user.

• Claude Code: writes coldstart.md, ensures CLAUDE.md imports it via @coldstart.md, and registers the find/gs search hooks and notebook recall/capture hooks in .claude/settings.json, merging into existing settings without overwriting. The mcp experience also writes .mcp.json.
• Codex: inlines the full coldstart guidance in a marked block in AGENTS.md, and registers Codex-specific navigation and notebook hooks in .codex/hooks.json. The mcp experience also writes [mcp_servers.coldstart] to .codex/config.toml.
• Cursor: writes .cursor/rules/coldstart.mdc, and registers Cursor-specific navigation and notebook hooks in .cursor/hooks.json. The mcp experience also writes .cursor/mcp.json.
• Other: writes only coldstart.md, and prints wiring instructions (the mcp experience also prints the MCP server entry).

init warms up the index in the background so the first lookup is instant. Re-running init is safe and will not duplicate entries. Version stamping causes the old background keeper to shut down on the next lookup, and a new keeper is spawned from the new binary, with no manual restart needed.

coldstart provides two entry points in a single binary: the CLI (primary, coldstart find / gs / kb, suitable for agents with a shell) and MCP (for shell-less clients such as Claude Desktop, providing the find, gs, and kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases tools, byte-identical to the CLI). kb commit is CLI/human-only.

Migrating from coldstart-mcp: the package was renamed from coldstart-mcp to @cstart/coldstart in 2.0.0; coldstart-mcp is deprecated but still worksInstallation. Switch commands: npm uninstall -g coldstart-mcp && npm install -g @cstart/coldstart && coldstart init. The coldstart-mcp binary name is kept as an alias, and existing MCP configurations continue to work.

Removing coldstart: the per-repository wiring written by init cannot be reached by a global npm uninstall, so an unwire command is provided that removes only the markers owned by coldstart (hook entries, the @coldstart.md import, the AGENTS.md block, the MCP server entry, and files fully owned by coldstart), without touching user content in shared files. It scans all four clients, is idempotent, and by default preserves the notebook (since it is committed shared data). After running it in each project, then npm uninstall -g @cstart/coldstart.

When it applies

Best suited for use with Claude Code, Codex, and Cursor, all three of which get platform-specific find/gs hooks and notebook recall/capture hooks from coldstart init. Other clients get coldstart.md and printed wiring instructions. The notebook's freshness mechanism is based on content hashes, so it works for any codebase, including languages whose navigation index does not parse; where the index can parse, notes also get symbol-level freshness.

Limitations

coldstart has no embedding vectors, no generated summaries, and no semantic layer computed at index time, and this is intentional: the semantic layer is borne by the agent. The index keeps only cheap and precise content—paths, symbols, exports, import/call graphs—and returns the top-ranked reasons for each file. The notebook still does not compute meaning on its own; it only stores, anchors, and freshness-checks the meaning written by the agent. The notebook is still young; what has been verified is: notes written by the agent in real sessions are accurate when checked against the code; the stale-note loop closes end to end; capture, recall, and concurrent writes hold up under stress. Its bet is that such a corpus will compound over the repository's lifetime.