ctx-search / zxn

zxn is a local Rust code-search CLI and MCP server for AI coding agents.

The implementation target is a persistent, mmap-backed trigram index with SQLite metadata, exact/regex verification, compact snippets, and deterministic agent-facing output.

Current MVP

• zxn index <repo> scans a repo with gitignore-aware walking and writes a persistent cache under the user cache directory.
• zxn search <query> uses a document-level trigram index for selective exact searches and verifies candidate files before returning snippets.
• zxn search --regex <pattern> extracts conservative literals, uses the index when possible, and falls back to scanning when the regex is unindexable.
• zxn find <query> performs lightweight fuzzy path search from SQLite metadata.
• zxn status, zxn rescan, zxn serve --mcp, and zxn bench are available.

Design

The hot content-search path does not use SQLite FTS, Tantivy, or LMDB. SQLite is used for metadata. Content search uses:

trigram hash -> lookup entry -> postings offset -> delta-decoded file IDs

Final results are always verified by reading candidate files, so the index may produce candidate-stage false positives but should not produce final false positives.

Quick Start

cargo run -p ctx-cli --bin zxn -- index .
cargo run -p ctx-cli --bin zxn -- search "SomeLiteral" .
cargo run -p ctx-cli --bin zxn -- search --regex "class .*Controller" .
cargo run -p ctx-cli --bin zxn -- find "user controller" .

Install the CLI as zxn:

cargo install --path crates/ctx-cli --force

Cache

By default, indexes are stored under:

~/.cache/ctx-search/repos/<stable-repo-id>/

Use --cache-dir to override this.