Under the hood

How it stays current

One background keeper watches the repo and patches an on-disk cache; readers never build. No cache TTL — the index is never discarded for being old, it's kept correct.

How the index stays fresh

coldstart is one keeper, thin readers. A single background keeper watches the repo and keeps an on-disk cache current; the readers (find, gs, the MCP server) are stateless and never build. There is no cache TTL — the index is never discarded for being old, it's kept correct.

keeper — coldstart --daemon watches repo → patch/rebuild → saves cache · serves nothing on-disk cache coldstart findreads cache, prints coldstart gsreads cache, prints MCP serverreads cache, stdio
WHILE RUNNING

Patched as you type

Edits debounce (400 ms), then patch incrementally (~2–5 ms/file) or trigger a background rebuild. Re-saved in atomic generations — a reader never loads a half-written mix.

ON START

Reconciled, not rebuilt

Stat-checks every file against its fingerprint plus a git diff, and patches exactly what changed. A branch switch that used to force a full rebuild is now typically a few seconds.

AS A BACKSTOP

Linted & audited

Every patch is checked against index invariants (a violation auto-rebuilds), and a rotating fingerprint audit after each save catches watcher-missed drift.

Full internalsThe exact pipeline (walk → parse → resolve → graph → cache) and per-language resolver notes live in ARCHITECTURE.md on GitHub.

Lifecycle commands

coldstart statusKeepers on this machine: alive? fresh? last operations? It also reports install health — if any keeper is running an older version than the installed binary, run coldstart restart; if a repo's wired hook paths no longer exist (node/nvm change), run coldstart init there.
coldstart restartKill the current repo's keeper (respawns on next lookup). --root DIR targets another repo; --all kills every keeper. A fresh keeper reconciles on start, so it comes back correct, not just alive.
coldstart indexBuild + save the cache once, up front (single-writer prep).
coldstart --versionPrint the installed version and exit (-v works too).
When anything feels staleRun coldstart restart first. If an update doesn't seem to have taken effect, coldstart status tells you whether the keeper is on the old version (restart it), a hook path is dangling (re-run init), or the install didn't update. TROUBLESHOOTING.md on GitHub has recovery steps.

MCP tools

For no-shell clients (like Claude Desktop), the same engine is exposed as MCP tools with byte-identical output to the CLI.

find · gsThe two navigation operations.
kb_search · kb_lookupRead the notebook.
kb_write · kb_status · kb_repair · kb_repair_aliasesWrite to and inspect the notebook. kb_repair lists notes that are written but unfindable; kb_repair_aliases lists notes whose aliases may no longer be true.
Not exposedkb commit and kb view stay CLI/human-only — publishing to git and opening a browser are never agent actions.

Bring your own semantics

coldstart has no embeddings, no generated summaries, no semantic layer computed at index time — on purpose. The semantic layer is the agent. The index keeps what's cheap to keep exact — paths, symbols, exports, the import/call graph — and returns why each file ranked. The notebook applies the same rule to memory: it stores and freshness-checks the meaning agents author, and computes none of its own.

Read the argumentThe full case is in PHILOSOPHY.md on GitHub, or see how this plays out against vector RAG specifically.

Supported languages

Tree-sitter for the parsed set; the notebook's content-hash freshness works on all of them — notes on a Swift repo are as trustworthy as notes on a TypeScript one (they just lack symbol-level freshness).

TypeScriptJavaScriptJSX / TSX VueSvelteAstroAngularJS PythonRuby (Rails)GoRust JavaKotlinC#PHP (Laravel)C++ Groovy / GradleGraphQLYAMLTOMLXML.env

Not indexed: Swift, Dart — no extension mapping; these files aren't walked or parsed. The notebook still works on them.