ultraindex-nav

ultraindex-nav — navigate a huge repo through its index

This is the light consumer of an ultraindex build. Instead of reading a large repo into context, you ask the prebuilt index where to look and open only what the task needs. The same zero-dependency bundle ships here: node scripts/ultraindex.mjs <command>. No npm install, no keys.

The core rule: load the minimum. Use find to get the exact files, open those entries/files one at a time, and answer. Do not read graph.json or the whole encyclopedia/ directory — that defeats the purpose.

Workflow

1. Locate the index. Look for .ultraindex/ (default) or docs/ultraindex/ at the repo root. Then check freshness:

   node scripts/ultraindex.mjs check --out <index-dir>
   

   • Missing (no index dir): tell the user to build it first — node scripts/ultraindex.mjs build --repo <repo> (the ultraindex skill) — and stop. Do not auto-build; building also expects a light enrichment pass.
   • Stale (check reports changed files): proceed, but warn the results may be slightly out of date and suggest a rebuild.
   • Fresh: continue.

2. Orient (once, cheap). node scripts/ultraindex.mjs map --out <index-dir> prints INDEX.md — the project summary, hub modules, and module table. Read it to understand the shape of the repo.

3. Find the relevant files for the task.

   node scripts/ultraindex.mjs find "<task keywords>" --out <index-dir>
   

   It returns the top modules with their exact source files to open, the matched terms, and graph neighbours. Use neighbors <file|module> to expand along the graph ("what else touches this").

4. Load only those. Open the listed encyclopedia/<module>.md entries (for the business + code overview) and the specific source files — one at a time, stopping as soon as you have what the task needs.

5. Act and answer, citing the concrete files. If you discover the index was wrong or stale enough to mislead, say so and recommend re-running the generator's build.

Answering a question (grounded mode)

When the user asks a question about the codebase (not "do a task"), answer it from real code, not memory — and prove it:

1. Assemble evidence.

   node scripts/ultraindex.mjs ask "<the question>" --out <index-dir>
   

   This finds the relevant modules and prints their real source (with line numbers) plus which files to open. Read it; open more files from the listed ones if a thread is thin.
2. Write the answer to ANSWER.md, citing every claim with the evidence it rests on, in bare brackets: [file], [file:line], or [file:start-end] (e.g. Retries use exponential backoff [src/util.ts:2-4]). A markdown link [text](path), or a citation inside a code fence/inline-code, does not count — write the citation in the prose. Every answer needs at least one citation.
3. Verify grounding.

   node scripts/ultraindex.mjs check --answer ANSWER.md --out <index-dir>
   

   It fails if the answer has no citations or any citation doesn't resolve to a real file/line. Fix and re-run until it passes, then give the user the answer with its citations. Never present an answer that hasn't passed this check.

Notes

• The index is read-only here — this skill never writes to it (apart from your ANSWER.md scratch file). Refreshing/enriching the index is the ultraindex (generator) skill's job.
• find/neighbors/map/ask print only the slice you asked for, so each call is cheap. Chaining a few is still far less context than reading the repo.