# Loom Code

> 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.

- Skill: `clickhouse/loom-code` (Agent Skill)
- Install (CLI): `npx get-skill add clickhouse/loom-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/clickhouse/loom-code/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: ClickHouse (https://skillmd.com/u/clickhouse)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/clickhouse/loom-code

---


# 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

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.

