xerj: Auto-index code and documents so AI searches instead of reading files
An AI indexer for coding agents to search local code and documents, using fewer tokens than grep while speaking Elasticsearch.
GitHub xerj-org/xerj Updated 2026-10-16 Branch main Stars 5.7K Forks 308
Rust AI search Elasticsearch API Local development

🧭 Decision Guide

Try it if you

  • You want Claude Code or Cursor to search the project and reference repositories through MCP
    The README says xerj init wires XERJ into Claude Code/Cursor with MCP and a skill
  • Your corpus contains code, PDFs, logs, SQLite, or CSV and you do not want to write a schema
    The “Feed it any folder” section lists these formats and says no schema or pipeline is required
  • You already use Elasticsearch clients, Kibana, or official client libraries
    The “Elasticsearch compatibility” section says these tools connect directly to localhost:9200
  • You care about token costs in reference coding and accept the README's 2.7x study result
    The opening README study reports 2.7x fewer output tokens at the same 16/16 solve rate

Skip it if you

  • You need TLS, API-key authentication, or a multi-user production boundary but can only use --insecure
    The README states that --insecure disables TLS and API-key auth and makes every reachable caller a superuser
  • Your export flow depends on Elasticsearch scroll for exact result totals of arbitrary size
    The README says scroll is a bounded snapshot that returns 400 beyond its window and recommends search_after
  • Your workload depends on low read p99 latency during high-rate write floods
    The benchmark section says read p99 under high-rate writes accounts for all four losses
  • You cannot accept Jev rerank sending search-result text to TypeSafe servers
    The “Score results with Jev” section explicitly says enabled rerank sends result text

Requirements

  • The installer provides prebuilt static binaries for x86-64 and arm64 on Linux, macOS, and Windows
  • After starting the service, wait for http://localhost:9200 to respond before running xerj autoindex
  • Hosts without runtime internet access need the air-gapped deployment recipe; the default lexical embedder is offline, while neural mode needs three model files staged locally
  • --insecure is intended for a single-user development machine; a fresh node binds to 127.0.0.1 by default

First step (verbatim from README)

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

Watch out

  • Do not expose --insecure beyond localhost; it disables both TLS and API-key auth
    The README security warning and docs/SECURITY_MODEL.md
  • Use search_after for large result sets instead of relying on scroll beyond its snapshot window
    The README section “Elasticsearch compatibility”
  • Before enabling rerank, confirm the TypeSafe data transfer and read docs/RERANK.md
    The README section “Score results with Jev”
  • Use Jev scores for ranking, not exact percentages; the README says they are poorly calibrated
    The README section “Score results with Jev”

Alternatives

  • Elasticsearch:Better when you need Elasticsearch internals or cannot accept XERJ's bounded-snapshot scroll semantics
    The README sections “Elasticsearch compatibility” and “Benchmarks”
  • grep/sed:Better when you only need to inspect a small amount of text without XERJ indexing, RAG, or file-line search
    The README opening and “Why it exists” section

Not stated in the README

  • The README does not specify resource limits for individual files, total corpus size, or continuous incremental indexing
  • The README does not enumerate the exact API differences in the remaining 3 failures out of 1369 compatibility cases
  • The README does not state the CPU, memory, or disk requirements for the 593-dataset example
  • The README does not provide post-install service management, background execution, or security-configuration details for Windows
  • The README does not specify the names, sizes, or acquisition method of the three model files required by neural mode
  • The README does not describe upgrade, index migration, or rollback procedures between releases

💡 Deep Analysis

6
No I retrieve sensitive code and logs in a local RAG system and want Jev reranking to improve nDCG, but cannot normally send candidate text to TypeSafe's servers. Should I enable this integration?
For: A local RAG developer handling sensitive code and logs who also wants Jev to improve retrieval ranking

No, not under the stated data constraint, because Jev reranking sends candidate result text to TypeSafe’s servers.

  • The README says that adding "rerank": {} to _search sends the top results to Jev.
  • On the public FiQA test, nDCG@10 increased from 0.24 to 0.36 at a total cost of about $0.64 for 648 searches. This indicates a possible ranking benefit, not an offline benefit.
  • The feature remains off until a key is configured, and [rerank] enabled = false disables it explicitly.
  • XERJ also provides local /v1/systemone and /_decide, but these require previously labeled examples and are not a drop-in equivalent for general Jev reranking.

Sensitive data should therefore keep Jev disabled; enabling it only makes sense when outbound data is permitted and its cost and latency are acceptable.

  • README section “Score results with Jev”: “Add `"rerank": {}` to a `_search` and XERJ sends the top results to Jev”
  • README: FiQA nDCG@10 increased from `0.24 to 0.36`, costing about `$0.64` for 648 searches
  • README: “`[rerank] enabled = false` forbids it completely”
  • README: local `POST /v1/systemone` and `POST /_decide` require labelled examples
Not stated in the README:The README does not state retention, region, or data-processing terms for Jev requests.;The README does not provide Jev's added latency or fallback behavior on request failure.;The README does not report local systemone performance on code and log corpora.
Yes I use Claude Code or Cursor for reference coding and want the agent to index similar open-source repositories before searching implementation patterns instead of reading files with grep and sed. Is XERJ suitable for my workflow?
For: A software engineer using Claude Code or Cursor who needs an agent to search reference open-source repositories while reducing context usage

Yes, because the README identifies reference coding and coding-agent integration as primary use cases and provides a one-command MCP and skill setup.

  • xerj init wires XERJ into Claude Code and Cursor; autoindex can index code, documents, logs, and PDFs.
  • xerj search returns ranked passages with file names and line numbers, while xerj def locates definitions by symbol, reducing the need to open complete files.
  • The README reports a controlled case where agent output tokens fell 2.7x at the same 16/16 solve rate; this is a case-study result, not a universal guarantee.

If the agent must write, delete, or rebuild indexes, the README does not specify fine-grained MCP permissions, so that security boundary remains to be verified.

  • README: “Reference coding is its main use case”
  • README command: `xerj init # wire XERJ into Claude Code/Cursor (MCP + skill), one command`
  • README commands: `xerj search` and `xerj def`
  • README: “cut a coding agent's output tokens by 2.7x at the same 16/16 solve rate”
xerj init                                        # wire XERJ into Claude Code/Cursor (MCP + skill), one command
Not stated in the README:The README does not say whether MCP permissions can be restricted separately for Claude Code and Cursor.;The README does not describe automatic incremental updates for frequently changing reference repositories.
It depends I need to index internal code and security-audit material on an air-gapped Linux arm64 machine without runtime Internet access, and cannot send the content to a cloud service. Are XERJ's offline capabilities sufficient?
For: An engineer handling internal code and security-audit material in an air-gapped Linux or arm64 environment without runtime Internet access

It depends: local deployment and the default lexical embedder fit an offline constraint, but neural semantic retrieval requires model files to be staged in advance.

  • The README provides an air-gapped deployment recipe and says prebuilt binaries cover Linux, macOS, and Windows on x86-64 and arm64.
  • The default lexical embedder runs offline, so basic indexing, full-text search, and some semantic functionality do not require an external service.
  • Neural mode requires three model files locally before the first semantic operation; the README does not state their download source, integrity checks, or size.
  • Jev reranking sends result text to TypeSafe’s servers, which conflicts with a no-egress policy for internal code and audit material unless it remains disabled.

Basic offline search is therefore feasible, while neural-mode preparation and Jev’s offline deployment details remain blockers.

  • README section “Install by hand”: “For a host with no runtime internet access, follow the air-gapped deployment recipe”
  • README: “Prebuilt for Linux, macOS and Windows on x86-64 and arm64”
  • README: “The default lexical embedder is offline; neural mode needs the three model files staged locally”
  • README section “Score results with Jev”: “This sends the text of those results to TypeSafe's servers”
curl -fsSL https://xerj.org/get | sh
Not stated in the README:The README does not provide the names, sizes, checksums, or offline acquisition process for the three neural model files.;The README does not say whether every code parser and PDF parser dependency works in an air-gapped deployment.;The README does not describe model-update or vulnerability-fix procedures for offline environments.
Yes I am auditing about 1,492 PHP files and want an agent to locate security-relevant code with less context while preserving file and line references. Is XERJ more suitable than reading files one by one?
For: A security engineer auditing about 1,492 PHP files who requires the agent to return file and line references

Yes for narrowing the audit search space, but not as the sole mechanism for vulnerability confirmation or complete program-semantic analysis.

  • The README’s WordPress core security-audit case covered 1,492 PHP files using roughly 26,000 tokens, described as about 0.5% of the tokens needed to load the whole tree.
  • xerj search returns ranked passages with file and line references, while xerj def returns definition file, line, and signature information.
  • XERJ’s code indexing preserves symbols and line numbers rather than treating code only as flat text, which is useful for locating definitions and related passages.
  • The project analysis notes that cross-file calls, generated macros, dynamic loading, build conditions, and runtime configuration may not be explained accurately by indexing alone.

It is suitable as the audit retrieval layer, but the final finding should not rely only on retrieved snippets.

  • README section “Why it exists”: the WordPress core AI security audit covered `1,492 PHP files` and `roughly 26,000 tokens`
  • README command: `xerj search` returns `ranked passages, file:line`
  • README command: `xerj def` returns `file:line + signature`
  • Project insights common pitfalls: indexing cannot fully explain cross-file calls, generated macros, dynamic loading, and similar behavior
xerj autoindex ~/my-project
Not stated in the README:The README does not state how PHP versions, framework features, or dynamic-code patterns affect symbol extraction coverage.;The README does not provide recall, false-positive, or vulnerability-type breakdowns for the security audit.;The README does not explain how to connect retrieved results with static analyzers, tests, or vulnerability databases.
Yes I need to build XERJ from source on Linux, macOS, or Windows x86-64/arm64 hosts and want deployment without a JVM or other runtime. Is the build path sufficiently clear?
For: A Rust engineer who wants to build the local search server from source on Linux, macOS, or Windows x86-64/arm64 hosts

Yes: the README provides a stable-Rust requirement, source-build commands, and a deployment model without a JVM.

  • Rust is the project’s main language; source builds require a stable Rust toolchain and explicitly use cargo build --release -p xerj-server.
  • The README describes the artifact as one static binary with no JVM and no dependencies, with prebuilt targets for Linux, macOS, and Windows on x86-64 and arm64.
  • After building, the server can be started with ./target/release/xerj --insecure --data-dir ./data, and the node can then be checked through http://localhost:9200.
  • The Elasticsearch compatibility suite also has a runnable Rust command for post-build API verification.

The README does not explain platform-specific toolchains, cross-compilation setup, package signing, or reproducible-build guarantees, so a complex release pipeline still needs additional validation.

  • Project data: `main_language: Rust`
  • README section “Build from source”: “You need a stable Rust toolchain”
  • README section “Build from source”: `cargo build --release -p xerj-server`
  • README section “Install by hand”: “One static binary, no JVM, no dependencies”, covering Linux/macOS/Windows x86-64 and arm64
  • README section “Build from source”: `cargo run --release -p es-yaml-runner -- --dir tests/es-compat-yaml/yaml`
git clone https://github.com/xerj-org/xerj
Not stated in the README:The README does not specify the linker, SDK, or Rust target required for Windows source builds.;The README does not say whether binaries for Linux, macOS, and Windows are signed or provide supply-chain verification data.;The README does not provide complete cross-compilation or reproducible-build configuration.
It depends I already depend on the official Elasticsearch clients, Kibana, bulk, aggregations, and kNN queries, and want to connect a local codebase to a Rust service without a JVM. Can XERJ serve as a compatible replacement?
For: A developer already using the official Elasticsearch clients, Kibana, and aggregations who wants to index local code and documents without rewriting the search layer

It depends: common Elasticsearch REST workflows are largely portable, but XERJ should not be treated as a complete replacement for Elasticsearch internals.

  • The README lists indices, documents, bulk, search, aggregations, mappings, kNN, scroll, reindex, and _cat, and says Kibana and official clients can connect directly.
  • The conformance suite currently passes 1366 of 1369 cases, so three compatibility gaps remain.
  • Scroll is a bounded upfront snapshot. If the exact total exceeds the snapshot window, XERJ returns 400 instead of silently truncating; the README recommends search_after for large result sets.
  • Its deployment advantage is a single static binary with no JVM, but the README does not promise Elasticsearch execution plans, plugins, or every edge API behavior.

It is a reasonable fit for standard REST-based local search, but not an automatic replacement for systems dependent on full Elasticsearch semantics.

  • README section “Install by hand”: “One static binary, no JVM, no dependencies”
  • README section “Elasticsearch compatibility”: lists bulk, aggregations, mappings, kNN, scroll, reindex, and `_cat`
  • README: “The conformance suite ... currently passes 1366 of 1369 cases”
  • README: “scroll is a bounded up-front snapshot ... Use `search_after` for result sets of any size”
cargo run --release -p es-yaml-runner -- --dir tests/es-compat-yaml/yaml
Not stated in the README:The README does not identify the three failing compatibility cases or their impact.;The README does not specify the supported Kibana versions.;The README does not provide a complete migration, reindexing, and rollback procedure for existing Elasticsearch data.

✨ Highlights

  • autoindex indexes code, PDFs, logs, and SQLite in one command
  • A reference-coding study reports 2.7x fewer output tokens
  • Compatible with Elasticsearch clients, Kibana, and official libraries
  • The latest compatibility suite passes 1366 of 1369 cases
  • --insecure disables TLS and API-key authentication

🔧 Engineering

  • xerj autoindex detects datasets and builds typed indexes automatically
  • xerj search returns ranked passages, filenames, and line numbers
  • tree-sitter preserves symbols and line numbers for code
  • The Elasticsearch REST API supports aggregations, kNN, and scroll

⚠️ Risks

  • With --insecure, any caller reaching the port is a superuser
  • A cleartext bind outside localhost requires explicit permission
  • scroll uses a bounded snapshot and returns 400 beyond its window
  • Read p99 under high-rate writes is the benchmark's recurring loss
  • Jev rerank sends result text to TypeSafe servers

👥 For who?

  • Developers who need Claude Code or Cursor to search code
  • Teams maintaining local corpora of code, documents, logs, and PDFs
  • Users with Elasticsearch clients who want a single static binary
  • Users in isolated environments needing offline default lexical search