ctxq

Ask the index, get the line. Your docs, live inventories and code, indexed for your AI agent — one binary. It stops digging through folders: it asks, and gets back small, sourced passages over MCP, a resident daemon or the CLI.

• No lost context: the few passages it needs, with their source, instead of whole files or guessed paths.
• Always-current docs: the daemon re-syncs docs every 60s and inventories every 5 min; status tells the agent how fresh the index is.

• Relevant: a global BM25 with identifier-aware weighting, plus dense cosine when you plug a real embedder. Offline, BM25 leads (the built-in hash is a weak rerank, not a neural model). Exact identifiers — a port, a container, a domain — hit either way.
• Local first: the index is a single SQLite file. Works offline with the built-in embedder; plug Ollama or any OpenAI-compatible server for a real model. Vectors can live in Qdrant, and other bases can be federated.
• Agent oriented: stable JSON, bounded outputs, structured inventories, workspace maps, annotations that agents leave for each other, and a status they can trust.
• Safe by default: files carrying secrets (keys, tokens) are quarantined before indexing — never chunked, never embedded, never served.

v3 is a ground-up rewrite: a retrieval core plus a code graph (symbols, callers, change impact, doc ↔ code links — docs/v3/CODEGRAPH.md).

How it indexes

• Documents — Word, PowerPoint (with notes), Excel and PDF are converted to markdown in-process, then cut by H2/H3 headings; each chunk keeps its breadcrumb. Tables and inventories are indexed one row per chunk. Sync is incremental (hash + mtime).
• Code — a generic lexer, tuned per language, feeds a scope tree and per-language declaration recognizers: symbols, calls resolved through imports, doc comments, doc ↔ code links. Rust, TS/JS, Python, Go, Java, Kotlin, C#.
• Ranking — dense cosine + a global BM25, fused by score: cosine + α · bm25 / bm25_max. Identifier-like queries get a higher α. With the built-in hash embedder, α is raised so BM25 leads.

Measured

A 100-question golden set (exact-identifier and natural-language questions from a real private workspace, kept out of the repo) gates every change.

Configuration	MRR	hit@1	hit@5	missed
Hybrid, qwen3-embedding 0.6b, tuned prompt template	0.795 [0.739–0.848]	71 %	92 %	8
Same, generic prompt template	0.754	67 %	88 %	12
Built-in embedder, fully offline (128-d)	≈ 0.51

Hybrid score fusion beat reciprocal rank fusion on that set. Details and history: docs/ROADMAP.md.

Install

One binary, no runtime dependency. Source and releases live at github.com/kerbart/ctxq. The one-liner downloads a SHA-256-verified archive from GitHub Releases (ctxq.dev mirrors them), installs it to ~/.local/bin, and puts ctxq on this shell's PATH. Linux x86_64 is musl-static (Alpine and glibc distros). Linux arm64 and macOS ship from the same command.

curl -fsSL https://ctxq.dev/install.sh | sh && . "$HOME/.ctxq/env"
# same installer: https://raw.githubusercontent.com/kerbart/ctxq/main/install.sh

Then, from a project:

ctxq setup
ctxq search "how do I deploy the api?"

Windows: use WSL. CTXQ_BINDIR changes the destination. Project page: https://ctxq.dev.

From source:

cargo install --git https://github.com/kerbart/ctxq.git --locked
# or: cargo build --release            # target/release/ctxq
# optional embedded ONNX model:  cargo build --release --features onnx-embeddings

Cutting a release: bump version in Cargo.toml, commit, then scripts/release.sh vX.Y.Z (tags and pushes; .github/workflows/release.yml does the rest). ci.yml runs cargo test --release on every push.

Quick start

cd my-workspace
ctxq setup                      # 1. index + register ctxq in your agents
ctxq search "how do I deploy the api?"   # 2. ask it yourself

That is all. Your CLIs (Claude Code, Copilot, Codex, Grok, Gemini) and any editor already configured in the repo now list ctxq among their tools — restart them once. ctxq setup --interactive asks two questions, one line each: the embedding provider, then which CLIs get the server. ctxq setup --embed ollama writes that provider into ctxq.toml before indexing (qwen3-embedding:0.6b on http://localhost:11434). An empty answer keeps the current one. --embeddings still overrides a single run and does not save. You never start the MCP server yourself: the CLI launches ctxq mcp in the background and talks to it over stdin/stdout.

Where the index lives

One index per workspace root (the directory you ran ctxq setup in). It sits outside the tree, at ~/.cache/ctxq/<name>-<hash>/docs.db (or <root>/.ctxq/ if you passed --in-repo). ctxq doctor prints the path.

ctxq setup --force-home indexes all of $HOME. That is a different index from a project inside it:

ctxq setup --force-home          # index A: ~/.cache/ctxq/<you>-…/docs.db
cd ~/engie && ctxq setup         # index B: ~/.cache/ctxq/engie-…/docs.db

Two indexes. They do not merge. Searching from ~/engie uses B; searching from $HOME uses A (which also contains the engie files as a subset). Markdown, office, PDF and code are indexed; .git, archives, secrets and gitignored files are skipped.

This is the beginning of the README. Read the rest at the original. Read the full README ↗