Navigation
find & gs
Two lookups answer "where does this live?" and "what is this file?" without a model call — rank candidate files for a concept, then inspect one file's symbols, importers, and callers. Why it's built this way →
coldstart find navigation
coldstart find <term> [term…] [flags]
Which files are about this? Ranks files by how many of your query terms each covers — filenames, path segments, exported symbols, plus a repo-wide name-reference pass — and shows why each ranked: which terms it defines vs. imports.
coldstart find
$ coldstart find auth session cookie src/auth/service.ts 3/3 defines auth, session, cookie Summary [fresh] Signs and verifies session cookies. src/middleware/session.ts 2/3 imports session, cookie
Pass every salient identifier from your task — the symbol, the domain noun, the rare token you half-remember — not one distilled keyword. find ranks by coverage and shows where the terms cluster, often answering without opening anything. Its reference pass runs on ripgrep, competing with raw grep on speed.
--path GLOBScope to matching paths. Comma-combine; prefix ! to exclude.
--testsInclude test files (excluded by default).
--viaShow name-reference relations — where the terms are referenced, not just declared.
--jsonMachine-readable output.
When find says "no indexed file contains any of […]"Those identifiers aren't in the repo. Don't grep spelling variants — trust the negative.
coldstart gs navigation
coldstart gs <file> [flags]
What is this file, and who uses it? Returns the file's top-level symbols (with line ranges), its 1-hop internal imports, who imports it, and per-symbol cross-file callers — in one call. This is the answer to "who calls this?", not a grep.
coldstart gs
$ coldstart gs src/auth/service.ts symbols signCookie L12 · verify L34 · rotate L61 callers verify ← middleware/session.ts, routes/login.ts imported by 4 files moves with tests/session_test.py (9 of 14 commits)
--symbol a,bDeliver the named method bodies inline — skip a separate Read.
--match TERMFilter a god-file to one area. a|b = OR, /regex/ = regex.
--view VOne of symbols / imports / importers / callers. Default returns all.
--jsonMachine-readable output.
Edited togetherIn a repo with git history, gs also lists the files that keep changing in the same commits as this one, with the count as the evidence. It is a habit, not a dependency — nothing imports or calls across it — and it catches the pairs no parser can: a sibling implementation, a test in another language, a doc that has to stay in sync. Anything connected by an import edge is left out, so what you see is what the graph missed, and it shows up under --view too.
…and it comes to youYou don't have to ask for it. Once an agent has edited two different files in a task, the same signal is delivered to it automatically, naming the files that history says move with the ones it just changed. It's advisory — the message says plainly that this is a habit rather than a dependency, and asks the agent to check rather than to change anything. Each file is mentioned at most once per task, and the slate wipes clean every time you send a new message.
ScopeCallers are one-hop and file-scoped. Named function/constant calls resolve cross-file; member-expression calls (this.method(), api.method()) don't. Chase further hops by running gs on the caller file.
graph — the same data, as a picture
find and gs answer one question at a time, for an agent. graph is for you: it draws the whole repo as a sphere where every file is one point and latitude is the directory, then lets you click any point to walk the relations outward.
coldstart graph
$ coldstart graph .coldstart/graph.html 1,615 files in 24 directory bands, 3,905 relations (imports 1,525 · calls 555 · edited-together 1,825 · same-note 0) 656 files have no relation at all.
It writes one self-contained HTML file and opens it. No server, no build step, and no dependencies — the page is HTML, CSS, and a canvas script with your repo's data baked in, so it also works offline, over email, or in a gist. Nothing leaves your machine.
--out PATHWrite somewhere else. The default lands in .coldstart/ and is gitignored for you.
--no-openWrite the file without launching a browser.
--jsonPrint the counts instead of the prose summary.
Every line is namedClick a file and its neighbours fan out around it, each edge labelled with why it is there — imports, calls save(), load(), edited together · 13 of 42 commits, same note · <title>. Click a neighbour to open its connections; click one of those and the view slides along, so you are always looking at two levels rather than an ever-growing hairball.
Explore coldstart's own codebase in it →