Ctx Search

Ctx Search

Navigate docs/code with a strict breadth-first flow and seeded context.

Tools

Use npx @anduril-code/ctx CLI commands.

All commands are invoked as npx @anduril-code/ctx <command>.

Strategy (high-signal defaults)

1. Default to exec for multi-file research. When you need to read 3+ files, or when results from one call feed into the next, use a single exec call instead of separate commands. One exec replaces many sequential reads/outlines/symbols calls and cuts round-trips dramatically.
2. Build a narrow first-pass context:
   • gather "<query>" --maxTokens 1200 --seeds <seed files>
   • If blocked, rerun with --maxTokens 2200
3. For file targeting, run rank before opening content.
4. For code files, prefer outline then read.
5. For symbol-level understanding before edits, prefer focus.
6. For Markdown, run sections first, then extract --only exact headings.
7. Use imports to trace dependency flow when understanding module relationships.
8. Use symbols to find definitions and call sites for specific functions/types.
9. Treat read output as triage only; anchor any final claim with line-aware evidence (outline or rg -n + sed -n).

When given a file path

1. If Markdown: sections → extract --only/read
2. If source code: outline → read
3. If symbol-specific: focus <file>::<symbol>
4. To understand context: imports for dependency graph, symbols for usage sites

When given a question or topic

1. gather "<question>" --maxTokens 1200 for auto-discovery
2. Or manual: tree → rank → read top-ranked files
3. For docs: add locate to search across markdown headings
4. For code: add outline and symbols for structural context

Prefer exec for multi-file and chained exploration

Always reach for exec first when your task involves reading multiple files, cross-referencing results, or chaining ctx calls. A single exec call that reads 7 files and cross-references their contents is far better than 7 separate read calls. Only fall back to individual commands when you need just one or two simple lookups.

npx @anduril-code/ctx exec '
const t = await tree({ depth: 2 });
const files = [];
function collect(entries) {
  for (const e of entries) {
    if (!e.isDirectory) files.push(e.path);
    if (e.children) collect(e.children);
  }
}
collect(t.entries);
const ranked = await rank({ query: "authentication", files });
const top3 = ranked.results.slice(0, 3);
const contents = await Promise.all(top3.map(f => read({ file: f.file, maxTokens: 2000 })));
const syms = await symbols({ query: "validateToken" });
json({ top3, contents: contents.map(c => c.content.slice(0, 200)), syms });
'

Available functions in exec (all async — use await):

• Read-only: tree, read, context, gather, rank, focus, symbols, imports, outline, tokenCount
• Utilities: log(...) and json(value) to produce output
• Write (requires --allow-write): patch, insert, rename

Rule of thumb: if you're about to make 3+ ctx calls, stop and write an exec script instead.

When onboarding to a codebase

1. tree for shape + token map
2. gather with default seeds for broad context
3. outline entry points and core modules
4. extract exact sections from README/AGENTS as needed
5. imports on key modules to understand dependency flow

Hashes and editing

outline output includes hash:xxxx for every symbol. These hashes are used by the editing tools (ctx patch, ctx insert, ctx rename).

read --lineHashes annotates each line with lineNo:hash| content — use these 4-char hashes for ctx patch line-hash mode or hashline fallback. Line hashes are derived from line number + line content, so identical text on different lines gets different hashes. Hashes are valid for the specific content block where they were generated.

When you identify what needs to change, hand off to ctx-code.

Stop conditions

• Stop when you can answer with exact file references.
• Do not full-read large files unless ranked and required.
• Do not finalize recommendations without file + line references.

Workflow: search → edit → verify

This skill is phase 1 of a 3-phase cycle. NEVER use raw Edit/Write/MultiEdit tools for source changes. Always follow this sequence:

1. Search (this skill) — investigate, gather context, identify what to change
2. Edit — invoke ctx-code skill via the Skill tool, then use its patch/insert/rename commands
3. Verify — invoke ctx-verify skill via the Skill tool to review diffs and run tests

When you know what to change → STOP and invoke the ctx-code skill before touching any file. Do not call Edit/Write directly.