How to Use xerj: The Beginner's Guide (Index Your Codebase for Your AI Agent)

CodexFuse Team · 2026-11-03T06:54:30.479Z · 13 min read min read

What is xerj, exactly?

xerj is an open-source, Elasticsearch-compatible code search server you run on your own machine, built for one job: giving an AI coding agent the codebase context it needs without drowning it in tokens. Instead of the agent grepping through thousands of files and opening each one to judge whether it matters, xerj pre-indexes the repository and answers questions like "where is this defined?" with ranked passages that include exact file and line numbers. Learning how to use xerj means installing one static binary, pointing it at your project with an autoindex command, and letting your agent ask it questions through a built-in MCP server.

The project lives at its xerj GitHub repository — github.com/xerj-org/xerj — under the Apache-2.0 license, and it is a RISING one: the repo page showed 18,846 stars on November 3, 2026, with the osrepos directory recording +144 stars in the single day before that check. If you already pair-program with an AI assistant in the terminal, this guide pairs naturally with a Claude Code beginner guide — xerj's own headline case study was measured with real claude -p runs, and Claude Code is one of the agents xerj wires itself into with a single command.

How do you install xerj?

You install xerj with one line, and you get one static binary — no Java runtime, no dependency tree, no Docker required. The README's installer line is:

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

On Windows the equivalent is irm https://xerj.org/get.ps1 | iex. The installer downloads the matching release archive from GitHub, verifies its SHA-256 checksum before installing, and puts the binary in ~/.local/bin. Prebuilt archives cover Linux, macOS, and Windows on x86-64 and arm64. As of November 3, 2026 the binary line is at 1.0.0-rc.100 — pin that version rather than saying "latest," because this project's release candidates were churning fast (rc.95 was the line in mid-October, rc.100 two and a half weeks later).

One safety note, said once and said loudly because the README itself says it this way: the quick-start uses a --insecure flag, and that flag is a trust boundary, not a formality. It turns off TLS and API-key auth, so every caller that can reach the port is a superuser who can read and delete every index, including every /_memory namespace. It is meant for one user on a dev machine — a fresh node binds 127.0.0.1 only, and a cleartext bind on any other interface refuses to start unless you explicitly allow it. With authentication on, xerj mints an admin key at <data-dir>/admin.key on first start, and you pass it with --api-key or the XERJ_API_KEY environment variable. Keep your data directory outside any folder you autoindex — the README warns that ./data is not in the built-in ignore list, so an index of your project would happily index its own index files.

How do you index your codebase for an AI agent?

You point one command at your project and xerj does the rest: it sniffs every file's content (not the file extension) to decide what is code, infers one index per dataset, and parses sources with tree-sitter so the index holds real symbols and line numbers instead of flat text. To index a codebase for an AI agent with xerj, the first-index sequence is five moves:

1. Start a node: xerj --insecure --data-dir ~/xerj-data & (remember the trust boundary from the install section), then wait for http://localhost:9200 to answer.
2. Wire it into your agent: xerj init sets up MCP plus a skill for Claude Code and Cursor in one command.
3. Index your project: xerj autoindex ~/my-project — keep ~/xerj-data outside ~/my-project.
4. Ask your first question: xerj search "how do we rotate the WAL segment" returns ranked passages with file:line references.
5. Jump to a definition: xerj def "euler_to_rotationmatrix" returns the definition's file, line, and signature.

The README shows a real sample run so you know what to expect: "phase A: 593 datasets inferred, 1955 junk/skipped files; phase B: indexing 25329 files with 8 workers; done in 158.1s, 593 datasets, 83103 records live, 790 junk records." Most first indexes land the same way — a quick sniffing phase, a parallel indexing phase, and a summary of how many records are live. Since you will usually be indexing a git repository, the habits from a Git beginner guide transfer directly: one repo, one index, and a clean working tree makes the dataset boundaries obvious.

What do xerj's search, def and gain commands do?

Three commands cover the daily loop, and each answers a different question your agent would otherwise burn tokens figuring out:

xerj gain deserves a callout because it is xerj's honesty feature: instead of marketing math, it reports what the index did for your actual runs, counted from real usage. That makes it the number you should quote when someone asks whether indexing your codebase was worth the five minutes.

How do you wire xerj into your coding agent with MCP?

The xerj MCP server speaks MCP over stdio and proxies to your running node — and here is the rule the README states in bold-adjacent language: xerj mcp does not start a node; step 1 is the prerequisite. Start the node first, then hand your agent this config:

{
  "mcpServers": {
    "xerj": {
      "command": "/home/you/.local/bin/xerj",
      "args": ["mcp"],
      "env": { "XERJ_URL": "http://localhost:9200" }
    }
  }
}

Use the absolute path to the binary — desktop MCP hosts do not inherit your shell's PATH, and a bare xerj in the command field is the most common wiring failure. The project lists 26 supported clients, with five tested end to end: OpenCode, Claude Code, Cline, Kimi Code CLI, and DeepSeek Harness. In the README's tested runs the tool list shows 20 tools (Cline) and 22 tools (Claude Code) — newer than the 13-tool count an October indie review reported, so take the README's numbers. The same MCP surface exposes /_memory/{namespace}, which is xerj's durable agent memory: your agent can stash and retrieve notes across sessions instead of re-deriving them. If your agent pair-programmer is Aider rather than Claude Code, the terminal-native habits still transfer — our Aider beginner guide is the pillar page for this whole agent-devtools cluster, and xerj slots into it as the retrieval layer Aider's repo-map and grep habits were approximating.

Is xerj actually better than grep?

For the codebase-context job, the xerj vs grep debate is really a question about where tokens go — and the vendor's own controlled case study says xerj wins that debate, with boundaries. The honest answer requires the vendor's exact numbers, attributed every time, plus the limits the same README states. The README ran 8 tasks across 4 languages, 16 runs per arm, with real claude -p token counts:

The README's own headlines from that study: 2.7x fewer output tokens than grep and 26x fewer than memory alone at the same solve rate, 2.1x cheaper overall, up to 278x fewer tokens on a single Java task — and field reports of roughly 5x fewer tokens end to end, which the README presents as user testimony rather than a controlled result. One indie deep-dive explains the mechanism: with grep, the token cost lives in the judgment step — grep returns a line, and judging whether that line matters requires opening the whole file. The README's logs record a grep-driven agent peaking at 1.06 million input tokens on a single corpus, which is the failure mode xerj's ranked passages are designed to kill.

Now the boundaries, stated once each as the README states them. The gains are gated by memorisation: xerj wins on private, internal, niche, or post-cutoff code, and is "neutral to harmful" on popular public libraries the model already knows — indexing React's source to teach the model React is pure overhead. And the "40x fewer tokens than grep" line you may see in coverage is third-party framing, not the repo's own controlled result; quote the 2.7x/26x figures when you want the defensible numbers.

Why is xerj compatible with Elasticsearch tools?

xerj implements the Elasticsearch surface your existing tooling already speaks: indices, documents, bulk, search, aggregations, mappings, kNN, scroll, reindex, and _cat. This xerj Elasticsearch compatibility is why an independent review could measure 1,366 of 1,369 Elasticsearch YAML conformance cases passing — and why you can point Kibana-style workflows and ES client libraries at http://localhost:9200 and have most of them just work. One documented gap to know: scroll is a bounded up-front snapshot, so a query that exceeds the window returns a 400 — the README's fix is to use search_after instead. Because the API is plain REST, you can prototype calls before wiring them into an agent; a REST API tester is a handy way to shape a search request and its curl form against your local node before you commit it to a config file.

Eulix vs xerj: which kind of code index do you need?

Eulix is this page's comparison member, and the difference is mechanism, not quality. Eulix is a deterministic local indexing and call-graph engine — it maps exactly how your code connects, the same way every time. xerj is a search-and-retrieval engine with an MCP server — it ranks passages by relevance to a question and hands them to an agent. If your problem is "show me every caller of this function, deterministically," you want the call-graph tool. If your problem is "my agent is burning tokens grepping for context," you want xerj. They are different answers to different questions, which is why Eulix lives on this page as a comparison rather than getting its own rival article.

What are the five beginner mistakes with xerj?

Every one of these comes from the README's own warnings or from independent reviewers' measured results — none of them is hypothetical:

When should you NOT reach for xerj?

Three honest no-goes, all from this run's sources. First, log search: an independent review tried it on their corpus and reported it "did not work for us" — grep was more accurate for logs, so keep grep in your toolbox for that job. Second, memory weight: the same review measured the idle daemon at 8.3 GB on a 154 MB corpus (an August build — treat it as a data point, not a guarantee), and the optional neural embedding mode downloads roughly 90 MB of model files, so this is not a lightweight sidecar on a small VPS. Third, the memorisation boundary from the vs-grep section: on code the model already knows cold, retrieval adds tokens without adding information. xerj earns its keep on the code only you have.

Sources

• github.com/xerj-org/xerj — README (fetched November 3, 2026): install flow, autoindex mechanics, the five-command sequence, the --insecure trust-boundary wording, the controlled claude -p case-study figures, MCP wiring, Elasticsearch API surface, Corpus Hub.
• github.com/xerj-org/xerj/releases (checked November 3, 2026): binary line pinned at 1.0.0-rc.100; releases page topped by Corpus Hub pack pre-releases, 703 releases total.
• andrew.ooo/posts/xerj-review-elasticsearch-compatible-search-for-ai-agents/ (October 16, 2026, independent review): Elasticsearch conformance 1,366 of 1,369 cases, 13-tool MCP count (superseded by the README's 20–22), the broader 1-of-21 vs 21-of-21 harness, the valkey/memcached control, the log-search caveat, the 8.3 GB idle-daemon measurement.
• frontiernow.dev/en/github/xerj/ (editorial review): tree-sitter parsing, the /_memory agent-memory feature.
• osrepos.com/repo/xerj-org-xerj (snapshot November 3, 2026): 18,827 stars, +144 since November 2.
• updownx-studio.blogspot.com/2026/10/xerjai-how-autoindex-reduces-token.html (indie deep-dive): token cost living in the judgment step; the README's 1.06M-input-token grep-driven peak.

Frequently asked questions

Is xerj free?

Yes. xerj is open source under the Apache-2.0 license — one static binary you download and run on your own machine, with no license server, no seat fees, and no hosted tier to subscribe to. The Corpus Hub's signed pre-indexed packs are the project's distribution channel for public datasets, not a paywall.

Does xerj replace grep?

No, and you should keep both. xerj replaces the grep-then-open-every-file loop your agent runs when it needs codebase context; for one-shot searches and for log files — where an independent review found xerj "did not work for us" and grep more accurate — grep remains the right tool.

How much memory does xerj use?

One independent review measured the idle daemon at 8.3 GB on a 154 MB corpus, using an August build — treat that as a single data point from an older release, not a specification. The default lexical embedding mode is offline and light; the optional neural mode downloads roughly 90 MB of model files. Size your machine from your own corpus, and use xerj gain to check the trade-off is paying off.

Can I use xerj with an agent other than Claude Code?

Yes. The project lists 26 supported MCP clients, with five tested end to end: OpenCode, Claude Code, Cline, Kimi Code CLI, and DeepSeek Harness. xerj init does one-command MCP plus skill wiring for Claude Code and Cursor; for other clients, paste the stdio config block from the MCP section with the absolute binary path.

Is my code private when I index it with xerj?

Indexing happens on your own machine — nothing is uploaded to index your repository. Authentication is on by default with an admin key minted at <data-dir>/admin.key; the --insecure flag from the quick-start exists only for a single user on a local dev machine, where the node binds 127.0.0.1 and refuses cleartext binds on other interfaces unless you explicitly allow them.