Documentation

ctx is a command-line tool and MCP server that answers one kind of question well: which files does this task actually need? It builds a local index of your repository — files, symbols, and the dependency edges between them — and lets you (or an AI agent) query it over stdio.

What it is

  • A deterministic, offline code graph. No embeddings, no API calls, no LLM in the loop — the same repository and the same query give the same answer.
  • An incremental indexer. Only changed files are re-parsed on subsequent runs, so re-indexing a repo typically takes tens of milliseconds.
  • A reference tool for agents: where does this symbol live, what imports what, what would break if I changed this, and which files does this task need.
  • An MCP server over stdio that exposes the same capabilities to Claude Desktop, Cursor, opencode, VS Code, and any other MCP client.

What it is not

  • Not semantic search. ctx matches names and paths; it has no notion of what code means. A task like "add Google OAuth" is scored against symbol and file names, not code semantics.
  • Not a full language server. It does not resolve types, follow macros, or understand generics deeply. It extracts definitions, references, and import edges.
  • Not a replacement for grep for one-off searches. If you just need a string anywhere in a tree, grep / rg is the right tool.
  • Not guaranteed to resolve every import. Unresolved imports are recorded as external/unknown edges rather than guessed.

Quick start

Install via npm (no Rust toolchain needed):

npm install -g ctxai-cli
ctx --version

Or build from source (requires Rust 1.85+):

git clone https://github.com/halloffame12/CTX.git
cd CTX && cargo build --release
./target/release/ctx --version

Then point it at a repository:

cd /path/to/your/project
ctx init
ctx doctor
ctx search "rate limit"

The core loop

CommandWhat it does
ctx initIndex the current directory into .ctx/. Incremental, so later runs are fast.
ctx doctorVerify the index is healthy and current.
ctx context "…"Build a relevance-ranked context package for a task description.
ctx mcpRun the MCP server so an AI agent can query the graph.
CautionThe index is a snapshot. Run ctx init (or keep ctx watch running) after adding, renaming, or deleting files so searches and agents see the current state.
Only TypeScript/JavaScript, Python, Rust, and Go are parsed. All other files are skipped by the scanner — see How it works and the FAQ for details.

Next steps