local first · agent first · one binary
ask the index, get the line
No more grep loops eating your context. One MCP call, one sourced passage.
Your agent shouldn't dig through folders. ctxq indexes your docs, live inventories and code for it and serves back sourced passages. One binary. Local first.
$ curl -fsSL https://ctxq.dev/install.sh | sh && . "$HOME/.ctxq/env"
Linux x86_64 static musl · SHA-256 verified · no root · ctxq is on your PATH when the line returns
What it indexes
One SQLite file next to your project. Everything runs on your machine.
Markdown, Word, PowerPoint with speaker notes, Excel and PDF. Converted in-process, cut by heading.
Docker, systemd, listening ports, projects, scripts. One row per chunk: “which port?” gets the row.
Rust, TS/JS, Python, Go, Java, Kotlin, C#. Symbols, callers, callees, impact of a diff.
BM25 is always on. Plug Ollama or any OpenAI-compatible server for hybrid search.
A file holding a key is quarantined: never indexed, never served.
Every passage comes back with its file and line range.
Agent ready
Claude Code, Codex, Copilot CLI. It installs ctxq, indexes the project and registers the MCP server.
Set up ctxq (https://ctxq.dev) for this project. Follow these steps exactly; do not invent flags or URLs. Rules: no sudo, do not edit project files yourself, stop and quote the exact error if a step fails. 1. If an MCP server named "ctxq" is already available, call its status tool, report the result, and stop. 2. If you are Codex: your sandbox blocks the ctxq binary, so do not run it. Ask me to run this in a normal terminal from this project's root, then to restart Codex: curl -fsSL https://ctxq.dev/install.sh | sh && . "$HOME/.ctxq/env" && ctxq setup 3. Otherwise, if ctxq is not on PATH, install it (checksum-verified, no root): curl -fsSL https://ctxq.dev/install.sh | sh 4. From this project's root (never from $HOME), run: . "$HOME/.ctxq/env" && ctxq setup It indexes the project, registers the "ctxq" MCP server in every agent CLI it finds, and adds AGENTS.md, CLAUDE.md, .mcp.json and .codex/ (expected). Do not start "ctxq mcp" yourself. 5. Run: . "$HOME/.ctxq/env" && ctxq status Report the indexed counts and any quarantined files, then tell me to restart this agent and approve the ctxq server if asked.
Codex's sandbox blocks the binary: it hands you the one line to run, then you restart it.
Agent surface
search | Ranked passages with source lines |
inventory | The exact row: port, container, domain |
context | Docs and code together, within a token budget |
map | One line per document |
annotate | Notes for the next agent |
status | Freshness, quarantined files |
code_symbol | Signature, doc, body |
code_callers · code_callees | Who calls it, what it calls |
code_path | Shortest call chain |
code_impact | Diff → callers → docs |
MRR 0.795 · 71 % hit@1 · 92 % hit@5 on a 100-question private set (hybrid, qwen3-embedding 0.6b). Method, configuration and everything else: README.
ctxq