Skip to main content
Glama

ctx

Codebase intelligence and context engine for AI coding agents.

CI Release npm License MCP

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 information

Related 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 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

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 "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:

Tool

Purpose

ctx_project

project overview (root, git, counts)

ctx_search

symbol / file search (with kind + files filters)

ctx_skeleton

body-less structural skeleton of a file

ctx_symbol

definition, methods, references, deps of a symbol

ctx_dependencies / ctx_dependents

outgoing / incoming imports

ctx_impact

change-impact analysis (symbol or path, depth)

ctx_context

ranked context package (task, include_bodies, max_tokens)

ctx_changed

files & symbols changed since a ref

ctx_diff

semantic diff of symbols between refs (single base resolves to its merge-base with HEAD)

ctx_stats

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

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

Language

Files

Symbols

Dependencies

Skeleton

TypeScript

ts, tsx, mts, cts

functions, methods, classes, interfaces, enums, constants, fields, modules, type aliases

import / require / dynamic import() / re-exports; ./, ../, @/ aliases, bare specifiers

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

import x, from x import y, relative imports

bodies elided

Rust

rs

functions, structs, enums, traits, impl blocks, methods, consts

use — crate::, self::, super::

impl/fn bodies elided, struct/enum kept

Go

go

functions, methods, types, interfaces, consts

package import paths

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 = 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.

Available Tools

11 tools
ctx_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_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

    A4.4/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Deep code indexing for AI agents. Search symbols, navigate call graphs, explore inheritance, track git history — all via MCP.
      76 PyPI
      59
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Local-first codebase intelligence engine providing AI coding agents with a typed MCP toolset for understanding and navigating code repositories.
      100
      54
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      Local-first codebase context engine that parses code into a ranked dependency graph and serves it to AI tools via MCP for deep structural understanding.
      5
      18 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      Apache 2.0