🧭 Decision Guide
Why trending now: Cannot be determined from the provided materials
Try it if you
-
You want Claude Code or Cursor to search the project and reference repositories through MCPThe 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 schemaThe “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 librariesThe “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 resultThe 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 --insecureThe 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 sizeThe 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 floodsThe 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 serversThe “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 authThe README security warning and docs/SECURITY_MODEL.md
-
Use search_after for large result sets instead of relying on scroll beyond its snapshot windowThe README section “Elasticsearch compatibility”
-
Before enabling rerank, confirm the TypeSafe data transfer and read docs/RERANK.mdThe README section “Score results with Jev”
-
Use Jev scores for ranking, not exact percentages; the README says they are poorly calibratedThe README section “Score results with Jev”
Alternatives
-
Elasticsearch:Better when you need Elasticsearch internals or cannot accept XERJ's bounded-snapshot scroll semanticsThe 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 searchThe 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?
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_searchsends 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 = falsedisables it explicitly. - XERJ also provides local
/v1/systemoneand/_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
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?
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 initwires XERJ into Claude Code and Cursor;autoindexcan index code, documents, logs, and PDFs.xerj searchreturns ranked passages with file names and line numbers, whilexerj deflocates 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
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?
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
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?
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 searchreturns ranked passages with file and line references, whilexerj defreturns 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
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?
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 throughhttp://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
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?
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_afterfor 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
✨ 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