CTX
This server exposes a local code-intelligence MCP service for a project's indexed code graph, letting agents inspect structure and dependencies without dumping whole files.
ctx_project: get a high-level overview (root, git, file/symbol/dependency counts, languages).ctx_search: find symbols or file paths by name/kind, with limits and file-path search.ctx_skeleton: view a compact, body-less structural outline of a source file.ctx_symbol: get deep detail on a symbol: signature, methods, references, and dependencies.ctx_dependencies/ctx_dependents: see what a file imports, or which files import it.ctx_impact: analyze the blast radius of changing a symbol or file (direct/indirect/tests/unknown).ctx_context: build a relevance-ranked token-budgeted context package for a natural-language task.ctx_changed: list files and symbols changed since a git ref or in the working tree.ctx_diff: get a semantic symbol-level diff between git refs.ctx_stats: check index health (counts and database size).
ctx
Codebase intelligence and context engine for AI coding agents.
Documentation: https://halloffame12.github.io/CTX · docs overview
Table of contents
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 informationRelated MCP server: agentmako
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
usepaths and Go imports resolve to real files or are marked external/unresolved.ctxnever 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) |
|
Windows (Scoop) |
|
Windows (winget) |
|
Node.js (npm) |
|
Run without installing |
|
Direct | `curl -fsSL https://ctx.dev/install.sh |
The installer scripts currently live in the repository (
scripts/install.sh,scripts/install.ps1). Untilctx.devis live you can run them directly:curl -fsSL https://raw.githubusercontent.com/halloffame12/CTX/main/scripts/install.sh | shirm 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:PATHcargo build --release
cargo install --path . # installs `ctx` to PATHVersion is read from the git tag / Cargo.toml:
ctx --version # ctx 0.1.6
ctx version # sameQuick 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 relevantThese 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 versionPer-command help always available:
ctx context --help
ctx impact --helpctx 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 filesIf 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 --jsonResults are grouped:
Direct dependents
Indirect dependents
Tests
UNKNOWN (unresolvable imports in affected files)
Potentially affected: N files / M symbolsTraversal is BFS with per-node cycle protection, bounded by --depth.
ctx doctor
ctx doctor # human-readable
ctx doctor --json # machine-readableReports 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–500Symbol 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 --jsonInvariants: 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 requiredThe server implements JSON-RPC 2.0 over line-delimited stdio:
initialize,ping,notifications/initialized,tools/list,tools/callprompts/listandresources/listare served (empty by default)unknown methods →
-32601, invalid JSON →-32700, tool errors surface asisError: trueresultsstdout carries protocol messages only; all logs go to stderr
Tools exposed:
Tool | Purpose |
| project overview (root, git, counts) |
| symbol / file search (with |
| body-less structural skeleton of a file |
| definition, methods, references, deps of a symbol |
| outgoing / incoming imports |
| change-impact analysis ( |
| ranked context package ( |
| files & symbols changed since a ref |
| semantic diff of symbols between refs (single base resolves to its merge-base with HEAD) |
| index statistics (files, symbols, dependencies, db size) |
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
npxform requires no global install. Ifctxis already on your PATH, replace"command": "npx", "args": ["-y", "ctxai-cli", ...]with"command": "ctx", "args": ["mcp", ...].
Supported languages
Language | Files | Symbols | Dependencies | Skeleton |
TypeScript | ts, tsx, mts, cts | functions, methods, classes, interfaces, enums, constants, fields, modules, type aliases |
| bodies elided, docs kept |
JavaScript | js, jsx, mjs, cjs | same as TS | same as TS | bodies elided |
Python | py, pyi, pyw | functions, methods, classes, constants, module-level vars |
| bodies elided |
Rust | rs | functions, structs, enums, traits, impl blocks, methods, consts |
| impl/fn bodies elided, struct/enum kept |
Go | go | functions, methods, types, interfaces, consts | package | fn/method bodies elided, types kept |
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 = 200Architecture
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 implementationsDevelopment
cargo build
cargo test --lib --test integration --test skeleton # unit + integration + golden
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --checkRepository 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 ctxmay 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 contextincremental "focus files" (files you've asked the agent to touch) to steer ranking.
License
MIT — see LICENSE.
Available Tools
11 toolsctx_changedA
Return files and symbols changed since a git reference as JSON, including working-tree changes by default. Use to focus an agent on what changed in a branch or commit range before reviewing or testing. ref is a git ref (e.g. HEAD~5, main, a SHA); omit it to report uncommitted working-tree changes. Only works in git repositories (returns an error otherwise). For a per-symbol semantic diff between two refs use ctx_diff; for a plain list of changed file paths use this tool.
Inputs: ref.
ctx_contextA
Build a compact, relevance-ranked context package for a coding task and return it as JSON. This is the high-value tool: give it a natural-language task and it returns the most relevant files/symbols/snippets to feed to an LLM, optionally including recent git changes. Use when you need a focused slice of the codebase for a prompt instead of reading many files. task is required and should describe the goal; include_bodies (default false) embeds function bodies; max_tokens (default auto, 128-100000) caps package size.
Inputs: task (required), max_tokens, include_bodies.
ctx_dependenciesA
Return the outbound import edges of a file as JSON: [{target, imported_symbol}] — the project files/modules it imports and, where known, the symbol imported. Use to see what a file depends on before refactoring it. path is project-relative or absolute (traversal rejected). For the reverse direction (who imports this) use ctx_dependents. Requires the project to be indexed.
Inputs: path (required).
ctx_dependentsA
Return the inbound (reverse) dependency edges of a file as JSON: [{source, imported_symbol}] — the project files that import it and, where known, the symbol they import. Use to find every consumer of a file before changing or removing it. path is project-relative or absolute (traversal rejected). For the forward direction (what a file imports) use ctx_dependencies.
Inputs: path (required).
ctx_diffA
Return a semantic symbol diff between two git refs as JSON: the symbols added, modified or removed per file. Compared to ctx_changed, this is a structural (symbol-aware) diff rather than a file list. Provide base and head explicitly, or supply only base (or neither) — when base alone is given it resolves to its merge-base with HEAD so the diff shows only the current branch's changes; head defaults to HEAD. Only works in git repositories.
Inputs: base, head.
ctx_impactA
Analyze the blast radius of changing a symbol or file. Returns an ImpactReport: {target, target_symbol, depth, direct, indirect, tests, unknown} where direct/indirect/test lists are [{path, distance, symbols}]; unknown surfaces imports that could not be statically mapped. Use before modifying code to estimate what else must be checked or updated. Provide exactly one of symbol (a name) or path (a project-relative file); depth controls how many hops of indirect impact to traverse (default 3, 1-20). Requires the project to be indexed; returns an error object if the target is not found.
Inputs: path, depth, symbol.
ctx_projectA
Return the project overview as JSON: {root, git, files, symbols, dependencies, languages}. Use this first to orient a coding agent on a repo: absolute root path, git root, and how large the codebase is (counts of indexed files, symbols and dependency edges, plus the distinct languages present). Requires the project to have been indexed (see ctx_search for symbol lookup). Returns only counts, never file contents. Prefer ctx_stats for detailed index-health numbers (e.g. index.db size) and ctx_search to actually find symbols.
Inputs: no named parameters.
ctx_searchA
Search the project's code graph for symbols or file paths by name and return JSON. Symbol results give {name, parent, kind, path, line, signature}; with files=true results give {path, language, size}. Use to find where a function/class/type is defined before reading it, or to locate files by path fragment. Use ctx_symbol for deep detail on a single exact symbol, and ctx_impact to see what depends on a match. query is a case-insensitive substring/name match. Constrain with kind (function, method, class, struct, trait, enum, interface, type, constant, variable, module, field, constructor, impl) and limit results (default 50, 1-500).
Inputs: query (required), kind, files, limit.
ctx_skeletonA
Return a body-less structural skeleton of one source file as {path, language, skeleton}. The skeleton preserves signatures, types, exports and doc comments but strips function bodies, so it is a compact map of a file's public API and structure. Use before editing a file to understand its shape without reading the whole body. path is project-relative or absolute (must be inside the project; traversal is rejected). Set with_stats=true to also include {stats} (symbol counts). Only paths for supported languages can be resolved (error otherwise); use ctx_search (files=true) to confirm a path first.
Inputs: path (required), with_stats.
ctx_statsA
Return index-health statistics as JSON: counts of indexed files, symbols and dependency edges, plus the size of index.db (the underlying code-graph database). Use to check whether the project has been indexed (all-zero counts mean you must run init/indexing before graph tools such as ctx_search or ctx_impact will return results). Read-only, no side effects. For a broader project overview (root/git/languages) use ctx_project.
Inputs: no named parameters.
ctx_symbolA
Return deep detail for a single symbol as JSON: [{name, kind, signature, file, line, methods, references, dependencies}]. Use when you already know the exact symbol name and need its definition, signature, methods it exposes, everywhere it is referenced, and its dependencies. For fuzzy or name-based discovery use ctx_search first, then ctx_symbol for the best match. Returns an array because a name may resolve in multiple files.
Inputs: name (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools are clearly distinct, with ctx_symbol, ctx_search, ctx_skeleton, and ctx_context each serving a different purpose. The only mild ambiguities are ctx_project vs ctx_stats and ctx_changed vs ctx_diff, but the descriptions explicitly point to the more detailed or semantic variant.
All tools share the consistent ctx_ prefix and use lowercase snake_case, which makes the set feel uniform. However, the names mix nouns (symbol, skeleton, impact), a verb (search), and an adjective (changed), so it is not a strict verb_noun pattern throughout.
Eleven tools is a well-scoped size for a code-context server. Each tool covers a distinct aspect of code navigation, dependency analysis, impact assessment, or change tracking without redundant entries.
The tool set covers the full workflow: orient with ctx_project, search and inspect symbols, understand file structure, trace dependencies in both directions, assess impact, and inspect git changes at file or symbol level. There are no obvious dead ends for an agent trying to build a contextual picture of a codebase.
Maintenance
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceDeep code indexing for AI agents. Search symbols, navigate call graphs, explore inheritance, track git history — all via MCP.76 PyPI59MIT
- AlicenseCqualityCmaintenanceLocal-first codebase intelligence engine providing AI coding agents with a typed MCP toolset for understanding and navigating code repositories.10054Apache 2.0
- AlicenseBqualityDmaintenanceLocal-first codebase context engine that parses code into a ranked dependency graph and serves it to AI tools via MCP for deep structural understanding.518 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to query a local, continuously updated symbol graph of a codebase, providing ranked search, caller/callee exploration, dependency paths, and git-diff impact analysis through MCP tools.14 npmApache 2.0