XERJ Searches Your Code So Agents Stop Reading Whole Files

It is rare to find a project whose most interesting feature is its own disclosure.

XERJ is a Rust search engine for code and documents, built for coding agents, with an Elasticsearch-compatible wire protocol and an Apache-2.0 license. It has a benchmark table with real dollar figures. It also has a maintainer note admitting that its GitHub star count is inflated roughly thirteenfold by a synthetic cohort, and asking people not to cite it.

Both of those things are worth your time, and they are related.

The problem it is aimed at

When a coding agent needs to understand a codebase, the default move is grep. Grep is honest: it finds lines matching a pattern. But an agent using grep has to read files to find out whether the match matters, and reading files is what fills a context window. A single large file can consume more tokens than the answer was worth.

XERJ's alternative is a local index. Point it at a folder, and autoindex sniffs file types, infers datasets, discards junk, and builds a separate index per dataset. The repository's own log from a real run reads like this: 593 datasets inferred, 1,955 junk or skipped files in phase A, then phase B indexing 25,329 files with eight workers, finishing in 158.1 seconds with 83,103 records live.

Code is parsed with tree-sitter, keeping symbols and line numbers instead of flattening everything into text. That is why xerj def <symbol> can return a file, a line, and a signature — a jump-to-definition across a repository, which is what an agent needed in the first place.

The benchmark, read carefully

The project ran eight tasks across four languages, sixteen runs per arm, and measured actual claude -p token consumption rather than estimating it. Three setups: memory only, grep-driven, and XERJ.

Memory only used 260,916 output tokens, cost $11.18, and solved 11 of 16. Grep used 26,477 tokens, cost $3.27, and solved all 16. XERJ used 9,982 tokens, cost $1.58, and also solved all 16.

So: about 2.7 times fewer output tokens than grep, 26 times less than relying on the model's memory, with no change in solve rate. The best single case — a Java task — saved 278 times. Users report roughly 5x end to end.

Now the caveat that makes this article worth writing. The repository's headline claims "40x fewer tokens than grep." The body's controlled experiment says 2.7x. Those numbers are not the same claim, and the gap between them is exactly the pattern that makes benchmark-driven marketing untrustworthy. To the project's credit, the README itself says to prefer the body's figure. A headline that oversells and a footnote that corrects it is a strange thing to ship, but at least the correction is there.

The constraint nobody mentions in launch posts

Here is the sentence that most search-for-agents projects omit: the benefit depends on whether the model already knows the code.

On private, internal, niche, or post-training-cutoff code, retrieval saves a lot, because the model genuinely cannot guess. On popular open-source libraries the model has seen ten thousand times, the index is neutral or actively harmful — you spend tokens retrieving what the model already knew.

That single constraint changes how you should deploy this. It is not a universal upgrade. It is a fix for a specific failure mode: agents working on code nobody has written a blog post about.

The --insecure flag is a real trust boundary

Running xerj --insecure disables TLS and API authentication. Anyone who can reach the port is effectively a superuser: read, write, delete every index, including everything under /_memory. That is fine on a single-developer laptop and catastrophic on anything shared.

The defaults are better than the flag. A new node binds to 127.0.0.1, and a plaintext bind to a non-loopback address refuses to start unless you explicitly set server.allow_insecure_network_bind = true. The project also records that running insecure on 0.0.0.0 was a real vulnerability — LAN clients could write without authorisation — and that it has been fixed. Naming your own past vulnerability is a good habit.

The disclosure that should be a template

In an instrumentation commit, the maintainer wrote that the repository's stars and forks were amplified about thirteenfold by a synthetic cohort, that real installation data is thin — roughly 145 release asset downloads and about 28 completed installs — and that Cloudflare RUM stopped recording in July, so the zero-traffic chart on the site is an artefact.

For a project with an Elasticsearch-compatibility claim and 1,371 conformance tests passing (zero failures, three skips), that is a remarkable thing to publish. It also tells you something about the current state of open-source signals: a star count is a marketing surface, and anyone who runs a growth loop can move it. The only numbers worth trusting are the ones an author volunteers against their own interest.

Other things you will meet

Installation is a curl pipe to shell, which verifies SHA256 and refuses to proceed if it cannot find a checksum tool — an unusually sane guard for that pattern. Builds are static musl with jemalloc, Linux-first, Windows by manual install. There is an MCP server exposing thirteen tools including xerj_plan and xerj_map, and xerj init wires up Claude Code or Cursor in one command. kNN with scalar8 quantization is supported. Multi-node deployment ships with a Helm chart and a compose file.

The version is 1.0.0-rc.x, and the CLI still moves. The CLA is adapted from Apache's, with a maintainer note that a lawyer has not reviewed it and two placeholder fields remain. Many commits are authored by coding agents and labelled as such, which is transparent and also a reason to read the code you depend on.

Reference coding, the use case nobody benchmarks

Buried in the README is the most interesting application: point the index at the nearest open-source project to the problem you are solving, then write your own version with the reference in context.

That is how a lot of real engineering gets done — find the library that already solved it, read it, then implement something narrower. Doing it badly means pasting half a repository into a prompt. Doing it well means being able to ask "where does this project handle backpressure" and getting a file, a line, and a function signature.

It also shows the limits of the benchmark above. Reference coding requires downloading and indexing someone else's repository, which costs time, disk, and network. The savings arrive on the second and third query, not the first. Anyone evaluating this should measure the whole session, not one task.

The Elasticsearch compatibility claim

XERJ speaks the Elasticsearch wire protocol, and the project reports 1,371 conformance tests passing with zero failures and three skips. If that holds, tools already written against Elasticsearch can point at it with minimal changes, and teams that have been paying for a cluster to hold a few million documents have an exit.

The pitch against Elasticsearch's SSPL licence is fair: SSPL is not open source in the OSI sense, and that matters to companies that want to ship a product on top of a search engine. But "compatible" is a spectrum. Query DSL coverage, aggregations, and analyser behaviour are where the differences show up, and the conformance suite is the only way to know which side of the line you are on.

Should you use it

If your agents work on internal code, large private repos, or logs and documents that no model has seen, the case is decent: a local, Apache-2.0, ES-compatible index with tree-sitter symbol awareness and an honest benchmark. If your work is mostly on public libraries, you will probably find grep and a good ripgrep configuration just as effective and far less to maintain.

And if you take one thing from this project, take the disclosure habit rather than the search engine. A tool that tells you its own numbers are inflated is worth more attention than one that tells you it is forty times better.