code context engine
About
A local MCP server for AI coding agents. AST-aware indexing, semantic search, and automatic compression. Your agent stops re-reading your entire codebase every session.
Details
- Author
- elara-labs
- Categories
- Developer Tools, Knowledge Base, Search
Jump to
Setup
Install code context engine in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/elara-labs/code-context-engine
Follow the installation instructions in the repository README, then restart your MCP client.
A local MCP server for AI coding agents. AST-aware indexing, semantic search, and automatic compression. Your agent stops re-reading your entire codebase every session.
Index your codebase. AI searches instead of re-reading files.
94% token savings, reproducibly benchmarked.
Website·Docs·Why CCE?·Benchmark·GitHub
One command. Auto-detects your editor. Zero cloud, zero config.
Talk:We Cut 94% of Our AI Coding Tokens— AI Engineer World's Fair 2026
uvx --from "code-context-engine[local]" cce init # install + index + configure, one shot
uv tool install "code-context-engine[local]" # or: pipx install "code-context-engine[local]" cd /path/to/your/project cce init
Restart your editor. Done. Every question now hits the index instead of re-reading files.
Agent Plugin support:Runcce init --pluginto generate a portableAgent Plugindirectory that works with VS Code, Cursor, Copilot, Codex, ChatGPT, and Kiro. The plugin usesuvxto launch CCE on demand, so users don't need to pre-install the Python package. SeeAgent Pluginbelow.
Already have Ollama?Skip[local]and useuv tool install code-context-engineinstead. CCE auto-detects Ollama at localhost:11434 and usesnomic-embed-text.
Python 3.11+ and a C compiler (for tree-sitter grammars).
Tested on macOS, Linux, Windows with Python 3.11/3.12/3.13.
cce initauto-detects your editor and writes the right config. To target a specific agent, use--agent claude,--agent codex,--agent copilot,--agent pi, or--agent all.
Multiple editors in the same project? All get configured in one command.
Codex note:Codex CLI reads MCP servers from~/.codex/config.tomlonly — it has no per-project config.cce initadds one[mcp_servers.cce-<project>-<hash>]section per project so multiple projects coexist;cce uninstallremoves only the section for the current project.
Pi note:Pi does not support MCP natively. To use CCE with Pi, you need a pi MCP adapter extension (e.g.pi-mcp-adapter) that consumes the.mcp.jsonconfig and exposes CCE's tools to the Pi agent.cce initsets up both.mcp.jsonandAGENTS.md(Pi loads the latter automatically for startup instructions).
my-project · 38 queries · last query 5m ago ⛁ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ 88% tokens saved Input savings 1.9M tokens $27.78 Output savings 4.8k tokens $0.36 ────────────────────────────────────────── Total saved 1.9M tokens $28.15 Breakdown: retrieval 84% ▰▰▰▰▰▰▰▰▰▰ 1.8M $26.76 · 12 calls chunk compression 3% ▰▱▱▱▱▱▱▱▱▱ 68.5k $1.03 · 12 calls output compression <1% ▰▱▱▱▱▱▱▱▱▱ 4.8k $0.36 · 12 calls Cost estimate based on Opus pricing (input $15.0/1M, output $75.0/1M)
Supports Anthropic, OpenAI, and Google model pricing. Configure viapricing.modelin~/.cce/config.yaml.
Input tokens are 85-95% of your Claude Code bill. CCE cuts them by 94% (benchmarked on FastAPI).
Without CCE: Claude reads payments.py + shipping.py = 45,000 tokens With CCE: context_search "payment flow" = 800 tokens
We benchmarked CCE againstFastAPI(53 source files, 180K tokens) with 20 real coding questions. No cherry-picking, no synthetic queries.
Methodology:For each query, "without CCE" means reading the full content of every file the query touches. "With CCE" means the relevant chunks after compression.
Important baseline note:The 94% number is measured against full-file reads, not against what Claude Code actually does. In practice, Claude Code already uses grep, partial file reads, and targeted tools, so the real-world savings compared to normal Claude Code behavior will be lower than 94%. We use full-file as the baseline because it's reproducible and deterministic (no agent behavior variability). The benchmark measures CCE's retrieval efficiency, not a head-to-head comparison with Claude Code's built-in exploration.
Per-Layer Savings (each measured independently)
Output compression (reducing Claude's reply length) provides additional savings (~65% estimated) but is not included in the headline number above.
Django (2,347 files, 5.4M tokens) shows CCE scales to large codebases with 0.95 recall. Go's shorter files reduce the retrieval headroom (smaller baseline). Monorepos dilute recall at top-10 (fiber). Middleware queries with one-feature-per-file hit R=1.00 consistently.
pip install code-context-engine python benchmarks/run_benchmark.py --repo https://github.com/fastapi/fastapi.git --source-dir fastapi python benchmarks/run_benchmark.py --repo https://github.com/go-chi/chi.git --source-dir .
Full results inbenchmarks/results/. Queries and methodology inbenchmarks/.
11 MCP toolsthat Claude uses automatically:
Live dashboardwith donut charts, file health, and session history:
Dollar estimateswith multi-provider pricing (Anthropic, OpenAI, Google):
cce savings --all # see savings across all projects
- Index:Tree-sitter parses your code into semantic chunks (functions, classes, modules). Stored as vector embeddings locally.
- Search:Claude callscontext_search. Hybrid vector + BM25 retrieval finds the right chunks. Code graph adds related files automatically.
- Compress:Chunks are truncated to signatures + docstrings (or LLM-summarized if Ollama is running).
- Remember:Decisions and code areas persist across sessions viasession_recall.
- Track:Every query is logged.cce savingsshows exactly how much you saved.
Re-indexing after edits takes under 1 second (96% embedding cache hit rate). Git hooks keep the index current automatically.
Output compression tools (like Caveman) save 20-75% on output tokens. Output is 5-15% of your bill. Net savings: ~11%.
CCE saves oninputtokens (94% retrieval savings on FastAPI,reproducibly benchmarked). Input is 85-95% of your bill.
Not a text search. Tree-sitter AST parsing creates semantic chunks. Hybrid retrieval merges vector similarity with BM25 keyword matching via Reciprocal Rank Fusion. A confidence scorer blends similarity (50%), keyword match (30%), and recency (20%). Graph expansion walks CALLS/IMPORTS edges to pull in related code.
record_decision("use JWT for auth", reason="session tokens flagged by legal")is stored in SQLite and surfaces viasession_recallin the next session. No re-explaining your architecture.
Not estimates. Actual tokens served vs full-file baseline, broken down by buckets (retrieval, compression, output, memory, grammar). Dollar costs fetched from Anthropic's pricing page. Savings summary shown at every session start.
Secret files (.env, .pem, credentials.json) are never indexed. Content is scanned for AWS keys, GitHub tokens, Slack tokens, Stripe keys, JWTs, and generic credentials. PII (emails, IPs, SSNs, credit cards) is scrubbed from memory writes. All MCP file paths are validated against path traversal.
SHA-256 fingerprint per chunk, salted with model name. Re-index skips unchanged code. Binary float32 storage (10x smaller than JSON). Typical re-index: 96% cache hit, under 1 second.
Replaced LanceDB with sqlite-vec. Same cosine-distance quality, 99% smaller install. WAL mode + PRAGMA NORMAL for 80% write speedup. Vectors, FTS5, code graph, and compression cache all in three SQLite files.
Memory entries compressed without LLM calls. Drops articles, fillers, pronouns. Three levels (lite/full/ultra, 20-60% savings). Code, paths, URLs preserved byte-for-byte. Same input always yields same output.
5 Claude Code lifecycle hooks capture session context. Every hook runscurl ... || true, so a crashed server never blocks the user. SessionStart injects bootstrap context; others capture silently.
Dollar estimates incce savingssupport 15+ models across Anthropic, OpenAI, and Google. Static pricing ships with CCE, live Anthropic pricing is fetched and cached 7 days. Configurepricing.model(e.g.gpt-4o,gemini-2.5-pro,sonnet) or override withpricing.input/pricing.outputfor custom rates.
Running dozens ofcce serveprocesses (one per project per AI session) can exhaust system memory. The resource governor caps ONNX Runtime threads per process, uses advisory file locks so only one process indexes a given project at a time, backs off under Linux memory pressure (PSI), and auto-shuts down idle servers after 30 minutes. Configure viaserve.idle_timeout_minutesandserve.max_ort_threads.
CCE's cross-session memory depends on the agent callingrecord_decisionandrecord_code_area. Memory nudges make recording ambient: after N searches without a recording,context_searchresults include a short reminder. At session end, the Stop hook summarizes unrecorded activity. Nudges re-arm after the first recording so they stay useful without being noisy.
cce serve --httpexposes aPOST /searchendpoint for custom agent integrations that speak HTTP instead of MCP stdio. Same hybrid retrieval pipeline, structured JSON response with confidence scores. Input validation clampstop_k(1..100) andconfidence_threshold(0.0..1.0).
7 buckets track every token saved: retrieval, chunk compression, output compression, memory recall, grammar, turn summarization, progressive disclosure. Survives restarts. Powers CLI and dashboard analytics.
cce init --plugin # Generate at .cce/plugin/ cce init --plugin --plugin-dir ~/plugins/cce # Custom location cce init --agent claude --plugin # Both: agent config + plugin
.cce/plugin/ ├── plugin.json # Agent Plugins v1.0.0 manifest ├── mcp.json # MCP server config (uvx + stdio) ├── skills/ │ └── code-context/ │ ├── SKILL.md # Agent instructions (frontmatter + body) │ └── references/ │ └── tools.md # Per-tool parameter docs (loaded on demand) └── LICENSE
VS Code, GitHub Copilot, ChatGPT, Codex, Cursor, and Kiro. The plugin usesuvxto launch CCE on demand, so users do not need to pre-install the Python package. The MCP server auto-discovers the project root by walking up from its working directory, looking for.context-engine.yamlor.git/.
Both can be used together.--agenthandles per-editor MCP config,--pluginprovides a portable alternative.
cce init # Index + install hooks + register MCP cce init --plugin # Generate Agent Plugin for VS Code, Cursor, etc. cce # Status banner cce savings # Token savings with dollar estimates cce savings --all # All projects cce dashboard # Web dashboard with live charts cce search "auth flow" # Test a query cce status # Index health + config cce services # Ollama + dashboard + MCP status cce commands add-rule '...' # Project rules for Claude cce uninstall # Clean removal of all CCE artifacts
Runcce listfor the full command reference.
Zero-config by default. Override what you need in~/.cce/config.yamlor.context-engine.yaml:
compression: level: standard # minimal | standard | full output: standard # off | lite | standard | max ollama_url: http://localhost:11434 # point at a remote Ollama if desired retrieval: top_k: 20 confidence_threshold: 0.5 pricing: model: opus # opus | sonnet | haiku | gpt-4o | gemini-2.5-pro | ... # input: 15.0 # override $/1M input tokens # output: 75.0 # override $/1M output tokens
Remote Ollama:If you run Ollama on another machine in your network, setcompression.ollama_url(e.g.http://nas.local:11434) or exportCCE_OLLAMA_URL(the env var wins). CCE probes the endpoint and falls back to truncation-only compression when it's unreachable, so a flaky link won't break indexing.
CCE also compresses Claude's responses (same concept as Caveman):
Tell Claude: "switch to max compression" or "turn off compression". Code blocks and commands are never compressed.
No GPU required. With Ollama, embeddings are handled by the Ollama server. With the[local]extra, the embedding model runs on CPU via ONNX Runtime.
AST-aware chunking (tree-sitter parsed, 11 extensions):
Language-aware fallback chunking (40+ extensions):
All other text files are chunked by line range. Binary files are skipped.
No. Quality stays the same or slightly improves.
CCE replaces "dump the entire file" with "search for the relevant function." The model still gets the code it needs (0.90 Recall@10 in benchmarks). Less irrelevant context means less noise competing for attention, which can improve the model's focus on your actual question.
CCE writes output compression rules directly into your agent's instruction files (CLAUDE.md,AGENTS.md,.cursorrules, etc.) duringcce init. These rules apply to theentire session, not just CCE tool responses, so every reply from the agent follows them.
Set the level in~/.cce/config.yamlor.context-engine.yaml:
compression: output: max # off | lite | standard | max
Then re-runcce initto update instruction files. Or change at runtime:
Default isstandard. All levels includecode output rulesthat tell the model to show only changed lines (not full file rewrites), which is where most output tokens go in coding sessions. Themaxlevel produces very terse prose (similar to "caveman mode"). Code blocks, paths, and commands are never compressed regardless of level.
Most savings areinput tokens(what goes into the model):
Output tokens cost 5x more per token (e.g. Opus: $15/1M input vs $75/1M output), so even a small output reduction has outsized cost impact.
- Multi-repo benchmarks (FastAPI, chi, fiber)
- More benchmarks (Django, Express)
- Tree-sitter support for C, C++, Ruby, Swift, Kotlin
- Docker support for remote mode
- Port to mcp 2.x API
Contributions welcome. Seehttps://github.com/elara-labs/code-context-engine/blob/main/CONTRIBUTING.mdfor setup.
Claude Code·MCP·sqlite-vec·Tree-sitter·fastembed·Ollama
If CCE saves you tokens, give it a star.
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
