XERJ.code — reference coding

An agent that does not know an API guesses, runs, fails, and guesses again. Each lap costs output tokens, which are the expensive kind. This skill replaces laps with a lookup: clone the repositories that already contain a correct implementation, index them with XERJ, and retrieve the passage before writing.

The trade is deliberate. Retrieval spends input tokens, which are cheaper per token and cacheable; loops spend output tokens. See COSTS.md for the arithmetic and for the conditions under which this trade loses.

Status, stated plainly: measured, and the value is real but narrow. (Full case study with real tokens and dollars: docs/case-studies/reference-coding/CASE_STUDY.md, 2026-08-05.)

The comparison that matters is against native Claude Code — the same agent with tools that would grep the source itself — not a bare model. Measured across three regimes, same agent, one objective verdict (compiles + passes hidden tests):

• Unfamiliar code with a contract the model can't recall (a seal, a generational handle, a lazy refill, a specific hash scheme — measured across seven purpose-built libraries, 21 runs): native and xerj both solve 21/21; xerj uses 1.5× fewer output tokens and costs 1.3× less than native, because retrieval replaces the grep. Pure memory fails 1/21 and burns 6.5× the cost flailing. This is the win, and it is decisive. The compiler can leak an API name across a retry loop, but never a contract.
• Memorised code (any popular public crate — even a 256-value table, or a protobuf-style varint): retrieval is overhead. Pure memory is cheapest; injecting a big reference can be the worst arm, because the model re-emits what it was handed.

So: use this when the reference is code the model has not memorised — your own private/proprietary code, an internal API, a post-cutoff or niche library. On public library references the model already knows, it costs more than it saves. The native-vs-xerj gap grows with corpus size (grep pulls the whole tree into context; retrieval pulls one passage).

Since #977 the whole loop is inside the xerj binary — xerj corpus add / xerj corpus index / xerj code — plus the xerj_code_search MCP tool for agents without a shell. The old wrapper scripts (xc-corpus.sh, xc-index.sh, xc.py) are gone; your existing ~/.xerj-code corpora and indexes work unchanged (see Migration below).

Standing corpora for this repository (MANDATORY since 2026-08-06)

In the xerj repo, retrieval-before-writing is required for non-trivial engine work, not optional. Each corpus below has a pinned, licence-reviewed definition in hub/ — xerj corpus add --from hub/<name>.json rebuilds it at the same commits anyone else is using:

Approach-only sources: elasticsearch (AGPL-3.0 / SSPL-1.0 / Elastic-2.0) and sonic (MPL-2.0). Never copy their code into Apache-2.0 XERJ; for ES, pasting source would also falsify the project's public "shares no code with Elasticsearch" claim. meilisearch is MIT at the core but BUSL-1.1 for its Enterprise Edition parts — check the header/path first. Read the design, write our own implementation. Each manifest's review.use field says which bucket a repo is in; hub/README.md explains the three.

Operational traps, both hit in practice

• Nothing under /tmp. Clones live in ~/.xerj-code/corpora/, the index in ~/.xerj-code/data (override the root with XERJ_CODE_HOME). A /tmp data dir is lost on reboot and the whole corpus silently retrieves nothing.
• xerj corpus index <corpus> --fresh is the rebuild, and it never costs you a working index. It builds a replacement beside the existing one — under xc-<corpus>-b<stamp>-*, with an autoindex --state-dir of its own in ~/.xerj-code/autoindex-state/<corpus>/ — verifies it (autoindex exited 0 or 3 and _count > 0), switches state/<corpus>.json to it by atomic rename, and only then deletes the old indices, by exact name. A build that fails or comes back empty is removed and the old index, the old state file and the old state directory stay exactly as they were. Use it after the data dir was wiped or moved, when xerj code says the index is older than 30 days, or when a plain re-run says the state directory "cannot become generation authority". It is not xerj autoindex --fresh, which the command never forwards: that flag only discards autoindex's resume journal and is refused outright once a corpus generation has committed — which is why --fresh used to fail on every corpus that had been indexed before (#930).
• A record count the node does not answer is never read as zero. The count is a tri-state: a number, a 404 (no index matches — genuinely zero), or Unknown (timeout, 5xx, unparseable reply). Unknown authorises no delete and no swap: if the node cannot count the existing index, it is presumed to be a working one and no failed build is kept over it; if it cannot count the new build, nothing is deleted and nothing is switched. Only a number — or a 404 — authorises a delete or a swap.
• An interrupted FIRST build is kept, and xerj code says so. When a build fails after writing records and there is no working index to fall back to, the command keeps it rather than leave no corpus at all, and records salvaged: true plus the real autoindex_exit in the state file. Such a build can be partial, so xerj code warns on stderr with every query that coverage is INCOMPLETE — a miss is then not evidence that the code is absent — and xerj corpus list marks the corpus. A plain xerj corpus index <corpus> resumes it (same prefix, same state directory) and clears the mark when it finishes.
• A plain xerj corpus index <corpus> updates in place. It re-runs autoindex against the recorded build's prefix and state directory, so additions, edits, deletions and renames reconcile incrementally.
• The state file has two prefixes on purpose. prefix is always xc-<corpus> — the whole namespace, so anything that globs xc-<corpus>* keeps working across rebuilds. index_prefix is the one verified build, and it is what xerj code queries, so a half-built replacement never leaks into answers during a rebuild.
• During a rebuild both builds exist, so the node briefly holds the corpus twice. Budget disk for it on a large corpus.
• Always verify: curl -s "$URL/xc-<corpus>*/_count" must be > 0. The command does this itself and says so; do it again if you are scripting around it.

When this is worth it

Use it when the task touches code someone else has already written correctly:

• an unfamiliar library, framework, or protocol
• porting an algorithm whose reference implementation exists
• matching an established convention across a large codebase
• any time you have already looped twice on the same error — that is the signal that guessing is not converging

Do not use it for code that only exists in this repository (ordinary file reads are cheaper), for one-line edits, or when you already know the API. Indexing has a fixed setup cost; a task you would finish in two tool calls will not repay it.

The loop

xerj corpus add <name> <git-url>...   # clone reference repos (once per domain)
xerj corpus add --from <manifest>     # ...or rebuild a corpus someone else defined
xerj corpus index  <name>             # index them with xerj autoindex (once per corpus)
xerj code <name> "<what you need>"    # retrieve before writing (every task)

Status at any time: xerj corpus list shows every corpus in the ledger, its index prefix, whether it is loaded on this node (— loaded — N index(es) / — NOT loaded here (0 indices) — stale/other-server), and any INCOMPLETE marks.

1. Build a corpus

Group repositories by problem domain, not by language. A corpus for "async Rust" holds tokio, hyper, and tower; a corpus for "parsers" holds nom, pest, and tree-sitter. Keep corpora small and sharp — a corpus that contains everything retrieves like a search engine with no query.

xerj corpus add async-rust \
  https://github.com/tokio-rs/tokio \
  https://github.com/hyperium/hyper

Clones are shallow (--depth 1) and land in ~/.xerj-code/corpora/<name>/. Every build writes a corpus.json beside them — URLs, full commit SHAs and licences, a few hundred bytes, no source. That file is the shareable corpus definition: hand it to someone else and

xerj corpus add --from their-corpus.json

rebuilds the same commits on their machine (an existing clone is moved to the recorded SHA, so both trees match). Vetted definitions for the corpora this project uses live in hub/:

xerj corpus add --from hub/xerj-storage.json && xerj corpus index xerj-storage

Corpus names and repo names are validated before anything touches the filesystem — a name with /, *, a leading ., or a reserved word is rejected at parse time, because the pinned-clone checkout runs git checkout --force inside that path.

2. Index it

xerj corpus index async-rust

This runs xerj autoindex in-process against the local XERJ instance (--url / $XERJ_URL, default http://localhost:9200). Exit code 3 means "completed with junk files" and is not a failure — some files in any real repository are unparseable. Treat 0 and 3 as success; anything else is real. The node must be reachable; nothing is built offline.

3. Retrieve before writing

xerj code async-rust "graceful shutdown with a broadcast channel"

xerj code returns the matching definition, not a byte window:

─── valkey/src/networking.c  (score 12.68, BSD)
    [function addBulkStringToReplyIOV @ line 2635 — 366 of 272,498 chars]
static void addBulkStringToReplyIOV(char *buf, size_t buf_len, ...) {

That line number is the whole point. A record is one whole file, so ranking can only tell you which file matched; the definition is located from the symbols[] the index already carries. Before this, an 8 KB slice of a 272 KB file was a coin flip on whether the answer was inside it — a query about null replies correctly ranked networking.c and then returned its licence banner, because addReplyNull lives at line 1460. Read the named definition, cite it, and if the top hits are irrelevant say so and fall back to normal work rather than forcing them in.

--full N caps each passage at N chars (--full 0 prints the file head and says how to get the matching definition instead). --no-symbol falls back to a raw window (only useful for data files with no symbols at all).

Exit codes

xerj code distinguishes no match from broken from not loaded — script around it:

This is deliberately different from sibling xerj search, which exits 0 on an empty result — different tool, different contract.

Retrieval modes

The default is bm25. Measured across two corpora and twelve hand-labelled queries:

top-3 is the operative metric — the agent reads k passages, not one — and BM25 is perfect on it while never being the worst arm on either corpus. It is also ~5× faster, with no vector round trip and no mapping lookup.

Hybrid was previously the default, chosen on rust-text alone where it wins top-1. That was a corpus-specific result: on the C corpus the vector arm reaches only 5 of 407 indices (issue #173), so fusion mixes a good ranking with one that cannot see 98.8% of the material. Use --mode hybrid when a corpus has broad semantic_text coverage and you specifically care about top-1 — and measure it before trusting it.

xerj code rust-text "lazy DFA cache eviction"                 # bm25 (default)
xerj code rust-text "lazy DFA cache eviction" --mode hybrid   # + vector, RRF-fused
xerj code rust-text "lazy DFA cache eviction" --mode semantic # vector only

The table above was measured with the script-era client-side fusion. Since #977 hybrid is fused server-side: one native top-level hybrid query with {"fusion":{"method":"rrf","k":60}}, no client-side rank merging — so per-hit per-arm ranks are gone (the server does not expose them) and every hybrid run opens with an arms-ran note instead, e.g. [hybrid RRF(k=60) — BM25 over 9 index(es), vector over 3 of 9]. On a corpus where only some indices are semantic-capable, the fused query is aimed at the capable set only and the note names the excluded lexical-only indices — a semantic leg fired at a wildcard covering plain-text indices 400s the whole request.

A hybrid answer opens with a line naming the arms that actually ran, and says BM25 only — ... rather than pretending when the vector arm could not run (no semantic_text mapping for body, or the fused request failed). The vector arm only works where body is mapped as semantic_text, and a semantic query against an index where it is not does not degrade — it fails the whole search with a 400 and takes every other index in the wildcard with it. xerj code reads the mapping first and aims the vector arm only at capable indices. Hybrid also runs a BM25 size-1 preflight: if the lexical arm finds nothing, the answer is an honest miss (exit 1) — with the lexical embedder, vector nearest-neighbours are not evidence of a match.

xerj code never requests highlight. On this engine a highlight block changes _score and reorders hits (issue #177): identical query, top-1 6/6 without it and 1/6 with it. Since passages now come from symbols[], the highlighter bought nothing and cost ranking.

No shell? The MCP tool

Not every agent can run commands. The same pipeline is the eleventh MCP tool, xerj_code_search (see xerj mcp; registration snippets per client live in the llms docs, not here). Its text output is byte-identical to xerj code's prose — same hits, same !! licence warnings, same footer — with the exit triangle mapped onto MCP's boolean: refusals (30-day staleness, corpus not in the ledger, corpus not loaded on this server, transport failure) are isError: true with the remediation in the text, while a no-match is isError: false — a miss is guidance, not a tool failure. Warnings ride the successful text payload (MCP has no stderr). licence_policy: "strict" additionally strips the passage text from restricted-licence hits, keeping locator + licence + the approach-only warning.

Rules that keep this honest

Retrieved code is evidence, not authority. A passage proves how that project solved the problem under its constraints. Cite file:line when you rely on it, and say plainly when you are adapting rather than copying.

Check the licence before copying. xerj corpus add records each repository's licence in corpus.json, and every hit from a restricted licence (AGPL, SSPL, Elastic, BUSL, GPL family, MPL, unknown) carries the warning line !! <licence>: adapt the APPROACH, do not copy the code directly under its passage. Copying a GPL implementation into a permissively licensed project is a real problem, not a technicality. Adapt the approach and write your own code when the licences are incompatible.

A stale index is worse than none. It returns code that no longer exists and sends the agent down a dead path with false confidence. xerj code refuses to answer from an index older than 30 days unless you pass --stale-ok; re-run xerj corpus index <corpus> --fresh instead.

Never index the working repository into a shared corpus. Reference corpora are for other people's code. Mixing your own in makes retrieval return your own mistakes as precedent.

MEATL

For agent-to-agent and agent-to-tool exchanges, xerj code --meatl emits one machine-readable line per hit — a compact, checkable format that cuts output tokens on the messages no human reads. It is explicitly not for user-facing text: prose to a person stays prose. A summary compressed into arrow chains costs the reader more than it saves the budget. The grammar:

@ok f=<file>:<line> score=<12.34>[ why=<licence>]   # one per hit
@ok f=<file>:<line> rrf=<0.1234>[ why=<licence>]    # native-hybrid scores
@no q="<query>" why=no-match-in-corpus              # a miss (exit 1)
@mode <arms-ran note>                               # hybrid/semantic note line

f is the provenance locator path:line exactly as the prose block prints it; why is the licence recorded in corpus.json for that hit's repo (absent when unknown). A MEATL miss keeps exit 1 and its no-match record.

Measuring it

The published numbers, the per-run raw data and the price model live in docs/case-studies/reference-coding/: CASE_STUDY.md for the write-up, COSTS.md for why output tokens are the expensive kind, data/results-*.json for the runs behind each figure, and generated/ for code the two arms actually produced.

The measurement harness itself (csrun.py, the purpose-built reference libraries, the hidden-test task specs) is not shipped in this repository — the retrieval loop it drove now lives in the binary, and the SWE-bench-shaped harness beside this skill (swebench/gen_predictions.py) drives xerj code the same way. What that harness does, if you want to build the equivalent: run three arms of the same agent — bare (memory only), native (it greps the corpus tree itself), xerj (the retrieved passage is injected) — over tasks whose verdict is objective, i.e. the generated code compiles and passes a hidden test the model never sees. Report medians, not means: one flailing trial can be 5× another.

Two rules that decide whether a result means anything:

• Validate the tasks before spending a token. Inject the reference-correct solution (must pass) and a plausible wrong one — correct but quadratic, or missing the contract — which must fail. A benchmark whose tests pass wrong code measures nothing.
• Do not measure on code the model has memorised. It reproduces even a 256-value table from recall, and retrieval then shows as pure overhead. The honest test bed is code that was never in a training set — your own private code is the realistic case.

After the session: xerj feedback

If you want to tell the maintainers what using XERJ was actually like, one command drafts the report and fills in the facts it can observe (version, OS, what was indexed) for you:

# opens the PR (branch + commit of ONLY the report + gh pr create):
xerj feedback --open-pr --used-for "reference coding" \
  --verdict "…what worked, what did not…"

# sandboxed and cannot push? draft it and print the exact git+gh commands:
xerj feedback --dry-run --used-for "reference coding" --verdict "…"

It only ever auto-fills facts it can observe and leaves every opinion as a placeholder for you to fill — never an invented verdict. A pull request that adds only a field report is exempt from the CLA gate. xerj feedback --help has the full contract. This is offered, not asked: the automatic nudge that used to print after queries is gone (2026-09-18 directive — no obligation language, and never ask an agent for a pull request), and no marker file is written either way.

Migration from the wrapper scripts (#977)

The capabilities moved into the binary; nothing about your data moved:

Your existing ~/.xerj-code corpora, state files and indexes work unchanged — same layout (corpora/, state/, autoindex-state/, data/), same corpus.json schema, same xc-<corpus> index namespaces, same exit-code triangle. python3 is no longer required; git still is (for xerj corpus add). One deliberate change: hybrid fusion is server-side now, so per-hit per-arm rank annotations are gone and the arms-ran note carries that duty.