Codebase context for AI coding agents

ctx indexes a repository into a local, deterministic code graph and answers the questions agents actually ask: where does this symbol live, what would break if I change it, and which files does this task need?

Read the docs View on GitHub

# 1,204 files indexed in ~1 second. Re-index: 34 ms.

ctx — zsh

$ ctx context "add Google OAuth"

Indexed 1,204 files · 8,391 symbols · 34 ms

Suggested files (4 of 7 within budget):

src/auth/oauth.ts score 0.91 path matches `auth`

src/models/user.ts score 0.83 imported by 12 files

src/api/routes.ts score 0.77 defines signInWithOAuth

src/db/session.ts score 0.61 modified this branch

Omitted 3 files below relevance threshold.

Context budget used: 1,842 / 8,000 tokens (estimate)

Install

npm — no Rust toolchain needed

npm install -g ctxai-cli
ctx --version

Or via cargo

cargo — from source

cargo install ctxai-cli --locked
ctx --version

Agents guess. ctx doesn't.

Coding agents fail at codebase navigation in predictable ways. They hallucinate file paths, dump entire directories into context, miss ripple effects, and burn the token window on noise.

ctx fixes that at the source. Every path it returns comes from a real indexed graph, so there is nothing to hallucinate. Skeletons carry structure without bodies, impact analysis runs a real traversal of the dependency graph, and each ranked file explains why it was selected.

What it does

Incremental code graph

A SQLite graph of files, symbols, and dependency edges. Only changed files re-index — content-hash based, transactional.

Symbol & file search

Deterministic, rank-ordered search. Substring, prefix, and kind-aware matching with no embeddings and no API calls.

Honest dependency resolution

Relative imports, Python dotted modules, Rust use paths, and Go imports resolve to real files. Anything unresolved is flagged external — never guessed.

Impact analysis

Cycle-safe breadth-first search over the inverted graph, grouped into direct, indirect, test-file, and unknown buckets.

Skeletons, not dumps

Structural context — signatures, types, exports — without bodies. An agent sees the shape of a codebase in a fraction of the tokens.

Explainable ranking

Keyword, hub, recency, path, and git scoring pick the files that matter. Every selection tells you why it was chosen.

Git-aware diffs

Symbol-level diffs between refs — which definitions were added, removed, or modified — not just file status.

Filesystem watching

Debounced incremental re-indexing on file events. The graph stays in sync while you edit.

MCP over stdio

A Model Context Protocol server for Claude, Cursor, opencode, and any MCP client. No daemon, no open port, no data leaving the machine.

Supported languages

Parsed with tree-sitter, not regex.

TypeScript / JavaScript

functions, methods, classes, interfaces, enums, types, constants, fields

import / require / dynamic import() · ./ ../ @/ aliases · index files

Python

functions, methods, classes, constants

dotted, relative & from-import resolution

Rust

fns, methods, structs, traits, impls, enums, constants, modules

use / crate:: / super:: / self:: / mod probing

Go

functions, methods, structs, interfaces

import paths, module-relative resolution

Commands

One tool, every question.

ctx context

$ ctx context "add Google OAuth"
Suggested files:
  src/auth/oauth.ts   (score 0.91)
      + path matches keyword `auth`
      + imported by 4 files (hub)
      + modified in working tree
Context budget: 1,842 / 8,000 tokens

ctx impact

$ ctx impact UserService.updateUser --depth 5
Direct dependents    2 files, 4 symbols
Indirect dependents  1 file,  2 symbols
Tests                1 file
UNKNOWN              1 unresolved import

ctx skeleton

$ ctx skeleton src/models.py
def create_user(name: str, **kwargs) -> User
  ...
def find_by_email(email: str) -> User | None
  ...
class User(BaseModel)
  fields: id, email, name, created_at

ctx diff

$ ctx diff HEAD~3 HEAD
ADDED    UserService.updatePhoto  src/user/service.rs
REMOVED  create_avatar           src/user/avatar.rs
MODIFIED UserService.updateName  src/user/service.rs

Full command reference →

Plug into any MCP client

ctx ships a Model Context Protocol server over stdio. Wire it into Claude Desktop, Cursor, opencode, VS Code, or anything that speaks MCP — no daemon, no port, no source leaving your machine.

The server exposes ten tools: ctx_project, ctx_search, ctx_skeleton, ctx_symbol, ctx_dependencies, ctx_dependents, ctx_impact, ctx_context, ctx_changed, and ctx_diff.

opencode / Claude Desktop

{
  "mcpServers": {
    "ctx": {
      "command": "ctx",
      "args": ["mcp", "-R", "/path/to/project"]
    }
  }
}

without a global install

{
  "mcpServers": {
    "ctx": {
      "command": "npx",
      "args": ["-y", "ctxai-cli", "mcp", "-R", "/path/to/project"]
    }
  }
}

Try it on your own repository

get started

ctx init
ctx doctor        # verify the index is healthy
ctx context "what does the payment module do?"
ctx mcp           # expose the code graph to your agent

Documentation Download binaries