FAQ & limitations

Does ctx send my code anywhere?

No. The index lives in .ctx/ inside your repository. ctx opens no network connections, sends no telemetry, and never executes project code. The MCP server runs as a child process over stdio — nothing leaves the machine.

Which languages are supported?

TypeScript, JavaScript, Python, Rust, and Go. Each is parsed with a tree-sitter grammar, and dependency resolution is language-aware. Any other file type is skipped by the scanner.

Does it use embeddings or an LLM?

No. The graph is built with static analysis, and ranking is a deterministic scoring function over names and paths. There are no API calls, no models, no keys — which is also why the results are reproducible.

How is this different from a grep or ripgrep wrapper?

grep finds lines; ctx knows structure. It knows that create_user is a function defined in one file and called from others, which files import which, and what a change would ripple into. Skeleton output gives an agent signatures and exports without bodies, and impact analysis walks real dependency edges instead of matching text.

Why a code graph instead of an embedding index?

Embeddings answer "what is this about?" — fuzzy semantic similarity. ctx answers "where does this live, what calls it, what would break?" which are exact questions with exact answers. For agents working on a codebase, exactness matters more than similarity. The trade-off is that ctx cannot find semantically similar code that shares no names.

Can it index a monorepo?

ctx indexes whatever directory you point it at, including the root of a monorepo. Use -R DIR to point any command at a specific project root.

Does it work with my editor / agent?

If your tool speaks MCP over stdio, it works. Claude Desktop, Cursor, opencode, VS Code (Cline, Roo), and most other MCP clients are covered in the MCP guide.

What does the index cost at runtime?

The binary is a single static-ish Rust executable with no runtime dependencies (Windows builds link the C runtime statically). As a concrete example, indexing this project's own repository (≈ 200 source files, ≈ 1,700 symbols) takes about a second; a re-index of an unchanged tree is typically in the tens of milliseconds. Your mileage depends on repository size and hardware.

Can I use ctx in CI?

Yes. Every command supports --json, and ctx doctor exits non-zero on an unhealthy index — so ctx diff, ctx impact, and ctx doctor can feed checks, code review, or changelog generation.

Honest limitations

  • Five languages. TypeScript, JavaScript, Python, Rust, Go. Everything else is invisible.
  • Name-based, not semantic. Search and context ranking match words; they cannot match concepts.
  • No type checking. ctx is not a language server. It does not resolve types or verify that code compiles.
  • Context following is bounded. ctx context follows direct dependency and dependent edges from matching files and caps dependents of hub files. Code reachable only through longer chains may be omitted — this is by design, to keep the package small, not a guarantee of completeness.
  • Unresolved imports are flagged, not guessed. Dynamic or exotic import patterns may end up in the unknown bucket.
  • The index is a snapshot. It only knows what was on disk at the last ctx init or what ctx watch has seen.
  • MCP runs on a spawn, not a daemon. There is no long running service and no shared cache between clients beyond the SQLite file.