Documentation

coldstart, command by command.

coldstart is one binary with two front doors — a CLI (the fast path for any shell-capable agent) and an MCP server (for no-shell clients), with byte-identical output. This page covers the stable core surface; for exhaustive flags, versioned changes, and internals, see the README and docs on GitHub — the source of truth.

The shape of itTwo operations answer navigation — find (which files?) and gs (what is this file, who uses it?) — and the kb family is the notebook: durable, agent-written notes kept honest by the index. That's the whole surface.

Install & setup

Requires Node.js 18+. Install globally, then run init once per project.

your-project
$ npm install -g @cstart/coldstart $ cd your-project $ coldstart init # coldstart.md + client wiring + notebook + hooks + warm-up

init asks two things — the experience and the client — then writes the coldstart guidance where that client will read it, creates the notebook, and registers the navigation and notebook hooks. It indexes the repo before it exits, so your first find is instant instead of racing a half-built index. A few seconds, once.

What it writes, per client

claudecoldstart.md, imported from CLAUDE.md, plus hooks in .claude/settings.json.
cursorThe guidance inlined into .cursor/rules/coldstart.mdc — Cursor doesn't resolve file references in rules — plus .cursor/hooks.json.
codexThe guidance inlined into a marked block in AGENTS.md, plus .codex/hooks.json.
othercoldstart.md and printed wiring directions for anything else.

Flags

--experience cli|mcpThe surface to wire. cli is the fast path; mcp also writes an MCP server entry.
--client NAMEclaude, cursor, codex, or other. Determines which config files get wired.
--commit-notebookOpt in to committing the notebook .raw logs so the team can share it. Private by default — see Sharing.

Upgrading and removing

$ npm install -g @cstart/coldstart@latest # upgrade $ coldstart unwire # unwire this repo, keeping the notebook $ npm uninstall -g @cstart/coldstart

On upgrade, running keepers notice the version bump and restart themselves. Re-run init only if a node or nvm change moved the global install — coldstart status tells you when that has happened. Unwiring keeps your notebook unless you pass --purge.

Codex onlyCodex asks you to approve hooks the first time — choose Trust all and continue, or launch codex from a terminal if the prompt never appears. For automated runs, pass --dangerously-bypass-hook-trust. openai/codex#21615 has the details.

The intended flow

find → gs → Read. Orient with two cheap calls before spending a token reading. Notebook summaries ride along on find, so the orientation step often answers itself.

  • find a concept → ranked candidate files, each with the evidence for why it ranked.
  • gs the best file → its symbols, importers, and per-symbol callers, in one call.
  • Read only the method body you actually need — not the whole file.

Where to next

NAVIGATION

find & gs

Locate the files for a concept, then drill into one file's shape, callers, and importers.
NOTEBOOK

The kb family

Durable, agent-written notes kept honest by the index — search, lookup, write, and share with a team.
UNDER THE HOOD

Freshness, MCP, languages

How the index stays current, the lifecycle commands, MCP tool exposure, and the supported-language set.
GRAPH

coldstart graph

See the whole repo at once, then walk it file by file. Try it on this codebase, or run the command on yours.