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
- 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.
- 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.
- 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.
- 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.
- 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).
- 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.
- 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
In Claude Code, 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.
1---2name: loom-code3license: Apache-2.04metadata:5 source: https://skillmd.com/skills/clickhouse/loom-code6 version: "1.2.0"7description: "Route-then-read code intelligence for a loom-indexed repository. WHEN: the repo is indexed by loom (LOOM_BASE_URL set, or a `.loom` marker), and you would otherwise read whole files, grep the tree, or guess who calls a function. Use loom's code.* tools to find the exact unit first, then read only that. FOR SINGLE OPERATIONS: call the code.* MCP tool directly."8---910# loom-code — find the unit, then read it1112Loom indexes the repository (tree-sitter + compiler tiers, merged-PR13history, tests, callers) and answers structural questions as-of the indexed14head. The index is a **router**: it tells you which unit to read, so the15read is one function instead of one file. Reading the whole file after a16`code.search` hit throws the saving away.1718## The loop19201. **Orient once.** `code.context_pack` (a `pr_number`, or a `task` sentence21 for a change not yet made) gives the briefing: touched symbols with callers, files that22 usually change together, related tests, recent PRs. Default budget23 2,500 tokens; sections are filterable.242. **Locate, don't browse.**25 - You know the name → `code.symbol` (qualified or bare; `Class::method`).26 - You know a phrase or a mechanism → `code.search` (`top_k` 5–10,27 `bodies: "none"` first; expand a single unit with the `next` call the28 result carries).29 - You know a regex or literal → `code.grep` (index-served, returns30 `path:line` plus the enclosing function).31 - You hold `path:line` pairs from a diff or a stack → `code.enclosing`32 resolves each to its innermost function.333. **Ask the graph, never infer it.** `code.callers` / `code.callees`34 (depth 1 unless you need more), `code.impact` for the blast radius of a35 change (callers, tests reaching it, co-change partner files),36 `code.trace` to resolve stack frames, `code.examples` for call sites,37 `code.history` for the PRs that touched a symbol.384. **Read the unit.** Open the file at the returned `path:start_line` and39 read that span. Only read more when the unit references something you40 did not get back.415. **Verify before you assert.** `code.verify` checks a claim ("X calls Y",42 "Z is defined in file F") against the index and answers `confirmed`,43 `refuted` or `not_established` (the graph is a floor: an absence is never44 `refuted`, so say the claim was not established).456. **Report what you used.** `code.outcome` with the `trace_run_id` from46 the response and an `action`: `used_in_answer`, `opened_file` (the paths47 you opened as `targets`), `fell_back_grep` or `ignored`. Outcomes train48 ranking; a silent session teaches nothing.497. **Before you open a PR, ask whether one exists.** `code.pr_check` with50 the draft — title, body, the paths you changed, the symbols, the issues51 it closes — answers `duplicate_of` (an open PR is already doing this, or52 a merged one already did: check main before you push), `related` (read53 those first) or `none` (open it). Items carry state, score and evidence54 lines; a title alone never reads as a duplicate. Callable by name.5556## Budgets5758Every op takes `token_budget`. Defaults are tuned per op (search 4k,59context_pack 2.5k, impact 3k). Ask for `bodies: "none"` on the first call60and expand one unit rather than raising the budget. `code.ask` returns a61grounded prose answer with citations; use it for "how does X work"62questions, not for locating code.6364## Merged code, not your working tree6566The index answers for the indexed commit (`as_of`). Files you have changed67and not merged are not in it: read those directly, and pass your diff to68`code.impact` (`files`, `diff`) for what the change reaches.6970## Trust the abstain7172Responses carry `abstain`, `abstain_code`, `retrieval_confidence`, and73`as_of` (branch, commit, `stale`, `not_covered`). `not_covered` means the74path is outside the indexed prefixes — go read the file. `stale: true`75means the index lags head; prefer the working tree for the files in the76recent commits it lists. A low-confidence hit is a hint, not a citation.7778## When you cannot call tools7980Some harnesses run without tool access (`claude --bare`). Loom's grep shim81(`integrations/grep-shim`) annotates every `grep`/`rg` line with the82enclosing function from the index, byte-identical output otherwise, so the83router still works through the shell.8485## Install8687In Claude Code, install either this skill (`loom-code-skill`) or the `loom`88plugin, not both: the plugin ships its own skill named `loom-code`.8990## Identity9192Org and namespace default to the deployment's code plane; set `consumer`93to your agent's name for trace attribution. A viewer token is enough for94every read; `code.refresh` needs writer.