halloffame12/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.
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:
| Method | Command |
| --- | --- |
| **macOS / Linux** (Homebrew) | brew tap halloffame12/CTX && brew install ctx |
| **Windows** (Scoop) | scoop bucket add ctx https://github.com/halloffame12/scoop-ctx && scoop install ctx |
| **Windows** (winget) | winget install halloffame12.CTX |
| **Node.js** (npm) | npm install -g ctxai-cli |
| **Run without installing** | npx ctxai-cli --version |
| **Direct** | curl -fsSL https://ctx.dev/install.sh | sh (Unix) or irm https://ctx.dev/install.ps1 | iex (Windows) — or grab a binary from GitHub Releases |
> The installer scripts currently live in the repository (scripts/install.sh,
> scripts/install.ps1). Until ctx.dev is live you can run them directly:
>
>
>
>
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:
Version is read from the git tag / Cargo.toml:
Quick start
Reasoning about how much context ctx saves
Without ctx, an agent trying to understand a change typically has a human
paste a few files:
These numbers are **illustrative**, not benchmarks — run ctx benchmark for
real timings on your own repository.
CLI reference
Per-command help always available:
ctx context — the flagship
Scoring is deterministic and explainable. Every suggested file carries the
reasons it was selected:
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
Results are grouped:
Traversal is BFS with per-node cycle protection, bounded by --depth.