loom-code — find the unit, then read it

Loom indexes the repository (tree-sitter + compiler tiers, merged-PR history, tests, callers) and answers structural questions as-of the indexed head. The index is a router: it tells you which unit to read, so the read is one function instead of one file. Reading the whole file after a code.search hit throws the saving away.

The loop

1. Orient once. code.context_pack (a pr_number, or a task sentence for a change not yet made) gives the briefing: touched symbols with callers, files that usually change together, related tests, recent PRs. Default budget 2,500 tokens; sections are filterable.
2. Locate, don't browse.
   • You know the name → code.symbol (qualified or bare; Class::method).
   • You know a phrase or a mechanism → code.search (top_k 5–10, bodies: "none" first; expand a single unit with the next call the result carries).
   • You know a regex or literal → code.grep (index-served, returns path:line plus the enclosing function).
   • You hold path:line pairs from a diff or a stack → code.enclosing resolves each to its innermost function.
3. Ask the graph, never infer it. code.callers / code.callees (depth 1 unless you need more), code.impact for the blast radius of a change (callers, tests reaching it, co-change partner files), code.trace to resolve stack frames, code.examples for call sites, code.history for the PRs that touched a symbol.
4. Read the unit. Open the file at the returned path:start_line and read that span. Only read more when the unit references something you did not get back.
5. Verify before you assert. code.verify checks a claim ("X calls Y", "Z is defined in file F") against the index and answers confirmed, refuted or not_established (the graph is a floor: an absence is never refuted, so say the claim was not established).
6. Report what you used. code.outcome with the trace_run_id from the response and an action: used_in_answer, opened_file (the paths you opened as targets), fell_back_grep or ignored. Outcomes train ranking; a silent session teaches nothing.
7. Before you open a PR, ask whether one exists. code.pr_check with the draft — title, body, the paths you changed, the symbols, the issues it closes — answers duplicate_of (an open PR is already doing this, or a merged one already did: check main before you push), related (read those first) or none (open it). Items carry state, score and evidence lines; a title alone never reads as a duplicate. Callable by name.

Budgets

Every op takes token_budget. Defaults are tuned per op (search 4k, context_pack 2.5k, impact 3k). Ask for bodies: "none" on the first call and expand one unit rather than raising the budget. code.ask returns a grounded prose answer with citations; use it for "how does X work" questions, not for locating code.

Merged code, not your working tree

The index answers for the indexed commit (as_of). Files you have changed and not merged are not in it: read those directly, and pass your diff to code.impact (files, diff) for what the change reaches.

Trust the abstain

Responses carry abstain, abstain_code, retrieval_confidence, and as_of (branch, commit, stale, not_covered). not_covered means the path is outside the indexed prefixes — go read the file. stale: true means the index lags head; prefer the working tree for the files in the recent commits it lists. A low-confidence hit is a hint, not a citation.

When you cannot call tools

Some harnesses run without tool access (claude --bare). Loom's grep shim (integrations/grep-shim) annotates every grep/rg line with the enclosing function from the index, byte-identical output otherwise, so the router still works through the shell.

Install

Install either this skill (loom-code-skill) or the loom plugin, not both: the plugin ships its own skill named loom-code.

Identity

Org and namespace default to the deployment's code plane; set consumer to your agent's name for trace attribution. A viewer token is enough for every read; code.refresh needs writer.