CTX

ctx

Codebase intelligence and context engine for AI coding agents.

Documentation: https://halloffame12.github.io/CTX · docs overview

Table of contents

• Why does it exist?
• Install ctx
• Quick start
• CLI reference
• JSON mode
• MCP server
• Supported languages
• Security
• Privacy
• Configuration
• Architecture
• Development
• Roadmap
• License

---

ctx builds a queryable code graph for a project — files, symbols, signatures and imports — and turns it into compact, relevance-ranked context for AI tools and for humans. It speaks MCP over stdio, so coding agents (Claude, Cursor, Copilot, opencode and any MCP client) can call it directly.

ctx init                      index the project
ctx doctor                    inspect the project + index health
ctx search "create_user"      find symbols
ctx deps src/app.py           what a file imports (and what imports it)
ctx impact create_user        who would break if I change this?
ctx context "add OAuth"       build a ranked context package for a task
ctx changed                   files & symbols changed since HEAD
ctx diff                      semantic diff of symbols between refs
ctx skeleton src/models.py    body-less structural skeleton
ctx watch                     keep the graph in sync while editing
ctx mcp                       run the MCP server over stdio
ctx stats                     show index statistics (files, symbols, dependencies, db size)
ctx version                   print version information

Why does it exist?

AI coding tools get the codebase wrong in predictable ways: they hallucinate file paths, read whole directories into context, miss ripple effects, and waste tokens. ctx addresses that with:

• Incremental code graph — a SQLite database (.ctx/index.db) of files, symbols and dependency edges, updated only where files changed.
• Honest dependency resolution — relative imports, Python dotted modules, Rust use paths and Go imports resolve to real files or are marked external/unresolved. ctx never fabricates internal edges it can't prove.
• Skeletons over dumps — structural context (signatures, types, exports) without bodies, so a model sees the shape of a codebase in a fraction of the tokens.
• Explainable ranked context — keyword + hub + recency + path + git scoring picks the handful of files that matter for a task, and tells you why.
• Impact analysis — cycle-safe BFS over the dependency graph, grouped into direct / indirect / tests / unknown buckets.
• Git-aware change tracking — symbol-level diffs between refs, not just file status.

ctx is local, fast, private and offline: nothing is sent anywhere, no code is executed, no telemetry.

Install ctx

The ctx command is one native, compiled Rust binary — install it through whichever ecosystem you already use:

The installer scripts currently live in the repository (scripts/install.sh, scripts/install.ps1). Until ctx.dev is live you can run them directly:

curl -fsSL https://raw.githubusercontent.com/halloffame12/CTX/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/halloffame12/CTX/main/scripts/install.ps1 | iex

Every method installs the same binary, verified against SHA-256 checksums published with each release. No Rust toolchain is required except for cargo install.

Building from source

Requires Rust 1.85+ (edition 2024). On Windows, a GNU toolchain is recommended for the bundled SQLite build:

scoop install mingw
$env:PATH = "$env:USERPROFILE\scoop\apps\mingw\current\bin;" + $env:PATH

cargo build --release
cargo install --path .        # installs `ctx` to PATH

Version is read from the git tag / Cargo.toml:

ctx --version   # ctx 0.1.6
ctx version     # same

Quick start

cd your-project
ctx init                     # creates .ctx/config.toml + indexes the project
ctx doctor                   # verify the index is current
ctx search "migrate"         # find functions/methods matching
ctx deps src/lib.rs          # what this file imports / what imports it
ctx impact create_user       # change analysis for a symbol or path
ctx context "add pagination" # context package for a task (JSON with --json)

Reasoning about how much context ctx saves

Without ctx, an agent trying to understand a change typically has a human paste a few files:

AI reads:
  12,000 lines of source
  ~100,000 tokens

With ctx:
  AI receives an architecture tree
  relevant symbols + signatures
  dependency / impact map
  skeletons of the files that matter
  target implementations only when relevant

These numbers are illustrative, not benchmarks — run ctx benchmark for real timings on your own repository.

CLI reference

Usage: ctx [OPTIONS] [COMMAND]

Commands:
  init        Create .ctx, write a default config and index the project
  doctor      Inspect the project and report the health of the ctx index
  skeleton    Show a body-less structural skeleton of a source file
  search     Search the graph for symbols or files
  symbol     Details about a symbol: definition, references, dependencies
  deps       Show what a file imports and what imports it
  impact     Analyze impact of changing a symbol or file
  context     Build a relevance-ranked context package for a task
  changed     Show symbols changed in the working tree or between refs
  diff       Semantic diff of symbols between two git refs
  schema      Print the SQLite graph schema
  benchmark  Re-run an index pass and print incremental timing
  watch      Watch the project and keep the graph in sync
  mcp        Run the Model Context Protocol server over stdio
  stats      Show index statistics (files, symbols, dependencies, db size)
  version    Print version information
  help       Print this message or the help of the given subcommand(s)

Options:
  -R, --root <DIR>  Project root (defaults to the nearest directory containing .ctx)
  -j, --json        Emit machine-readable JSON instead of human text
  -q, --quiet       Suppress non-essential output
  -v, --verbose     Enable verbose diagnostics on stderr
      --no-color    Disable ANSI colors
  -h, --help        Print help
  -V, --version     Print version

Per-command help always available:

ctx context --help
ctx impact --help

ctx context — the flagship

ctx context "add Google OAuth authentication"

Scoring is deterministic and explainable. Every suggested file carries the reasons it was selected:

Suggested files:
  src/auth/oauth.ts  (score 0.91, ~180 tokens)
      + exact symbol match `OAuthProvider`
      + path matches keyword `auth`
      + imported by 4 files (hub)
      + modified in working tree
Context budget: 1,842 / 12,000 tokens (estimate)
Omitted: 13 lower-relevance files

If the budget cannot hold the top files, budget_exceeded: true is reported in JSON rather than silently truncating. Working-tree git changes get a small scoring bonus automatically (--no-git disables it).

ctx impact

ctx impact UserService.updateUser --depth 5 --json

Results are grouped:

Direct dependents
Indirect dependents
Tests
UNKNOWN (unresolvable imports in affected files)
Potentially affected: N files / M symbols

Traversal is BFS with per-node cycle protection, bounded by --depth.

ctx doctor

ctx doctor          # human-readable
ctx doctor --json   # machine-readable

Reports git presence, detected languages, framework, package manager, index freshness (files changed on disk since indexing), SQLite health and parser support — with a final Status: READY / STALE / NOT INITIALIZED.

ctx search

ctx search "user"                    # case-insensitive name match
ctx search --kind struct "user"      # filter by symbol kind
ctx search --kind function User      # kind aliases: fn, const, alias
ctx search --files "src/auth"        # search file paths instead
ctx search "user" --limit 20         # default 50, clamped to 1–500

Symbol kinds: function, method, class, interface, type, enum, constant, variable, struct, trait, module, field, constructor, impl — with aliases fn → function, const → constant, alias → type. An invalid kind is rejected (exit 2).

ctx stats / ctx version

ctx stats            # files, symbols, dependency edges, index.db size
ctx stats --json
ctx version          # ctx 0.1.6
ctx version --json   # {"name":"ctx","version":"0.1.6"}

JSON mode

Every query command has deterministic JSON output:

ctx search User --json
ctx symbol UserService --json
ctx deps src/user.ts --json
ctx impact UserService --json
ctx context "add OAuth" --json
ctx changed --json
ctx diff --json
ctx doctor --json
ctx init --json
ctx benchmark --json
ctx schema --json
ctx stats --json
ctx version --json

Invariants: stdout is JSON only — no ANSI codes, no decorations, no progress bars. Diagnostics go to stderr. Errors exit non-zero with a message on stderr.

MCP server

ctx mcp                      # speaks MCP over stdio
ctx -R /path/to/project mcp  # or target a project root explicitly
npx ctxai-cli mcp            # no install required

The server implements JSON-RPC 2.0 over line-delimited stdio:

• initialize, ping, notifications/initialized, tools/list, tools/call
• prompts/list and resources/list are served (empty by default)
• unknown methods → -32601, invalid JSON → -32700, tool errors surface as isError: true results
• stdout carries protocol messages only; all logs go to stderr

Tools exposed:

opencode

Add ctx as an MCP server (see opencode's MCP configuration docs):

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

Claude / Claude Desktop

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

Cursor

Settings → MCP → Add → type command, then:

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

VS Code (Cline / Roo / Continue)

Add an MCP server of type stdio:

command: npx
args: -y ctxai-cli mcp -R /absolute/path/to/project

npx form requires no global install. If ctx is already on your PATH, replace "command": "npx", "args": ["-y", "ctxai-cli", ...] with "command": "ctx", "args": ["mcp", ...].

Supported languages

Partially-broken files degrade gracefully: tree-sitter recovers, valid symbols are still extracted, and the file is reported in parse_errors for the ctx init summary instead of aborting the index.

Security

• Indexing never executes project code or evaluates scripts.
• Paths are validated before use: any user-supplied path that lexically escapes the project root is rejected (path is outside the project root), including through MCP (e.g. ../../../../etc/passwd).
• No telemetry, no network calls, no external AI APIs. The engine is fully local and offline.

Privacy

ctx reads source files, writes a local SQLite index under .ctx/, and spawns git for change queries. Nothing leaves the machine.

Configuration

.ctx/config.toml is written on ctx init:

[index]
exclude = ["node_modules", "target", ".git", ".ctx", "dist", "build", "vendor"]
max_file_size = 2097152
follow_symlinks = false

[context]
max_tokens = 12000
max_files = 25
include_bodies = false

[watch]
enabled = true
debounce_ms = 200

Architecture

src/
  parser/     tree-sitter extractors (Rust, TypeScript/JS, Python, Go) + resolver
  graph/      SQLite code graph: database, symbols, dependencies, impact
  indexing/   scanning (gitignore-aware), hashing, incremental reindex
  context/    skeletons, ranking, context package builder
  git/        diff & changed tracking via the `git` binary
  mcp/        JSON-RPC server, tools, protocol types
  commands/   CLI + MCP command implementations

Development

cargo build
cargo test --lib --test integration --test skeleton   # unit + integration + golden
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check

Repository layout

src/
  parser/     tree-sitter extractors (Rust, TypeScript/JS, Python, Go) + resolver
  graph/      SQLite code graph: database, symbols, dependencies, impact
  indexing/   scanning (gitignore-aware), hashing, incremental reindex
  context/    skeletons, ranking, context package builder
  git/        diff & changed tracking via the `git` binary
  mcp/        JSON-RPC server, tools, protocol types
  commands/   CLI + MCP command implementations
tests/        integration + skeleton golden tests
packaging/    Homebrew tap, WinGet, Scoop manifests
packages/npm/ ctxai-cli meta package + 6 platform packages
scripts/      release + install tooling
website/      Next.js docs site (static export -> GitHub Pages)

Contributing

See CONTRIBUTING.md (setup, conventions, testing) and AGENTS.md (the invariants every change must preserve). Security issues go to SECURITY.md. All participants are expected to follow our Code of Conduct.

GitHub Actions CI runs fmt, clippy (-D warnings, all targets/features), tests and release builds on Linux / macOS / Windows. The release workflow publishes prebuilt binaries (6 targets) with a checksums.txt for each tag, and the npm workflow publishes the ctxai-cli meta package + 6 platform packages with provenance. package-validation.yml keeps all packaging in sync with Cargo.toml. See RELEASE.md for the full release checklist.

Packaging lives in packaging/ (Homebrew tap, Winget, Scoop) and packages/ (npm). Release tooling is in scripts/ (build-release.sh, verify-release.sh, generate-checksums.sh, install.sh, install.ps1, update-homebrew.sh, update-package-manifests.sh).

Note: cargo test --bin ctx may be blocked by Windows Application Control policy on some machines (os error 4551); the library, integration and golden suites above cover the behavior.

Roadmap

• Serverside of ctx doctor: expose diagnostics via MCP.
• Column/method-level references and more static symbol-reference resolution.
• Config-file reading for Node/TypeScript path aliases (tsconfig paths).
• Cargo / Go workspace awareness for module-boundary imports.
• ctx context incremental "focus files" (files you've asked the agent to touch) to steer ranking.

License

MIT — see LICENSE.