AI coding assistants like Copilot, Claude Code, and Cursor rely on generic tools grep, find, file reads to understand your codebase. On brownfield projects with thousands of files, this brute-force exploration creates a chain of problems:
- Context window saturation The agent fills its window reading files one by one, leaving little room for actual reasoning
- Partial context hallucination It sees a function but misses its dependencies, leading to wrong assumptions and broken suggestions
- Lost-in-the-middle Critical information buried deep in a long context gets ignored by the model
- Context poisoning Irrelevant code pulled in during exploration biases the model's output
- Iteration overhead Understanding one symbol takes 10-20 tool calls, each adding more noise to the context
- Stale reasoning After too many iterations, the agent contradicts its own earlier assumptions
The result: more tokens burned, slower responses, higher cost, and lower quality output.
Ctxo is an MCP server that enhances your existing AI tools with dependency-aware, history-enriched code intelligence. Instead of hundreds of grep and read_file calls, your agent gets the full picture symbol graphs, blast radius, git intent, and risk scores in a single MCP call.
- Clean context Only relevant symbols and their transitive dependencies, nothing more
- Fewer iterations One call replaces an entire exploration cycle
- Higher quality The agent reasons over structured, complete context instead of fragmented file reads
A senior developer takes ~10 minutes to gather context across files. Ctxo delivers that same context in under 500ms.
Install the CLI, then run the setup wizard:
npm i -g @ctxo/cli
ctxo initThat's it. The interactive wizard detects your AI tools, registers the ctxo MCP server in the correct config file (.mcp.json, .vscode/mcp.json, etc.), generates usage rules so your assistant knows when to call each tool, and prompts to install language plugins it detects in your project (pass --no-install to skip).
As of v0.7, Ctxo discovers language support from npm packages listed in your project's package.json. Three official plugins ship today:
npm i -D @ctxo/lang-typescript @ctxo/lang-go @ctxo/lang-csharpOr install one at a time with the CLI shortcut: ctxo install typescript (supports --yes, --global, --dry-run, --pm, --version). Any package named @ctxo/lang-* or ctxo-lang-* in your dependencies is auto-loaded.
Manual MCP config (if not using ctxo init)
Claude Code / Cursor / Windsurf / Augment / Antigravity — .mcp.json:
{ "mcpServers": { "ctxo": { "command": "npx", "args": ["-y", "@ctxo/cli"] } } }VS Code (Copilot) — .vscode/mcp.json:
{ "servers": { "ctxo": { "type": "stdio", "command": "npx", "args": ["-y", "@ctxo/cli"] } } }Amazon Q — .amazonq/mcp.json:
{ "mcpServers": { "ctxo": { "command": "npx", "args": ["-y", "@ctxo/cli"] } } }Zed — settings.json:
{ "context_servers": { "ctxo": { "command": { "path": "npx", "args": ["-y", "@ctxo/cli"] } } } }| Tool | What it does |
|---|---|
get_logic_slice |
Symbol + transitive dependencies (L1-L4 progressive detail) |
get_blast_radius |
What breaks if this changes (3-tier: confirmed/likely/potential) |
get_architectural_overlay |
Project layer map (Domain/Infrastructure/Adapter) |
get_why_context |
Git commit intent + anti-pattern warnings (reverts, rollbacks) |
get_change_intelligence |
Complexity x churn composite score |
find_dead_code |
Unreachable symbols, unused exports, scaffolding markers |
get_context_for_task |
Task-optimized context (fix/extend/refactor/understand) |
get_ranked_context |
Two-phase BM25 search (camelCase-aware, fuzzy correction) + PageRank within token budget |
search_symbols |
Symbol name/regex search across index (mode: 'fts' for BM25) |
get_changed_symbols |
Symbols in recently changed files (git diff) |
find_importers |
Reverse dependency lookup ("who uses this?") |
get_class_hierarchy |
Class inheritance tree (ancestors + descendants) |
get_symbol_importance |
PageRank centrality ranking |
get_pr_impact |
Full PR risk assessment in a single call |
Reviewing a PR? → get_pr_impact
About to modify code? → get_blast_radius → get_why_context
Understanding a symbol? → get_context_for_task(taskType: "understand")
Fixing a bug? → get_context_for_task(taskType: "fix")
Refactoring? → get_context_for_task(taskType: "refactor")
Don't know the name? → search_symbols or get_ranked_context
Finding unused code? → find_dead_code
Safe to delete? → find_importers
Onboarding? → get_architectural_overlay → get_symbol_importance
# Setup
ctxo init # Interactive setup (detects languages, prompts to install plugins, writes AI tool rules, git hooks)
ctxo init --tools claude-code,cursor -y # Non-interactive setup
ctxo init --no-install # Skip plugin install prompt
ctxo init --rules # Regenerate AI tool rules only
ctxo init --dry-run # Preview what would be created
# Plugins (v0.7+)
ctxo install # Install plugins for all detected languages
ctxo install typescript go csharp # Install specific plugins
ctxo install typescript --yes --pm pnpm # CI-friendly, pick package manager
ctxo install typescript --global --version 0.7.0 # Pin version, install globally
# Indexing
ctxo index # Build full codebase index
ctxo index --install-missing # Auto-install any missing plugins first
ctxo index --check # CI gate: fail if index stale
ctxo index --skip-history # Fast re-index without git history
ctxo watch # File watcher for incremental re-index
ctxo sync # Rebuild SQLite cache from committed JSON
# Diagnostics
ctxo status # Show index manifest
ctxo doctor # Health check all subsystems (--json, --quiet)
ctxo doctor --fix # Dependency-ordered auto-remediation (--dry-run, --yes)
ctxo stats # Show usage statistics (--json, --days N, --clear)
ctxo --version # Print CLI version (--verbose, --json)
ctxo version # Verbose version subcommand (CLI + plugins + runtime)Example output:
ctxo stats
Usage Summary (all time)
────────────────────────────────────────
Total tool calls: 30
Total tokens served: 26.0K
Top Tools
────────────────────────────────────────
get_logic_slice 14 calls avg 352 tokens
get_blast_radius 3 calls avg 1,279 tokens
get_ranked_context 3 calls avg 898 tokens
find_importers 2 calls avg 1,342 tokens
get_context_for_task 2 calls avg 740 tokens
Top Queried Symbols
────────────────────────────────────────
SymbolNode 15 queries
LogicSliceQuery 4 queries
SqliteStorageAdapter 2 queries
Detail Level Distribution
────────────────────────────────────────
L1: ███░░░░░░░ 25%
L2: ███░░░░░░░ 25%
L3: ███░░░░░░░ 25%
L4: ███░░░░░░░ 25%
Keep the committed .ctxo/index/ in sync with the source tree by failing PRs when the index is stale. Drop-in examples:
- GitHub Actions: examples/github-actions/ctxo-check.yml
- GitLab CI: examples/gitlab-ci/.gitlab-ci.yml
Both run ctxo index --check on every PR/MR. If the index is stale, the job fails and the author runs ctxo index locally, then commits the refreshed index. Combined with the post-commit hook from ctxo init, this keeps the index current without any webhook infrastructure.
Response Envelope All responses include _meta with item counts, truncation info, and drill-in hints. Large results auto-truncated at 8KB (configurable via CTXO_RESPONSE_LIMIT).
Intent Filtering 4 tools accept intent parameter for keyword-based result filtering. get_blast_radius(symbolId, intent: "test") returns only test-related impacts.
Tool Annotations All tools declare readOnlyHint: true, idempotentHint: true, openWorldHint: false for safe auto-approval in agent frameworks.
Privacy Masking AWS keys, GCP service accounts, Azure connection strings, JWTs, private IPs, env secrets automatically redacted. Extensible via .ctxo/masking.json.
Interactive Graph ctxo visualize generates a self-contained HTML with vis.js dependency graph. ForceAtlas2 layout, PageRank-based sizing, layer coloring, blast radius on click, git history per symbol, dead code and anti-pattern filters, dark/light theme.
Debug Mode DEBUG=ctxo:* for all debug output, or DEBUG=ctxo:git,ctxo:storage for specific namespaces.
Per-tool savings vs manual approach:
Manual Tokens Ctxo Tokens Savings
get_logic_slice ████████ 1,950 █ 150 92%
get_blast_radius ███ 800 ██ 600 25%
get_overlay ████████████ 25K██ 500 98%
get_why_context █ 200 █ 200 0%
get_change_intelligence ████████ 2,100 ▏ 50 98%
find_dead_code █████████ 5,000 ████ 2,000 60%
────────────────────────────────────────────────────────────
TOTAL 35,050 tokens 3,500 tokens 90%
329+ calls 6 calls 98%
Claude Agent SDK:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Analyze the blast radius of AuthService",
options: {
mcpServers: { ctxo: { command: "npx", args: ["-y", "@ctxo/cli"] } },
allowedTools: ["mcp__ctxo__*"]
}
})) { /* ... */ }OpenAI Agents SDK:
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
async with MCPServerStdio(params={"command": "npx", "args": ["@ctxo/cli"]}) as ctxo:
agent = Agent(name="Reviewer", mcp_servers=[ctxo])
result = await Runner.run(agent, "Review the PR impact")See Agentic AI Integration Guide for LangChain, raw MCP client, and CI/CD examples.
Language support ships as standalone plugins. Install only what your repo needs.
| Language | Plugin Package | Engine | Tier | Toolchain required | Features |
|---|---|---|---|---|---|
| TypeScript/JavaScript | @ctxo/lang-typescript |
ts-morph | Full | bundled | Type-aware resolution, cross-file imports, this.method() calls, complexity metrics |
| C# | @ctxo/lang-csharp |
ctxo-roslyn (Roslyn) |
Full | .NET SDK ≥ 8 on PATH | Symbols + calls / uses / implements / extends, cross-project resolution, complexity, tree-sitter fallback |
| Go | @ctxo/lang-go |
ctxo-go-analyzer |
Full | Go ≥ 1.22 on PATH | Symbols + calls / uses / implements / extends, reflect-safe dead-code, generics, tree-sitter fallback |
| All other languages | @ctxo/lang-* / ctxo-lang-* (plugin protocol) |
tree-sitter (community adapter) | Syntax | bundled per plugin | Symbol inventory (functions, classes, types, methods), import edges, cyclomatic complexity, unexported symbols |
Full tier delivers type-resolved semantic edges across package boundaries — what get_blast_radius, find_importers, find_dead_code and get_class_hierarchy actually need. Requires the language's official toolchain on PATH; graceful degradation to tree-sitter syntax tier when missing.
Syntax tier works out of the box via the @ctxo/plugin-api protocol (v1). Any package named @ctxo/lang-* or ctxo-lang-* in your dependencies is auto-discovered — third-party plugins can deliver new languages without touching core.
Ctxo ships with an interactive visualizer that renders your codebase index as a dependency graph. Explore symbols, edges, layers, and PageRank scores visually deployed automatically to GitHub Pages on every push.
Ctxo builds a committed JSON index (.ctxo/index/) that captures symbols, dependency edges, git history, and co-change data. The MCP server reads this index to answer queries no runtime parsing, no external services.
The codebase is a pnpm monorepo with 5 packages: @ctxo/cli (this package), @ctxo/plugin-api (plugin protocol v1), and three official language plugins (@ctxo/lang-typescript, @ctxo/lang-go, @ctxo/lang-csharp).
.ctxo/
index/ ← committed (per-file JSON, reviewable in PRs)
.cache/ ← gitignored (local SQLite, auto-rebuilt)
config.yaml ← committed (team settings)
masking.json ← committed (custom masking patterns)
MIT