Independent AI intelligence Two editions daily · ET
Fervor AI
Menu

Analysis · October 17, 2026 · repo

xerjagent-infrastructureclaude-codemcpagent-security

xerj Gives Your Coding Agent a Local Search Engine. Here's Where It Pays Off.

A single Rust binary that indexes any folder for agents. The README is unusually honest about when it helps and when it doesn't.

Coding agents spend a surprising amount of their budget just looking around.

Ask one to fix a bug in a codebase it hasn't seen, and it greps, opens a file, greps again, opens three more files, and slowly builds a picture of where things live. Every one of those reads costs tokens. On a big repo, the looking can cost more than the fixing. A local search index is supposed to end that, but only on certain kinds of code.

xerj, third on Trendshift's daily board when we read it on Saturday afternoon, with roughly 7.5k GitHub stars, promises to cut that bill by giving the agent a real search engine over your folder. The pitch is familiar. What's unusual is the README's own fine print: its numbers say the savings depend almost entirely on whether the model already knows your code.

That one detail tells you where to use it and where not to bother. The quickstart has a second detail worth knowing before you wire it to an agent.

What xerj is

xerj is a local search engine that ships as one file. You point it at a folder, and it builds a searchable index of everything in there.

"Local" matters here. By default, nothing gets uploaded to a cloud service to build the index (a few optional features can send text out, covered below). It runs on your laptop as a single static Rust binary, with no Java runtime and no database to install, under the Apache-2.0 license.

Two design choices make it useful for agents.

First, it speaks the Elasticsearch API. Elasticsearch is the widely used search server many companies run in production, and xerj answers the same requests on localhost:9200. So many tools that already know how to talk to Elasticsearch can talk to xerj, though it covers most of the API, not every corner of it. The README says it passes 1,366 of 1,369 Elasticsearch conformance tests (a standard suite that checks whether a server answers requests the way Elasticsearch does), while being clear that it's a separate implementation, not a fork.

Second, it reads a lot of file types and understands code. Source files get parsed with tree-sitter (a parser that understands code structure, used by many editors), so the index knows about functions and line numbers instead of just raw text. It also handles PDFs, Word and PowerPoint files, spreadsheets, CSV and JSON, notebooks, logs, and email archives.

For agents, there's xerj mcp, which exposes the index through MCP (the Model Context Protocol, the standard way coding agents like Claude Code and Cursor plug in outside tools). The README lists 13 tools, including plain search, hybrid search, code search, and a simple memory store. There's also xerj init, which the README says wires xerj into Claude Code or Cursor for you.

The number, and the sentence after it

The README reports a small controlled study: 8 coding tasks across 4 languages, 16 runs per approach, with token counts taken from real claude -p runs (Claude Code's non-interactive mode). Three approaches were compared:

  • Memory only (no search tools): 260,916 output tokens, $11.18, 11 of 16 solved.
  • Grep-driven agent: 26,477 output tokens, $3.27, 16 of 16 solved.
  • xerj: 9,982 output tokens, $1.58, 16 of 16 solved.

That's where the headline comes from: about 2.7 times fewer output tokens than grep, at the same solve rate, for roughly half the cost. The README adds that users report about 5x fewer tokens in daily work, based on field reports rather than a measured study.

Treat these as the project's own measurements. Eight tasks is a small sample, and the maintainers ran it themselves.

Now the sentence that makes this README worth reading. It says the gain depends on memorization. It helps most on private, internal, niche, or recent code, the kind the model never saw in training. On popular public libraries, it says the effect is neutral or even harmful.

That makes sense once you picture what's happening. Ask an agent about React, and the model already carries a rough map of React in its weights. It barely needs to search. Searching anyway just adds a step. Ask it about your company's billing service, and it knows nothing. Every grep is a guess, and that's where a proper index turns ten blind reads into one targeted lookup.

So the useful mental model is simple: an index helps an agent exactly where its memory runs out. Your internal monorepo is the target. Your side project built on three popular frameworks probably isn't.

The quickstart has a sharp edge

Here are the README's quickstart commands:

xerj --insecure --data-dir ./data &
xerj autoindex ~/my-project
xerj search "how do we rotate the WAL segment"

The --insecure flag turns off both encryption (TLS) and API-key login. The README says plainly that this makes every caller who can reach the port a superuser, meaning full read and write access to every index.

xerj does limit the damage. A fresh node only listens on 127.0.0.1, so other machines can't reach it, and the security model says an unencrypted node refuses to start on a public interface unless you explicitly allow it. The README frames --insecure as meant for one person on a dev machine.

That's a reasonable default for a human trying a demo. It's a weaker default once an agent is involved, because an agent runs commands and installs things on that same machine. Anything that can make a local HTTP request (a script the agent ran, a package's install hook, another tool) can then read or delete everything you indexed. If you indexed your email archive or internal docs, that's a lot to hand over to anything on localhost.

The fix costs one extra step. Leave auth on, which is the default without the flag.

Put this into practice

Here's a setup that keeps auth on and aims xerj where it pays off.

1. Install it. The README's install command is a script you pipe to your shell:

curl -fsSL https://xerj.org/get | sh

If piping a script into your shell makes you uneasy, and it's fair if it does, the README says prebuilt binaries exist for Linux, macOS, and Windows on x86-64 and arm64, and you can build from source with a stable Rust toolchain.

2. Start it with auth on. Skip --insecure:

xerj --data-dir ./data &

On first start, the security model says xerj generates a 64-character admin key, prints it, and saves it to ./data/admin.key with owner-only permissions. That key is the superuser credential.

3. Index the private code first. Pass the key when indexing. The README notes that autoindex won't read it from the config file, so use the flag or the environment variable:

export XERJ_API_KEY="$(cat ./data/admin.key)"
xerj autoindex ~/work/internal-service

Start with a repo the model can't know: internal services, a private monorepo, anything written after the model's training cutoff. Skip the popular open source dependencies.

4. Connect your agent. Run xerj init to wire it into Claude Code or Cursor, or add xerj mcp to your MCP config by hand. The README says the node must already be running, and that the MCP side needs the XERJ_AUTH setting when auth is on.

5. Check whether it's helping. Pick a task you'd normally give the agent, run it once with xerj connected and once without, and compare the token counts your tool reports. That's the same comparison the README ran, on your own code. If the numbers barely move, your codebase is probably one the model already knows well, and you can uninstall it without guilt.

Honest limitations

The benchmark is small and self-run. Eight tasks, run by the maintainers. The 5x figure comes from user reports, not a controlled test.

It's still a release candidate. The newest software release when we checked was v1.0.0-rc.96, from October 16. Expect changes.

Some access controls don't do what their names suggest. The security model says field-level and document-level security settings are ignored, and that one privilege-check endpoint (the API call a client uses to ask "am I allowed to do this?") answers true to every privilege it's asked about. Don't rely on either to restrict an agent.

A few optional features send your text away. If you add reranking to a search (a second pass where a model re-sorts the top results), the README says xerj sends the text of the top results to TypeSafe's servers. It stays off until you set a key, and [rerank] enabled = false turns it off completely. The README adds that proxy embeddings (sending text to an outside service to turn it into search vectors) and a WAL tap (a feed of every write to the index) can also send text off the machine if you configure them.

Sharing goes through Cloudflare by default. xerj share --tunnel uses a Cloudflare quick tunnel, which the security model says means searches and documents pass through Cloudflare in a readable form. Use your own hostname and certificate if that matters to you.

Where it fits

Most agent tools promise savings everywhere. xerj's README says where savings happen and where they don't, which is rarer and more useful.

Grep has real advantages here. It's already installed, it never needs re-indexing, and it can't leak anything because it doesn't listen on a port. An index has to earn its place against that.

If your agent mostly works on popular frameworks, keep using grep and don't add a moving part. If it spends its days in code no model has ever seen, give it a real index, keep the login on, and measure one task before and after. The numbers will tell you within an afternoon whether it earned its place.

Sources: xerj-org/xerj README · xerj security model · xerj releases · Trendshift daily board, read about 15:12 ET October 17, 2026 (live board; ranks move through the day). README and security model read from the main branch on October 17, 2026; latest software release v1.0.0-rc.96.