This page maps questions to code.* ops. Every argument and output is in the
generated operations reference, and in each op's
MCP description.
All read ops take org / namespace. When a call omits them, the MCP transport uses
the X-Loom-Code-Scope: <org>/<namespace> header the coding-agent plugins send for the
current checkout, and otherwise the deployment's default code namespace
(LOOM_CODE_ORG / LOOM_CODE_NAMESPACE). Explicit arguments win, and authorization
runs on the named namespace either way: a header naming a namespace the token cannot
read is refused, never widened. With no default set, a call that names no namespace is
refused with a validation error.
Several ops also take namespaces=[…] (up to 8) to ask across branch indexes at once.
Every answer that returns results carries a trace_run_id; report what you did with the
hits through code.outcome so ranking learns from it.
The same call in each surface:
# HTTP
curl -fsS -X POST "$LOOM_BASE_URL/v1/code.search" \
-H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"org":"acme","namespace":"code-myrepo","query":"where are request quotas enforced?","top_k":5}'MCP, the loom_code_search tool:
{
"query": "where are request quotas enforced?",
"namespace": "code-myrepo",
"top_k": 5
}# Python SDK
from loom import Agent
async with Agent("acme", "support", "review-bot") as agent:
# agent.code.* sends no namespace: the server's default code namespace answers
hits = await agent.code.search("where are request quotas enforced?")
# any code namespace, through the generic call (fields win over the Agent's identity)
hits = await agent.call(
"code.search", namespace="code-myrepo", query="where are request quotas enforced?"
)
for u in hits["results"]:
print(u["path"], u["start_line"], u["symbol"], u["tier"])
await agent.code.outcome(hits["trace_run_id"], "used_in_answer")MCP listing. The coding toolset lists code.search, grep, enclosing, ask,
symbol, outline, callers, context_pack, impact, pr_check and
bisect_candidates. core lists the first eight only with LOOM_MCP_CODE_TOOLS=true
(default off); tracker lists impact, pr_check and bisect_candidates. Every other
code op is callable by name or through loom_op:
loom_op {"op": "code.index_status", "arguments": {"namespace": "code-myrepo"}}. These
are served over HTTP and the SDKs only: code.outcome, code.refresh, code.reindex,
code.calibrate, code.context_packs, code.coverage.watch, code.coverage.unwatch,
code.scip_ingest, code.scip_status; LOOM_MCP_CODE_UPLOAD_TOOLS=true serves the last
two over MCP as well. An op's MCP tool name is loom_ plus its name with dots as
underscores. Toolsets: MCP reference.
CLI. There is no client CLI for the read ops. loom code … (init, backfill,
reconcile, compact, reembed, backfill-prs, scip-full, scip-delta, warm,
describe, stats, …) is the server's admin CLI
(CLI reference,
code index operations).
| Op | Use it when |
|---|---|
code.grep |
you hold an exact string. Literal by default, regex=true for RE2; mode = matches, files, presence (across namespaces) or message (a printed message → the statement that prints it) |
code.symbol |
you hold a name: definitions with signature and span; uses=true adds every line that mentions it, near_paths ranks several definitions by the files you are in |
code.search |
you have a question in words. Hybrid symbol + lexical + vector retrieval; put an identifier you hold in pattern= |
code.ask |
you want a synthesized answer with citations (cached per question and invalidated when a cited file changes) |
code.files |
you want files by name, glob or basename stem |
code.enclosing |
you have path:line locations (up to 200) and want the enclosing function of each |
code.outline |
you would otherwise read a whole file to see what is in it |
code.map |
you want an orientation map of the repository's modules |
code.trace |
you have a stack trace: each frame resolved to its unit |
A caller with a clock of its own passes deadline_ms to code.grep or code.search
(clamped to 200–60000; 0 means none, and unset takes LOOM_CODE_SEARCH_DEADLINE_MS):
the request stops starting new work when the budget runs out and returns what it has,
partial: true with a partial_reason naming what did not finish (a grep scan stopped
by ClickHouse's break-on-timeout, a search leg, rerank, HyDE), instead of timing out.
A failed lexical or vector retrieval leg also returns partial: true. Its
partial_reason names the unavailable leg, and note warns that results are
incomplete. These warnings survive the default MCP result shaping and searches
across repositories. An empty result during an outage does not prove that no match
exists. Failed-leg results are neither memoized nor saved as continuation pools;
retry after restoring the provider or store. Choosing legs: "lexical" deliberately
is not a failure.
Providers that record request outcomes expose failures in /v1/health under
providers_degraded and problems, and in the dashboard's Health view. A successful
recorded call clears its warning. Other providers and constructor failures can
produce a search warning without a health warning. Check credentials, permissions
and quota. Health reads make no provider calls and cannot detect expired credentials
before a real request encounters them.
In mode: "message", a pattern that matches no statement template (a code line rather
than a rendered message) is grepped once more as a literal and the answer says
fallback: "literal".
Examples.
# Which release branches contain this string? One call, one row per namespace.
curl -fsS -X POST "$LOOM_BASE_URL/v1/code.grep" \
-H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"org":"acme","pattern":"retry budget exhausted","mode":"presence","namespaces":["code-myrepo","code-myrepo-2-4"]}'d = await agent.code.symbol("QuotaLimiter::check", uses_brief=True, include_body=True)
located = await agent.code.enclosing(["src/quota/limiter.py:88", "src/api/routes.py:140"])code.search fields worth knowing: path_prefix, path_globs / exclude_globs
(rg -g), langs (rg -t), pattern (constrains both legs to chunks containing it),
bodies: "none" (spans and signatures only, the cheapest answer), token_budget,
expand (one LLM hop to bridge wording to identifiers) and cursor for the next page.
Repository Markdown and imported knowledge documents take different paths. An indexed
.md file has a symbol for each heading. Outside fenced code blocks, a backticked
identifier such as enforce_quota can create a reads edge from that section to a code
definition when the name resolves uniquely in the same namespace. Ambiguous names and
unsupported reference forms create no such edge. This is a recorded textual reference,
not proof that the implementation satisfies the specification.
Use an indexed repository, a token that may read it and the coding
MCP toolset. Check the branch and indexed revision before comparing documents and implementation;
editor changes are not indexed. The names below illustrate the call shapes: replace them
with a section and definition returned from your repository, rather than expecting these
example names to exist.
-
Find the specification with
loom_code_search, using the repository'snamespace, a question such as "where is request quota enforcement specified?", andpath_prefix: "docs/"when that directory is indexed. Read the returned section and copy its exactsymbolvalue. -
Follow that section's recorded references with
code.calleesthroughloom_op:{ "op": "code.callees", "arguments": { "namespace": "code-myrepo", "name": "docs.quotas::Quotas::Enforcement", "edge_kinds": ["reads"], "depth": 1, "max_nodes": 20, "explain": true } }Each returned
edgesitem names its target into_symbolandto_symbol_id;pathandlinelocate the reference in the document. Keep the edge's confidence and any ambiguity or truncation warning.explainbelongs insideargumentsand keeps the full result; ordinary MCP compaction can omit symbol IDs and a repeated target name. -
Read the target and find documents that cite it with
code.symbolthroughloom_op:{ "op": "code.symbol", "arguments": { "namespace": "code-myrepo", "name": "enforce_quota", "include_body": true, "explain": true } }Prefer the previous edge's
to_symbol_idassymbol_idwhen selecting one exact definition.definitionscontains the implementation;documented_inlists up to five citing sections with theirsection,pathandline. Read those sections before describing what they require. An absent link or an elided body does not prove that documentation or implementation is absent. For more recorded references, usecode.callerswithedge_kinds: ["reads"]and inspect the document paths among its results.
An internal document synced into the repository's trunk code namespace is knowledge
content, not a Markdown symbol in that branch's code graph. With a readable
X-Loom-Code-Scope: acme/code-myrepo MCP connection, loom_search can retrieve the
repository's documents alongside the caller's other content. It has no namespace
argument: setting a namespace on a separate code call does not set this connection scope.
A document source must be configured and synced; its worker needs
LOOM_KNOWLEDGE_SOURCE_SYNC_ENABLED. See document sources
and search scope.
Search for the symbol name and the behavior it implements, then inspect
structuredContent.knowledge.results: the MCP text summary quotes only an excerpt.
Preserve the returned source_uri, section, revision and any locator when
citing the passage. A knowledge revision is not a Git commit. Repository tags group
ordinary synced documents for retrieval; they do not create symbol edges or grant access.
A retrieved passage that names a symbol still needs an explicit code lookup and a human
or agent comparison. This workflow does not automatically join imported documents to
symbols, verify their claims, or prove that a missing search result means no document
exists. These call shapes are not captured output from a document/code qualification run.
| Op | Use it when |
|---|---|
code.callers |
who calls this, depth hops; an override also reports the base declaration's callers |
code.callees |
what this calls, depth hops |
code.impact |
blast radius of a symbol, or of files / a diff: callers, tests reaching the change, co-change partners |
code.test_gate |
which tests a change obliges, and which touched functions no test reaches |
code.tests_for |
which tests cover something |
code.test_home |
where a new test belongs |
code.coverage_claim |
"is this already tested?" |
code.verify |
check one closed-form claim ("A calls B", "X overrides Y") against the index |
code.verify_citations |
resolve every path:line / symbol citation in a draft before sending it |
code.path_guards |
the conditions that stand on the call path between two symbols |
code.examples |
real call sites of a symbol |
code.setting_facts |
what the tree says about one ClickHouse setting (declaration, change history, CI randomization); meaningful only for a ClickHouse source tree |
code.callers / code.callees take min_confidence to drop parser-tier edges below a
grade (compiler edges are always 1.0) and include_ambiguous to add the call sites the
resolver declined as a separate candidate_sites block. Read epistemic and causes
on the answer (overview.md).
Example: impact of a diff.
import subprocess
diff = subprocess.run(["git", "diff", "origin/main"], capture_output=True, text=True).stdout
r = await agent.code.impact(diff=diff, exclude_authors=["me"])
print(r["epistemic"], r.get("causes"))
for row in r.get("co_change_missing", []):
print("usually changes with this diff:", row)The diff shape returns the symbols the hunks overlap, the tests that reach them, and
co_change_missing; files alone treats every function in those files as changed.
Both shapes return owners: recency-weighted PR authors over the seed paths, with
exclude_authors (normally the change's own author) removed. The index holds merged
code, so the diff is read against the branch head; your uncommitted functions resolve
only when they already exist there.
These read the PR plane that the code_pr_history worker fills from GitHub
(LOOM_CODE_PR_HISTORY_ENABLED). A release-branch namespace's history holds the PRs
merged into that branch. How the plane is filled, and bisect and backports in depth, are
on history-and-prs.md.
| Op | Use it when |
|---|---|
code.context_pack |
briefing for a PR (pr_number), for a change you are about to make (task), or the repository; sections keeps only the blocks you will act on |
code.history |
merged PRs that touched a symbol or a path |
code.symbol_history |
merged PRs that changed one symbol, between two releases |
code.blame_range |
merged PRs behind a line range |
code.review_brief |
what reviewers checked on a merged PR |
code.conventions |
the repository's recurring review checks, over one PR |
code.pr_check |
before opening a PR: does a PR like this already exist (merged, open or closed)? |
code.bisect_candidates |
which merged PRs could have introduced a bug, from frames, paths, symbols and a good/bad window |
code.backport_gap |
which release branches still carry the bug one fix removed |
code.backport_gaps |
the set-wide report of fixes labelled for backport that some branch lacks |
code.first_build |
which CI build first carried a commit |
Example: duplicate check before a PR.
curl -fsS -X POST "$LOOM_BASE_URL/v1/code.pr_check" \
-H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"org":"acme","namespace":"code-myrepo","title":"Retry quota refresh on 503","paths":["src/quota/limiter.py"],"symbols":["QuotaLimiter::refresh"]}'verdict is duplicate_of (an open PR is doing this, or a merged one did), related
or none; items carry state, score and evidence lines. The check is heuristic and makes
no GitHub call; a title alone never reads as a duplicate.
| Op | Role | Returns |
|---|---|---|
code.repos |
viewer | readable entries with freshness, access and bootstrap stage; repo / repos narrow it to one checkout (a GitHub fork resolves to its parent's index) |
code.index_status |
viewer | watermarks, lags, tiers, commit_coverage (freshness.md) |
code.coverage |
viewer | per-language files, chunks, symbols per tier, edges, and gaps — what the index does not know |
code.index_errors |
viewer | files the indexer failed on |
code.recent_commits |
viewer | recently ingested commits |
code.context_packs |
viewer | stored PR packs |
code.outcome |
viewer | records what you did with a result (opened_file, used_in_answer, fell_back_grep, ignored) |
code.coverage.watch |
viewer | a code.coverage.ready task event on your inbox once a commit is covered; needs writer on the inbox's owner namespace |
code.coverage.unwatch |
viewer | drops a pending watch |
code.scip_status |
viewer | the state of an uploaded compiler-tier delta |
code.refresh |
writer | trigger an ingest pass now (freshness.md) |
code.scip_ingest |
writer | upload a compiler-tier delta from an external producer (applied by code_scip_apply) |
code.reindex |
admin | move the ingest watermark to a commit |
code.calibrate |
admin | refit the search's noise floor and abstain threshold |
Adding, branching, restricting and removing repositories (code.repo.add,
code.repo.remote_branches, code.repo.add_branch, code.repo.set_access,
code.repo.set_source, code.repo.remove) are on
repositories.md.
- overview.md — tiers, language support, reading an answer
- freshness.md —
as_of, commit coverage, CI refresh, coverage watches - history-and-prs.md — the PR plane, bisect, backports
- Python SDK reference, MCP reference
- operations reference — generated arguments