What is Code Context Engine?
A complete guide to understanding and using CCE. What it does, why you need it, how to set it up, and what happens under the hood.
The problem CCE solves
When you use an AI coding agent (Claude Code, Cursor, Copilot, Gemini), it needs to understand your codebase to answer questions and write code. The way it does this today is by reading entire files.
Ask "how does the payment flow work?" and the agent reads payments.py (800 lines), shipping.py (600 lines), and orders.py (400 lines). That's 45,000 tokens of input. You pay for every one of them.
The problem: most of those tokens are irrelevant. The answer was in 3 functions totaling 40 lines. The other 1,760 lines were wasted context.
Input tokens are 85-95% of your AI coding bill. Output tokens (the AI's responses) are cheap. The expensive part is feeding your code into the model.
What CCE does
Code Context Engine (CCE) is a local tool that indexes your codebase and lets AI agents search instead of read.
Instead of reading 3 entire files (45,000 tokens), the AI calls context_search("payment flow") and gets back the 3 relevant functions (800 tokens). Same answer. 94% fewer tokens.
| Without CCE | With CCE | |
|---|---|---|
| How the AI gets context | Reads entire files | Searches the index |
| Tokens per query | 83,681 | 4,927 |
| What the AI sees | Everything in the file | Only the relevant code |
| Your cost (Sonnet) | $0.14/session | $0.04/session |
How to set it up (60 seconds)
Install CCE
uv tool install code-context-engine
Or use pipx install code-context-engine if you don't have uv. Requires Python 3.11+.
Initialize your project
cd /path/to/your/project cce init
This does everything automatically:
- Indexes your codebase (parses code into semantic chunks)
- Registers the MCP server with your editor
- Installs git hooks so the index stays current
- Creates a CLAUDE.md with instructions for the AI
Restart your editor
That's it. Your AI agent now searches the index instead of reading files. No configuration needed.
Which editors work with CCE?
cce init auto-detects your editor and writes the right config:
| Editor | How it connects |
|---|---|
| Claude Code | MCP via .mcp.json |
| Cursor | MCP via .cursor/mcp.json |
| VS Code / Copilot | MCP via .vscode/mcp.json |
| Gemini CLI | MCP via .gemini/settings.json |
| Codex CLI | MCP via ~/.codex/config.toml |
| OpenCode | MCP via opencode.json |
Multiple editors in the same project? All get configured in one command.
What is MCP?
Model Context Protocol (MCP) is an open standard that lets AI agents use external tools. CCE is an MCP server. When Claude Code needs to understand your code, it calls CCE's tools through MCP instead of reading files directly.
You don't need to understand MCP to use CCE. cce init handles the wiring.
How it works under the hood
1. Indexing
CCE uses tree-sitter (the same parser used by GitHub, Neovim, and Zed) to parse your code into semantic chunks: functions, classes, modules. Each chunk gets a vector embedding stored locally in SQLite.
2. Searching
When the AI calls context_search("payment flow"), CCE runs a hybrid search: vector similarity (finds conceptually related code) combined with BM25 keyword matching (finds exact terms). Results are ranked by a confidence scorer that blends similarity, keyword match, and recency.
3. Graph expansion
If payments.py is a hit, CCE checks the code graph and automatically pulls in files it imports or calls. You get the dependency chain without asking for it.
4. Compression
Retrieved chunks are compressed to signatures and docstrings. A 200-line function becomes its signature + first docstring paragraph. The AI gets the shape of the code without every implementation detail.
5. Memory
CCE remembers decisions across sessions. Call record_decision("use JWT for auth") and next session, session_recall("auth") brings it back. No re-explaining your architecture.
What tools does CCE give the AI?
| Tool | What it does |
|---|---|
context_search | Search for relevant code by description |
expand_chunk | Get the full source of a compressed result |
related_context | Find code connected via imports/calls |
session_recall | Recall decisions from past sessions |
record_decision | Save a decision for future sessions |
record_code_area | Note which files were worked on |
reindex | Re-index a file or the full project |
index_status | Check index health |
set_output_compression | Adjust how verbose Claude's replies are |
The AI uses these tools automatically. You don't need to call them yourself.
Does the index stay current?
Yes. Git hooks reindex on every commit, checkout, and merge. CCE uses content hashing (SHA-256 per file), so only changed files get re-processed. Typical reindex after editing a few files: under 1 second.
Is my code sent to the cloud?
No. Everything runs locally. The index is stored in ~/.cce/projects/. Embeddings are computed on your CPU using a local ONNX model. No API keys, no cloud services, no data leaves your machine.
How do I see my savings?
cce savings
Shows tokens saved, dollar amounts (from live Anthropic pricing), and per-layer breakdown. Run cce savings --all to see savings across all your projects.
How do I remove it?
cce uninstall
Removes everything: hooks, config files, index data, editor settings. Clean removal, nothing left behind.
Supported languages
AST-aware chunking (tree-sitter parsed): Python, JavaScript, TypeScript, JSX, TSX, PHP, Go, Rust, Java.
Fallback chunking (line-based): Markdown, YAML, JSON, config files, and all other text files.
FAQ
Does it work on large codebases?
Tested on repos up to 400+ files (1M tokens). Indexing takes 30-60 seconds on first run, under 1 second for incremental updates.
What if the search returns wrong code?
Recall@10 = 0.90 (tested on FastAPI). 9/10 times it finds the right file. The 10% miss is usually cross-cutting queries spanning many files. The AI falls back to reading files normally when search doesn't help.
Can I use it alongside Cursor's built-in indexing?
Yes. They don't conflict. CCE provides an additional MCP-based search. Cursor's native indexing still works.
Is it free?
Yes. MIT licensed. Free forever. No paid tier, no usage limits.
Try it now
Three commands. 60 seconds. See your savings immediately.
uv tool install code-context-engine && cd your-project && cce init
View on GitHub