Coldstart

What AkashGoenka/coldstart MCP server does

AkashGoenka/coldstart MCP server gives coding agents two repository-local sources of context: a static navigation index and a durable notebook. The index helps answer which files are relevant to a task by examining paths, symbol names, exports, and import or call relationships. It is deterministic and does not depend on embeddings, a hosted service, or a model running locally.

The notebook stores agent-written Markdown under .coldstart/notebook/. Notes can describe a file, explain a multi-file flow, or record a lesson such as a bug cause, invariant, rule, or confirmed absence. Each note includes file and symbol anchors. When the indexed evidence changes, the note can be marked stale rather than presented as current knowledge. Because the notes live in the repository, they can be committed and reviewed with the code.

How it works

Run coldstart init from a project to create the guidance, notebook structure, client wiring, and background index warm-up. Initialization asks which experience to use—cli or mcp—and which supported client configuration to update. The client is selected explicitly rather than detected automatically.

Navigation is exposed through commands such as coldstart find and coldstart gs. Notebook operations include searching notes, looking up an exact file or symbol, writing through a deduplication gate, committing notes to Git, viewing the notebook in a single-file HTML browser, and checking or repairing notebook state. Search results can include summaries and a freshness indicator when the referenced file is unchanged from the version used to verify the summary.

For Claude Code, Codex, and Cursor, initialization can add prompt recall and task-end capture hooks. It also adds navigation-related hooks, including a nudge after tool use and a guard against repeated find lookups. An advisory “Edited together” signal can identify files that commonly change alongside recently edited files according to Git history.

Setup and configuration

Install the package globally with Node.js 18 or newer:

npm install -g @cstart/coldstart
cd your-project
coldstart init

The --experience and --client options can avoid the interactive questions. Claude Code receives an imported coldstart.md and merged entries in .claude/settings.json; Codex receives an inline block in AGENTS.md and hook configuration in .codex/hooks.json; Cursor receives .cursor/rules/coldstart.mdc and .cursor/hooks.json. Selecting the MCP experience also writes the corresponding MCP configuration for these clients. Other clients receive coldstart.md and printed wiring directions.

AkashGoenka/coldstart MCP server can be upgraded by installing the latest global package and running coldstart init again in each repository. coldstart unwire removes its wiring while keeping the notebook by default; coldstart unwire --purge also removes the notebook and its Git plumbing.

Limitations and notes

The project is designed for codebase context rather than general-purpose semantic retrieval. Its navigation uses static indexing and checkable relationships, not similarity scores. Notes are only as reliable as their anchors and freshness state, so stale or repair-needed entries may require review. The provided material documents direct support for Claude Code, Codex, and Cursor; it does not identify Claude Desktop, Windsurf, or Cline as supported clients.

The package was renamed from coldstart-mcp to @cstart/coldstart at version 2.0.0. The older binary remains as an alias for existing MCP configurations, but the CLI is the primary interface.