ctx++

1![ctx++](ctxpp.png)
2 
3# ctx++
4Fast, accurate codebase intelligence for AI coding agents.
5 
6ctx++ is an MCP (Model Context Protocol) server that gives AI agents precise, structured understanding of large codebases. It extracts symbols using native tree-sitter parsing, indexes them in SQLite with both full-text and vector search, and traces call graphs to automatically map how features are assembled across files -- no hand-maintained documentation required.
7 
8---
9 
10## Why ctx++
11 
12ctx++ is built around three principles:
13 
141. **Never time out.** SQLite with indexed vector and FTS search means queries are fast regardless of codebase size. The MCP server loads in under 2 seconds and all tool calls complete within the MCP timeout window.
152. **Return the right code, not just matching code.** The call graph traversal finds everything involved in a feature by walking real call relationships -- the same way a senior engineer would read the code.
163. **Minimal setup.** A single Go binary plus [Ollama](https://ollama.com) for embeddings. No cloud services, no API keys, no Docker.
17 
18---
19 
20## Tools
21 
22| Tool | Description |
23|---|---|
24| `ctxpp_index` | Index or reindex the codebase. Run once after install; incremental updates happen automatically. |
25| `ctxpp_search` | Search by identifier name (keyword) or natural language (semantic). Returns symbol definitions with file paths and line numbers. |
26| `ctxpp_file_skeleton` | Return all symbols in a file with signatures and line ranges, without reading the full body. Cheap way to understand a file's API surface. |
27| `ctxpp_feature_traverse` | Given an exact symbol name, return related symbols by walking the call graph outward via BFS. The auto-generated feature hub. |
28| `ctxpp_blast_radius` | Given a symbol, return every location in the codebase that references it. Answers "what breaks if I change this?" |
29 
30---
31 
32## Supported Languages
33 
34| Language | Extensions | Symbols Extracted |
35|---|---|---|
36| Go | `.go` | functions, methods, structs, interfaces, types, constants, variables |
37| Java | `.java` | classes, interfaces, enums, methods, constructors, fields |
38| Kotlin | `.kt`, `.kts` | functions, methods, classes, interfaces, properties, imports |
39| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | functions, classes, methods, arrow functions |
40| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | functions, classes, interfaces, type aliases, enums |
41| Rust | `.rs` | functions, structs, enums, traits, impl methods, type aliases |
42| C# | `.cs` | classes, interfaces, methods, fields, imports |
43| C | `.c`, `.h` | functions, structs, enums, typedefs, function-like macros |
44| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh`, `.hxx` | functions, methods, classes, structs, enums, namespaces, templates |
45| SQL | `.sql` | tables, views, indexes, functions, procedures, triggers |
46| Markdown | `.md`, `.mdx` | headings (as sections) |
47| HTML | `.html`, `.htm` | headings, script/style blocks |
48| Shell | `.sh`, `.bash`, `.zsh`, `.dash` | functions |
49| Protobuf | `.proto` | messages, services, RPCs, enums |
50| HTTP | `.http`, `.rest` | named requests |
51| Text/Config | `.txt`, `.env`, `Makefile`, `Dockerfile`, `LICENSE`, etc. | file-level document symbol |
52 
53Want to add another language? See `docs/ADDING-LANGUAGE-SUPPORT.md` for a step-by-step implementation template and PR checklist.
54 
55---
56 
57## Prerequisites
58 
59- **Go 1.24+** for building from source
60- **[Ollama](https://ollama.com)** for semantic search embeddings
61 
62```bash
63# Install Ollama, then pull the default embedding model:
64ollama pull bge-m3
65```
66 
67Without Ollama, ctx++ still works but provides keyword search only. Semantic search and feature traversal quality depend on embeddings.
68 
69---
70 
71## Install
72 
73```bash
74go install github.com/cavenine/ctxpp@latest
75```
76 
77Or build from source:
78 
79```bash
80git clone https://github.com/cavenine/ctxpp
81cd ctxpp
82make build
83```
84 
85---
86 
87## Quick Start
88 
89### 1. Index your project
90 
91```bash
92ctxpp index --path /path/to/your/project
93```
94 
95This creates `.ctxpp/index.db` in the project root. Add it to `.gitignore`:
96 
97```
98.ctxpp/
99```
100 
101Subsequent runs only re-process changed files. Branch switches self-heal automatically via the file watcher.
102 
103If parser logic changes but your source files do not, force a full reparse of supported files:
104 
105```bash
106ctxpp index --path /path/to/your/project --force
107```
108 
109### 2. Add to your MCP config
110 
111The examples below use Ollama with `bge-m3` (the default). If Ollama is not running, omit `CTXPP_OLLAMA_*` — ctx++ will fall back to keyword search only.
112 
113**OpenCode** (`opencode.json` in project root):
114 
115```json
116{
117  "mcp": {
118    "ctxpp": {
119      "type": "local",
120      "command": ["ctxpp", "mcp"],
121      "enabled": true,
122      "environment": {
123        "CTXPP_PROJECT": "/path/to/your/project",
124        "CTXPP_OLLAMA_URL": "http://localhost:11434",
125        "CTXPP_OLLAMA_MODEL": "bge-m3"
126      }
127    }
128  }
129}
130```
131 
132**Claude Code** (`.mcp.json`):
133 
134```json
135{
136  "mcpServers": {
137    "ctxpp": {
138      "command": "ctxpp",
139      "args": ["mcp"],
140      "env": {
141        "CTXPP_PROJECT": "/path/to/your/project",
142        "CTXPP_OLLAMA_URL": "http://localhost:11434",
143        "CTXPP_OLLAMA_MODEL": "bge-m3"
144      }
145    }
146  }
147}
148```
149 
150**Cursor / Windsurf** (`.cursor/mcp.json` or `.windsurf/mcp.json`):
151 
152```json
153{
154  "mcpServers": {
155    "ctxpp": {
156      "command": "ctxpp",
157      "args": ["mcp"],
158      "env": {
159        "CTXPP_PROJECT": "/path/to/your/project",
160        "CTXPP_OLLAMA_URL": "http://localhost:11434",
161        "CTXPP_OLLAMA_MODEL": "bge-m3"
162      }
163    }
164  }
165}
166```
167 
168### 3. Use it
169 
170Ask your AI agent anything about the codebase:
171 
172```
173use ctxpp to show me everything involved in account authentication
174```
175 
176```
177use ctxpp to find where FetchAccount is defined and what calls it
178```
179 
180```
181use ctxpp_blast_radius to tell me what breaks if I change the Account struct
182```
183 
184---
185 
186## Ollama Integration
187 
188ctx++ uses [Ollama](https://ollama.com) for embedding-based semantic search. The default model is `bge-m3` (BAAI's BGE-M3, 1024 dimensions), which was selected through head-to-head quality benchmarks against multiple models on real codebases.
189 
190```bash
191ollama pull bge-m3
192```
193 
194ctx++ auto-detects Ollama on `localhost:11434` at startup. If Ollama is not running, ctx++ falls back to keyword search only and prints a warning.
195 
196To use a different embedding model (e.g., `all-minilm` for faster indexing at the cost of some search quality):
197 
198```json
199"environment": {
200  "CTXPP_PROJECT": "/path/to/your/project",
201  "CTXPP_OLLAMA_MODEL": "all-minilm"
202}
203```
204 
205---
206 
207## AWS Bedrock Integration
208 
209For environments without a local GPU, ctx++ can use [Amazon Titan Text Embeddings V2](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html) via AWS Bedrock. Quality is comparable to the Ollama/bge-m3 default (4.7/5 vs 4.8/5 on the kubernetes benchmark).
210 
211**Prerequisites**: AWS credentials configured via `~/.aws/credentials`, `AWS_PROFILE`, or IAM role. The identity needs `bedrock:InvokeModel` permission on `amazon.titan-embed-text-v2:0`.
212 
213Set `CTXPP_EMBED_BACKEND=bedrock` and the following env vars:
214 
215**OpenCode** (`opencode.json` in project root):
216 
217```json
218{
219  "mcp": {
220    "ctxpp": {
221      "type": "local",
222      "command": ["ctxpp", "mcp"],
223      "enabled": true,
224      "environment": {
225        "CTXPP_PROJECT": "/path/to/your/project",
226        "CTXPP_EMBED_BACKEND": "bedrock",
227        "CTXPP_BEDROCK_REGION": "us-east-1",
228        "CTXPP_BEDROCK_MODEL": "amazon.titan-embed-text-v2:0",
229        "CTXPP_BEDROCK_DIMS": "1024",
230        "CTXPP_EMBED_CONCURRENCY": "100"
231      }
232    }
233  }
234}
235```
236 
237**Claude Code** (`.mcp.json`):
238 
239```json
240{
241  "mcpServers": {
242    "ctxpp": {
243      "command": "ctxpp",
244      "args": ["mcp"],
245      "env": {
246        "CTXPP_PROJECT": "/path/to/your/project",
247        "CTXPP_EMBED_BACKEND": "bedrock",
248        "CTXPP_BEDROCK_REGION": "us-east-1",
249        "CTXPP_BEDROCK_MODEL": "amazon.titan-embed-text-v2:0",
250        "CTXPP_BEDROCK_DIMS": "1024",
251        "CTXPP_EMBED_CONCURRENCY": "100"
252      }
253    }
254  }
255}
256```
257 
258**Cursor / Windsurf** (`.cursor/mcp.json` or `.windsurf/mcp.json`):
259 
260```json
261{
262  "mcpServers": {
263    "ctxpp": {
264      "command": "ctxpp",
265      "args": ["mcp"],
266      "env": {
267        "CTXPP_PROJECT": "/path/to/your/project",
268        "CTXPP_EMBED_BACKEND": "bedrock",
269        "CTXPP_BEDROCK_REGION": "us-east-1",
270        "CTXPP_BEDROCK_MODEL": "amazon.titan-embed-text-v2:0",
271        "CTXPP_BEDROCK_DIMS": "1024",
272        "CTXPP_EMBED_CONCURRENCY": "100"
273      }
274    }
275  }
276}
277```
278 
279Or for initial indexing from the command line:
280 
281```bash
282export CTXPP_EMBED_BACKEND=bedrock
283export CTXPP_BEDROCK_REGION=us-east-1
284export CTXPP_BEDROCK_MODEL=amazon.titan-embed-text-v2:0
285export CTXPP_BEDROCK_DIMS=1024
286export CTXPP_EMBED_CONCURRENCY=100   # increase to 200 for large repos
287ctxpp index --path /path/to/your/project
288```
289 
290**Trade-offs vs Ollama:**
291 
292| | Ollama (local GPU) | Bedrock |
293|--|--|--|
294| Per-query embed latency | ~25ms | 100-460ms |
295| Index time (kubernetes, 318K symbols) | 47m | ~7.5h |
296| GPU required | Yes | No |
297| Cost | Free (local) | AWS API pricing |
298| Horizontal scaling | Limited by GPU | High (100-200 concurrent) |
299| Quality (kubernetes benchmark) | 4.8/5 | 4.7/5 |
300 
301Bedrock is the right choice for CI/CD pipelines, cloud-hosted agents, or developer machines without a GPU. For interactive development with a GPU available, Ollama is faster.
302 
303---
304 
305## OpenAI-Compatible Embeddings Integration
306 
307ctx++ can also use any provider that exposes the OpenAI `POST /v1/embeddings` API. This includes OpenAI, OpenAI-compatible proxies, vLLM, LiteLLM, LocalAI, and Ollama's OpenAI-compatible endpoint.
308 
309Set `CTXPP_EMBED_BACKEND=openai` and configure:
310 
311- `CTXPP_OPENAI_URL`
312- `CTXPP_OPENAI_MODEL`
313- `CTXPP_OPENAI_DIMS`
314- `CTXPP_OPENAI_API_KEY` (optional for local unauthenticated servers)
315 
316Example with OpenAI hosted embeddings:
317 
318```json
319{
320  "mcpServers": {
321    "ctxpp": {
322      "command": "ctxpp",
323      "args": ["mcp"],
324      "env": {
325        "CTXPP_PROJECT": "/path/to/your/project",
326        "CTXPP_EMBED_BACKEND": "openai",
327        "CTXPP_OPENAI_URL": "https://api.openai.com",
328        "CTXPP_OPENAI_MODEL": "text-embedding-3-small",
329        "CTXPP_OPENAI_DIMS": "1536",
330        "CTXPP_OPENAI_API_KEY": "${OPENAI_API_KEY}"
331      }
332    }
333  }
334}
335```
336 
337Example with Ollama's OpenAI-compatible endpoint:
338 
339```bash
340export CTXPP_EMBED_BACKEND=openai
341export CTXPP_OPENAI_URL=http://localhost:11434
342export CTXPP_OPENAI_MODEL=bge-m3
343export CTXPP_OPENAI_DIMS=1024
344ctxpp index --path /path/to/your/project
345```
346 
347This backend is opt-in only. Auto-detection still prefers TEI, then Ollama, then bundled fallback.
348 
349---
350 
351## Configuration
352 
353All configuration is via environment variables.
354 
355| Variable | Default | Description |
356|---|---|---|
357| `CTXPP_PROJECT` | `.` | Path to the project root to index |
358| `CTXPP_OLLAMA_URL` | `http://localhost:11434` | Ollama API endpoint |
359| `CTXPP_OLLAMA_MODEL` | `bge-m3` | Ollama embedding model |
360| `CTXPP_EMBED_BACKEND` | _(auto-detect)_ | Embedding backend: `auto`, `ollama`, `tei`, `openai`, `bedrock`, or `bundled` |
361| `CTXPP_OPENAI_URL` | `https://api.openai.com` | OpenAI-compatible embeddings API base URL |
362| `CTXPP_OPENAI_MODEL` | _(required with `openai`)_ | OpenAI-compatible embedding model |
363| `CTXPP_OPENAI_API_KEY` | _(optional)_ | Bearer token for OpenAI-compatible providers |
364| `CTXPP_OPENAI_DIMS` | _(required with `openai`)_ | Embedding dimensions for the selected OpenAI-compatible model |
365| `CTXPP_WORKERS` | number of CPUs | Parallel workers for initial indexing |
366| `CTXPP_EMBED_CONCURRENCY` | `10` | Max concurrent embedding requests (mainly Bedrock) |
367 
368---
369 
370## CLI Reference
371 
372```
373ctxpp index [--path/-p <path>] [--force]  Index or reindex a project (default: $CTXPP_PROJECT or current directory)
374ctxpp backfill [--path/-p <path>]  Re-embed symbols missing embedding vectors
375ctxpp mcp                          Start the MCP server over stdio
376ctxpp version                      Print version
377```
378 
379---
380 
381## Architecture
382 
383ctx++ is written in Go and built on:
384 
385- **[go-tree-sitter](https://github.com/tree-sitter/go-tree-sitter)** -- native C tree-sitter bindings for fast, accurate AST parsing across all supported languages
386- **SQLite** via `modernc.org/sqlite` (pure Go, no CGO) with FTS5 for full-text search and brute-force cosine similarity for vector search
387- **[Ollama](https://ollama.com)** for embedding generation (default model: `bge-m3`)
388- **MCP SDK** for stdio-based MCP transport
389 
390The index lives in a single `.ctxpp/index.db` file per project. The schema tracks files, symbols, embeddings, call edges, and import edges. All queries hit indexed columns -- no full-table scans, no loading the entire index into memory.
391 
392See [PRD.md](PRD.md) for full architecture and design decisions.
393 
394---
395 
396## How Feature Traversal Works
397 
398When you ask `ctxpp_feature_traverse` about a symbol (e.g. `"HandleLogin"`):
399 
4001. A keyword search finds symbols with that exact name in the index
4012. The call graph is walked outward from each seed via BFS — what does this function call? What do those functions call?
4023. Results are returned in BFS order (seed first, then direct callees, then transitive callees) up to the configured depth (default: 3 hops)
403 
404This gives you the full call tree rooted at a symbol — useful for understanding what a function orchestrates without reading every file manually. Use `ctxpp_blast_radius` for the reverse direction: what calls this function?
405 
406---
407 
408## License
409 
410MIT
411