Skip to content
Back to search

code-context-engine

Save 94% on AI coding tokens. Index your codebase, agents search instead of reading files. Works with Claude Code, Codex, Copilot, Cursor, Gemini CLI. Local MCP server, free, open source.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/elara-labs--code-context-engine/badge.svg)](/listings/elara-labs--code-context-engine)

HTML

<a href="/listings/elara-labs--code-context-engine"><img src="/api/listings/elara-labs--code-context-engine/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One command. 30 seconds.

uvx --from "code-context-engine[local]" cce init    # install + index + configure, one shot

Or if you prefer a persistent install:

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:** Run `cce init --plugin` to generate a portable > [Agent Plugin](https://agent-plugins.org) directory that works with > VS Code, Cursor, Copilot, Codex, ChatGPT, and Kiro. The plugin uses > `uvx` to launch CCE on demand, so users don't need to pre-install the > Python package. See [Agent Plugin](#agent-plugin) below.

> **Already have Ollama?** Skip `[local]` and use `uv tool install code-context-engine` instead. CCE auto-detects Ollama at localhost:11434 and uses `nomic-embed-text`.

<details> <summary><strong>System requirements</strong></summary>

Python 3.11+ and a C compiler (for tree-sitter grammars).

| Platform | Setup | |----------|-------| | **macOS** | `xcode-select --install` | | **Ubuntu/Debian** | `sudo apt install build-essential cmake` | | **Fedora/RHEL** | `sudo dnf install gcc gcc-c++ cmake` | | **Windows** | [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (C++ workload) + [CMake](https://cmake.org/download/) |

Tested on macOS, Linux, Windows with Python 3.11/3.12/3.13. </details>

`cce init` auto-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`.

| Editor | Config written | Instructions | |--------|---------------|--------------| | Claude Code | `.mcp.json` | `CLAUDE.md` | | VS Code / Copilot | `.vscode/mcp.json` | `.github/copilot-instructions.md` | | Cursor | `.cursor/mcp.json` | `.cursorrules` | | Gemini CLI | `.gemini/settings.json` | `GEMINI.md` | | OpenAI Codex | `~/.codex/config.toml` (user-global, per-project section) | `AGENTS.md` | | OpenCode | `opencode.json` | | | Tabnine | `.tabnine/agent/settings.json` | `TABNINE.md` | | Pi | `.mcp.json` | `AGENTS.md` |

Multiple editors in the same project? All get configured in one command.

**Codex note:** Codex CLI reads MCP servers from `~/.codex/config.toml` only — it has no per-project config. `cce init` adds one `[mcp_servers.cce-<project>-<hash>]` section per project so multiple projects coexist; `cce uninstall` removes 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](https://github.com/nicobailon/pi-mcp-adapter)) that consumes the `.mcp.json` config and exposes CCE's tools to the Pi agent. `cce init` sets up both `.mcp.json` and `AGENTS.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 via `pricing.model` in `~/.cce/config.yaml`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 613 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/elara-labs/code-context-engine/main/docs/logo.svg" alt="Code Context Engine" width="140">
  3. </p>
  4. <h1 align="center">Code Context Engine</h1>
  5. <p align="center">
  6. <strong>Index your codebase. AI searches instead of re-reading files.<br>94% token savings, reproducibly benchmarked.</strong>
  7. </p>
  8. <p align="center">
  9. <a href="https://elara-labs.github.io/code-context-engine/">Website</a> · <a href="https://elara-labs.github.io/code-context-engine/guide/">Docs</a> · <a href="https://elara-labs.github.io/code-context-engine/guide/why-cce/">Why CCE?</a> · <a href="https://elara-labs.github.io/code-context-engine/blog/benchmark-fastapi.html">Benchmark</a> · <a href="https://github.com/elara-labs/code-context-engine">GitHub</a>
  10. </p>
  11. <br>
  12. <p align="center">
  13. <a href="https://pypi.org/project/code-context-engine/"><img src="https://img.shields.io/pypi/v/code-context-engine?style=flat-square&color=blue&label=PyPI" alt="PyPI"></a>
  14. <a href="https://pepy.tech/project/code-context-engine"><img src="https://img.shields.io/pepy/dt/code-context-engine?style=flat-square&label=downloads&color=blue" alt="Downloads"></a>
  15. <a href="https://github.com/elara-labs/code-context-engine/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/elara-labs/code-context-engine/ci.yml?style=flat-square&label=CI" alt="CI"></a>
  16. <a href="https://registry.modelcontextprotocol.io/?q=code-context-engine"><img src="https://img.shields.io/badge/MCP_Registry-listed-brightgreen?style=flat-square" alt="MCP Registry"></a>
  17. <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" alt="MIT License"></a>
  18. <a href="https://github.com/elara-labs/code-context-engine"><img src="https://img.shields.io/github/stars/elara-labs/code-context-engine?style=flat-square&label=stars" alt="Stars"></a>
  19. </p>
  20. <p align="center">
  21. <sub>Python 3.11+ · macOS · Linux · Windows</sub>
  22. </p>
  23. <br>
  24. <p align="center">
  25. <a href="#install-and-see-savings-in-60-seconds"><img src="https://img.shields.io/badge/Claude_Code-352318?style=for-the-badge&logo=anthropic&logoColor=D4A27F" alt="Claude Code"></a>&nbsp;
  26. <a href="#install-and-see-savings-in-60-seconds"><img src="https://img.shields.io/badge/VS_Code-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white" alt="VS Code"></a>&nbsp;
  27. <a href="#install-and-see-savings-in-60-seconds"><img src="https://img.shields.io/badge/Cursor-000?style=for-the-badge" alt="Cursor"></a>&nbsp;
  28. <a href="#install-and-see-savings-in-60-seconds"><img src="https://img.shields.io/badge/Gemini_CLI-4285F4?style=for-the-badge&logo=google&logoColor=white" alt="Gemini CLI"></a>&nbsp;
  29. <a href="#install-and-see-savings-in-60-seconds"><img src="https://img.shields.io/badge/Codex_CLI-412991?style=for-the-badge" alt="Codex CLI"></a>&nbsp;
  30. <a href="#install-and-see-savings-in-60-seconds"><img src="https://img.shields.io/badge/OpenCode-22C55E?style=for-the-badge&logo=gnometerminal&logoColor=white" alt="OpenCode"></a>&nbsp;
  31. <a href="#install-and-see-savings-in-60-seconds"><img src="https://img.shields.io/badge/Tabnine-4B32C3?style=for-the-badge&logo=tabnine&logoColor=white" alt="Tabnine"></a>&nbsp;
  32. <a href="#install-and-see-savings-in-60-seconds"><img src="https://img.shields.io/badge/Pi-000?style=for-the-badge" alt="Pi"></a>
  33. </p>
  34. <p align="center">
  35. <sub>One command. Auto-detects your editor. Zero cloud, zero config.</sub>
  36. </p>
  37. <br>
  38. <p align="center">
  39. <img src="https://raw.githubusercontent.com/elara-labs/code-context-engine/main/docs/demo.gif" alt="CCE Demo" width="720">
  40. </p>
  41. <p align="center">
  42. <a href="https://www.youtube.com/watch?v=dRmWYHuIJxM">
  43. <img src="https://img.youtube.com/vi/dRmWYHuIJxM/maxresdefault.jpg" alt="Talk: We Cut 94% of Our AI Coding Tokens — AI Engineer World's Fair 2026" width="560">
  44. </a><br>
  45. <sub><strong>Talk:</strong> <a href="https://www.youtube.com/watch?v=dRmWYHuIJxM">We Cut 94% of Our AI Coding Tokens</a> — AI Engineer World's Fair 2026</sub>
  46. </p>
  47. ---
  48. ## Use cases
  49. | | Use case | How CCE helps |
  50. |---|---|---|
  51. | **💰** | **Reduce Claude Code costs** | 94% fewer input tokens per session |
  52. | **🔒** | **Keep code private** | Everything local, no cloud indexing |
  53. | **🔄** | **Multi-editor teams** | One index across Claude Code, Cursor, VS Code, Gemini CLI |
  54. | **🧠** | **Cross-session memory** | Decisions and context survive restarts |
  55. | **⚡** | **Faster responses** | Less context = faster Claude replies |
  56. | **📊** | **Track actual savings** | Dollar amounts, not estimates |
  57. ---
  58. ## Quick start
  59. One command. 30 seconds.
  60. ```bash
  61. uvx --from "code-context-engine[local]" cce init # install + index + configure, one shot
  62. ```
  63. Or if you prefer a persistent install:
  64. ```bash
  65. uv tool install "code-context-engine[local]" # or: pipx install "code-context-engine[local]"
  66. cd /path/to/your/project
  67. cce init
  68. ```
  69. Restart your editor. Done. Every question now hits the index instead of re-reading files.
  70. > **Agent Plugin support:** Run `cce init --plugin` to generate a portable
  71. > [Agent Plugin](https://agent-plugins.org) directory that works with
  72. > VS Code, Cursor, Copilot, Codex, ChatGPT, and Kiro. The plugin uses
  73. > `uvx` to launch CCE on demand, so users don't need to pre-install the
  74. > Python package. See [Agent Plugin](#agent-plugin) below.
  75. > **Already have Ollama?** Skip `[local]` and use `uv tool install code-context-engine` instead. CCE auto-detects Ollama at localhost:11434 and uses `nomic-embed-text`.
  76. <details>
  77. <summary><strong>System requirements</strong></summary>
  78. Python 3.11+ and a C compiler (for tree-sitter grammars).
  79. | Platform | Setup |
  80. |----------|-------|
  81. | **macOS** | `xcode-select --install` |
  82. | **Ubuntu/Debian** | `sudo apt install build-essential cmake` |
  83. | **Fedora/RHEL** | `sudo dnf install gcc gcc-c++ cmake` |
  84. | **Windows** | [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (C++ workload) + [CMake](https://cmake.org/download/) |
  85. Tested on macOS, Linux, Windows with Python 3.11/3.12/3.13.
  86. </details>
  87. `cce init` auto-detects your editor and writes the right config. To target a
  88. specific agent, use `--agent claude`, `--agent codex`, `--agent copilot`, `--agent pi`, or
  89. `--agent all`.
  90. | Editor | Config written | Instructions |
  91. |--------|---------------|--------------|
  92. | Claude Code | `.mcp.json` | `CLAUDE.md` |
  93. | VS Code / Copilot | `.vscode/mcp.json` | `.github/copilot-instructions.md` |
  94. | Cursor | `.cursor/mcp.json` | `.cursorrules` |
  95. | Gemini CLI | `.gemini/settings.json` | `GEMINI.md` |
  96. | OpenAI Codex | `~/.codex/config.toml` (user-global, per-project section) | `AGENTS.md` |
  97. | OpenCode | `opencode.json` | |
  98. | Tabnine | `.tabnine/agent/settings.json` | `TABNINE.md` |
  99. | Pi | `.mcp.json` | `AGENTS.md` |
  100. Multiple editors in the same project? All get configured in one command.
  101. **Codex note:** Codex CLI reads MCP servers from `~/.codex/config.toml` only —
  102. it has no per-project config. `cce init` adds one `[mcp_servers.cce-<project>-<hash>]`
  103. section per project so multiple projects coexist; `cce uninstall` removes only
  104. the section for the current project.
  105. **Pi note:** Pi does not support MCP natively. To use CCE with Pi, you need a
  106. pi MCP adapter extension (e.g. [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter))
  107. that consumes the `.mcp.json` config and exposes CCE's tools to the Pi agent.
  108. `cce init` sets up both `.mcp.json` and `AGENTS.md` (Pi loads the latter
  109. automatically for startup instructions).
  110. ```
  111. my-project · 38 queries · last query 5m ago
  112. ⛁ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ 88% tokens saved
  113. Input savings 1.9M tokens $27.78
  114. Output savings 4.8k tokens $0.36
  115. ──────────────────────────────────────────
  116. Total saved 1.9M tokens $28.15
  117. Breakdown:
  118. retrieval 84% ▰▰▰▰▰▰▰▰▰▰ 1.8M $26.76 · 12 calls
  119. chunk compression 3% ▰▱▱▱▱▱▱▱▱▱ 68.5k $1.03 · 12 calls
  120. output compression* <1% ▰▱▱▱▱▱▱▱▱▱ 4.8k $0.36 · 12 calls
  121. Cost estimate based on Opus pricing (input $15.0/1M, output $75.0/1M)
  122. ```
  123. Supports Anthropic, OpenAI, and Google model pricing. Configure via `pricing.model` in `~/.cce/config.yaml`.
  124. ---
  125. ## Why this matters
  126. Input tokens are 85-95% of your Claude Code bill. CCE cuts them by 94% ([benchmarked on FastAPI](#benchmark-fastapi-reproducible)).
  127. ```
  128. Without CCE: Claude reads payments.py + shipping.py = 45,000 tokens
  129. With CCE: context_search "payment flow" = 800 tokens
  130. ```
  131. | | Without CCE | With CCE |
  132. |---|---|---|
  133. | Session startup | Re-reads files every time | Queries the index |
  134. | Finding a function | Read entire 800-line file | Get the 40-line function |
  135. | Cross-session memory | None | Decisions + code areas persisted |
  136. | Token cost (Sonnet, medium project) | ~$0.14/session | ~$0.04/session |
  137. ---
  138. ## Benchmark: FastAPI (reproducible)
  139. We benchmarked CCE against [FastAPI](https://github.com/fastapi/fastapi) (53 source files, 180K tokens) with 20 real coding questions. No cherry-picking, no synthetic queries.
  140. **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.
  141. **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.
  142. | Metric | Result |
  143. |--------|--------|
  144. | **Retrieval savings** | **94%** (83,681 → 4,927 tokens/query) |
  145. | Compression (additional, on retrieved chunks) | 89% (4,927 → 523 tokens/query) |
  146. | Recall@10 (found the right files) | 0.90 |
  147. | Latency p50 | 0.4ms |
  148. | Queries tested | 20 |
  149. ### Per-Layer Savings (each measured independently)
  150. | Layer | What it does | Savings | Method |
  151. |-------|-------------|---------|--------|
  152. | **Retrieval** | Full files → relevant code chunks | 94% | measured |
  153. | **Chunk Compression** | Raw chunks → signatures + docstrings | 89% | measured |
  154. | **Grammar** | Drops articles/fillers from memory text | 13% | measured |
  155. Output compression (reducing Claude's reply length) provides additional savings (~65% estimated) but is not included in the headline number above.
  156. ### Multi-language benchmarks
  157. | Repo | Language | Files | Retrieval savings | Recall@10 |
  158. |------|----------|-------|-------------------|-----------|
  159. | [FastAPI](benchmarks/results/fastapi.md) | Python | 53 | **94%** | 0.90 |
  160. | [Django](benchmarks/results/django.md) | Python (large) | 2,347 | **93%** | 0.95 |
  161. | [Express](benchmarks/results/express.md) | JavaScript | 6 | **94%** | 1.00 |
  162. | [chi](benchmarks/results/chi.md) | Go | 94 | **76%** | 0.67 |
  163. | [fiber](benchmarks/results/fiber.md) | Go (monorepo) | 396 | **93%** | 0.07 |
  164. 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.
  165. **Reproduce it yourself:**
  166. ```bash
  167. pip install code-context-engine
  168. python benchmarks/run_benchmark.py --repo https://github.com/fastapi/fastapi.git --source-dir fastapi
  169. python benchmarks/run_benchmark.py --repo https://github.com/go-chi/chi.git --source-dir .
  170. ```
  171. Full results in [`benchmarks/results/`](benchmarks/results/). Queries and methodology in [`benchmarks/`](benchmarks/).
  172. ---
  173. ## What you get
  174. **11 MCP tools** that Claude uses automatically:
  175. | Tool | What it does |
  176. |------|-------------|
  177. | `context_search` | Hybrid vector + BM25 search with graph expansion |
  178. | `expand_chunk` | Full source for a compressed result |
  179. | `related_context` | Find code via graph edges (calls, imports) |
  180. | `session_recall` | Recall decisions from past sessions |
  181. | `session_timeline` | Walk turn summaries for a session (drill into recall hits) |
  182. | `session_event` | Inspect raw tool input/output for a specific event |
  183. | `record_decision` | Save a decision for future sessions |
  184. | `record_code_area` | Record which files were worked in |
  185. | `index_status` | Check index freshness |
  186. | `reindex` | Re-index a file or the full project |
  187. | `set_output_compression` | Adjust response verbosity (`off` / `lite` / `standard` / `max`) |
  188. **Live dashboard** with donut charts, file health, and session history:
  189. ```bash
  190. cce dashboard
  191. ```
  192. ![CCE Dashboard](https://raw.githubusercontent.com/elara-labs/code-context-engine/main/docs/dashboard.png)
  193. **Dollar estimates** with multi-provider pricing (Anthropic, OpenAI, Google):
  194. ```bash
  195. cce savings --all # see savings across all projects
  196. ```
  197. ---
  198. ## How it works
  199. 1. **Index:** Tree-sitter parses your code into semantic chunks (functions, classes, modules). Stored as vector embeddings locally.
  200. 2. **Search:** Claude calls `context_search`. Hybrid vector + BM25 retrieval finds the right chunks. Code graph adds related files automatically.
  201. 3. **Compress:** Chunks are truncated to signatures + docstrings (or LLM-summarized if Ollama is running).
  202. 4. **Remember:** Decisions and code areas persist across sessions via `session_recall`.
  203. 5. **Track:** Every query is logged. `cce savings` shows exactly how much you saved.
  204. Re-indexing after edits takes under 1 second (96% embedding cache hit rate). Git hooks keep the index current automatically.
  205. ---
  206. ## What makes CCE different
  207. ### It saves where the money is
  208. Output compression tools (like Caveman) save 20-75% on output tokens. Output is 5-15% of your bill. Net savings: ~11%.
  209. CCE saves on **input** tokens (94% retrieval savings on FastAPI, [reproducibly benchmarked](#benchmark-fastapi-reproducible)). Input is 85-95% of your bill.
  210. ### It actually understands your code
  211. 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.
  212. ### It remembers
  213. `record_decision("use JWT for auth", reason="session tokens flagged by legal")` is stored in SQLite and surfaces via `session_recall` in the next session. No re-explaining your architecture.
  214. ### It tracks real savings
  215. 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.
  216. ### It is secure by default
  217. 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.
  218. ---
  219. ## Under the hood
  220. <details>
  221. <summary><strong>Content-Hash Embedding Cache</strong></summary>
  222. 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.
  223. </details>
  224. <details>
  225. <summary><strong>sqlite-vec: 2 MB instead of 217 MB</strong></summary>
  226. 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.
  227. </details>
  228. <details>
  229. <summary><strong>Deterministic Grammar Compression</strong></summary>
  230. 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.
  231. </details>
  232. <details>
  233. <summary><strong>Fail-Closed Hook Design</strong></summary>
  234. 5 Claude Code lifecycle hooks capture session context. Every hook runs `curl ... || true`, so a crashed server never blocks the user. SessionStart injects bootstrap context; others capture silently.
  235. </details>
  236. <details>
  237. <summary><strong>Multi-Provider Pricing</strong></summary>
  238. Dollar estimates in `cce savings` support 15+ models across Anthropic, OpenAI, and Google. Static pricing ships with CCE, live Anthropic pricing is fetched and cached 7 days. Configure `pricing.model` (e.g. `gpt-4o`, `gemini-2.5-pro`, `sonnet`) or override with `pricing.input` / `pricing.output` for custom rates.
  239. </details>
  240. <details>
  241. <summary><strong>Resource Governor (Multi-Instance Safety)</strong></summary>
  242. Running dozens of `cce serve` processes (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 via `serve.idle_timeout_minutes` and `serve.max_ort_threads`.
  243. </details>
  244. <details>
  245. <summary><strong>Memory Nudges</strong></summary>
  246. CCE's cross-session memory depends on the agent calling `record_decision` and `record_code_area`. Memory nudges make recording ambient: after N searches without a recording, `context_search` results 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.
  247. </details>
  248. <details>
  249. <summary><strong>HTTP Search Endpoint</strong></summary>
  250. `cce serve --http` exposes a `POST /search` endpoint for custom agent integrations that speak HTTP instead of MCP stdio. Same hybrid retrieval pipeline, structured JSON response with confidence scores. Input validation clamps `top_k` (1..100) and `confidence_threshold` (0.0..1.0).
  251. </details>
  252. <details>
  253. <summary><strong>Append-Only Savings Ledger</strong></summary>
  254. 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.
  255. </details>
  256. ---
  257. ## Agent Plugin
  258. [Agent Plugins](https://agent-plugins.org) is an open standard (v1.0.0) backed by Amazon, Cursor, Microsoft, OpenAI, and Vercel for packaging AI skills and MCP servers into portable, zero-install bundles. CCE can generate a plugin directory that compatible editors can discover and load automatically.
  259. ```bash
  260. cce init --plugin # Generate at .cce/plugin/
  261. cce init --plugin --plugin-dir ~/plugins/cce # Custom location
  262. cce init --agent claude --plugin # Both: agent config + plugin
  263. ```
  264. ### What gets generated
  265. ```
  266. .cce/plugin/
  267. ├── plugin.json # Agent Plugins v1.0.0 manifest
  268. ├── mcp.json # MCP server config (uvx + stdio)
  269. ├── skills/
  270. │ └── code-context/
  271. │ ├── SKILL.md # Agent instructions (frontmatter + body)
  272. │ └── references/
  273. │ └── tools.md # Per-tool parameter docs (loaded on demand)
  274. └── LICENSE
  275. ```
  276. ### Compatible editors
  277. VS Code, GitHub Copilot, ChatGPT, Codex, Cursor, and Kiro. The plugin uses `uvx` to 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.yaml` or `.git/`.
  278. ### When to use `--plugin` vs `--agent`
  279. | | `--agent` (default) | `--plugin` |
  280. |---|---|---|
  281. | Install method | Writes editor-specific config files | Generates a portable plugin directory |
  282. | Zero-install | No, CCE must be on PATH | Yes, `uvx` fetches CCE on demand |
  283. | Instruction updates | Stale until `cce init` re-run | Stale until `cce init --plugin` re-run |
  284. | Best for | Your own machine | Sharing with a team or distributing |
  285. Both can be used together. `--agent` handles per-editor MCP config, `--plugin` provides a portable alternative.
  286. ---
  287. ## CLI at a glance
  288. ```bash
  289. cce init # Index + install hooks + register MCP
  290. cce init --plugin # Generate Agent Plugin for VS Code, Cursor, etc.
  291. cce # Status banner
  292. cce savings # Token savings with dollar estimates
  293. cce savings --all # All projects
  294. cce dashboard # Web dashboard with live charts
  295. cce search "auth flow" # Test a query
  296. cce status # Index health + config
  297. cce services # Ollama + dashboard + MCP status
  298. cce commands add-rule '...' # Project rules for Claude
  299. cce uninstall # Clean removal of all CCE artifacts
  300. ```
  301. Run `cce list` for the full command reference.
  302. ---
  303. ## Configuration
  304. Zero-config by default. Override what you need in `~/.cce/config.yaml` or `.context-engine.yaml`:
  305. ```yaml
  306. compression:
  307. level: standard # minimal | standard | full
  308. output: standard # off | lite | standard | max
  309. ollama_url: http://localhost:11434 # point at a remote Ollama if desired
  310. retrieval:
  311. top_k: 20
  312. confidence_threshold: 0.5
  313. pricing:
  314. model: opus # opus | sonnet | haiku | gpt-4o | gemini-2.5-pro | ...
  315. # input: 15.0 # override $/1M input tokens
  316. # output: 75.0 # override $/1M output tokens
  317. ```
  318. **Remote Ollama:** If you run Ollama on another machine in your network, set `compression.ollama_url` (e.g. `http://nas.local:11434`) or export `CCE_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.
  319. ---
  320. ## Output Compression
  321. CCE also compresses Claude's responses (same concept as Caveman):
  322. | Level | Style | Savings |
  323. |-------|-------|---------|
  324. | `off` | Full output | 0% |
  325. | `lite` | No filler or hedging | ~30% |
  326. | `standard` | Fragments, drop articles | ~65% |
  327. | `max` | Telegraphic | ~75% |
  328. Tell Claude: "switch to max compression" or "turn off compression". Code blocks and commands are never compressed.
  329. ---
  330. ## Disk Footprint
  331. | Component | Size |
  332. |-----------|------|
  333. | Core install (Ollama backend) | ~17 MB |
  334. | With `[local]` extra (fastembed + ONNX) | ~189 MB |
  335. | Embedding model (one-time download) | ~60 MB (fastembed) or managed by Ollama |
  336. | Index per project (small/medium/large) | 5-60 MB |
  337. 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.
  338. ---
  339. ## Supported Languages
  340. **AST-aware chunking (tree-sitter parsed, 11 extensions):**
  341. | Language | Extensions |
  342. |----------|-----------|
  343. | Python | `.py` |
  344. | JavaScript | `.js`, `.jsx` |
  345. | TypeScript | `.ts`, `.tsx` |
  346. | PHP | `.php` |
  347. | Go | `.go` |
  348. | Rust | `.rs` |
  349. | Java | `.java` |
  350. | C# | `.cs` |
  351. **Language-aware fallback chunking (40+ extensions):**
  352. | Category | Languages |
  353. |----------|-----------|
  354. | Web | HTML, CSS, SCSS, LESS, Vue, Svelte |
  355. | Systems | C, C++, Zig, Nim |
  356. | Mobile | Swift, Kotlin, Dart |
  357. | Functional | Haskell, Scala, Clojure, Elixir, Erlang, F# |
  358. | Scripting | Ruby, Perl, Lua, R, Bash/Zsh |
  359. | Data/Config | JSON, YAML, TOML, XML, SQL, GraphQL, Protobuf |
  360. | DevOps | Terraform, HCL, Dockerfile |
  361. | Docs | Markdown |
  362. All other text files are chunked by line range. Binary files are skipped.
  363. ---
  364. ## Documentation
  365. | Page | Content |
  366. |------|---------|
  367. | [How Much Are You Spending on AI Coding Tokens?](https://elara-labs.github.io/code-context-engine/blog/real-cost-of-ai-coding-tokens.html) | The math on input vs output tokens |
  368. | [What is CCE? (Complete Guide)](https://elara-labs.github.io/code-context-engine/blog/what-is-code-context-engine.html) | Setup, tools, how it works, FAQ |
  369. | [How to Save Claude Code Tokens](https://elara-labs.github.io/code-context-engine/blog/save-claude-code-tokens.html) | Cost breakdown and savings guide |
  370. | [Benchmark Deep Dive](https://elara-labs.github.io/code-context-engine/blog/benchmark-fastapi.html) | Full FastAPI benchmark methodology |
  371. | [Comparison with Alternatives](https://elara-labs.github.io/code-context-engine/comparison.html) | CCE vs Cursor, Aider, Continue, Greptile |
  372. | [Examples](https://github.com/elara-labs/code-context-engine/blob/main/docs/wiki/Examples.md) | Real conversations with Claude |
  373. | [How It Works](https://github.com/elara-labs/code-context-engine/blob/main/docs/wiki/How-It-Works.md) | Full 9-stage pipeline |
  374. | [CLI Reference](https://github.com/elara-labs/code-context-engine/blob/main/docs/wiki/CLI-Reference.md) | Every command with output |
  375. | [Configuration](https://github.com/elara-labs/code-context-engine/blob/main/docs/wiki/Configuration.md) | All config options |
  376. ---
  377. ## FAQ
  378. ### Does CCE affect response quality?
  379. No. Quality stays the same or slightly improves.
  380. 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.
  381. ### How does output token savings work?
  382. CCE writes output compression rules directly into your agent's instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.) during `cce init`. These rules apply to the **entire session**, not just CCE tool responses, so every reply from the agent follows them.
  383. Set the level in `~/.cce/config.yaml` or `.context-engine.yaml`:
  384. ```yaml
  385. compression:
  386. output: max # off | lite | standard | max
  387. ```
  388. Then re-run `cce init` to update instruction files. Or change at runtime:
  389. ```
  390. set_output_level output_level=max
  391. ```
  392. | Level | Savings | What it does |
  393. |-------|---------|--------------|
  394. | `off` | 0% | No compression |
  395. | `lite` | ~25% | Removes filler/hedging/pleasantries + diff-only for code changes |
  396. | `standard` | ~70% | Drops articles, fragments, short synonyms + diff-only for code |
  397. | `max` | ~80% | Telegraphic style + diff-only for code |
  398. Default is `standard`. All levels include **code output rules** that tell the model to show only changed lines (not full file rewrites), which is where most output tokens go in coding sessions. The `max` level produces very terse prose (similar to "caveman mode"). Code blocks, paths, and commands are never compressed regardless of level.
  399. ### Where do the savings come from?
  400. Most savings are **input tokens** (what goes into the model):
  401. | Layer | Type | Typical savings |
  402. |-------|------|-----------------|
  403. | Retrieval | Input | 94% (full files → relevant chunks) |
  404. | Chunk compression | Input | 89% (chunks → signatures) |
  405. | Grammar compression | Input | 13% (article/filler removal) |
  406. | Turn summarization | Input | varies (session history) |
  407. | Progressive disclosure | Input | varies (tool payloads) |
  408. | Output compression | Output | 25-80% (depends on level) |
  409. 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.
  410. ---
  411. ## Roadmap
  412. - [x] Multi-repo benchmarks (FastAPI, chi, fiber)
  413. - [x] More benchmarks (Django, Express)
  414. - [ ] Tree-sitter support for C, C++, Ruby, Swift, Kotlin
  415. - [ ] Docker support for remote mode
  416. - [ ] Port to mcp 2.x API
  417. See [CHANGELOG.md](CHANGELOG.md) for shipped features.
  418. ---
  419. ## Contributing
  420. Contributions welcome. See [https://github.com/elara-labs/code-context-engine/blob/main/CONTRIBUTING.md](https://github.com/elara-labs/code-context-engine/blob/main/CONTRIBUTING.md) for setup.
  421. ---
  422. ## License
  423. MIT. See [LICENSE](LICENSE).
  424. ## Authors
  425. - [Fazle Elahee](https://github.com/fazleelahhee)
  426. - [Raj](https://github.com/rajkumarsakthivel)
  427. ## Acknowledgments
  428. [Claude Code](https://docs.anthropic.com/en/docs/claude-code) · [MCP](https://modelcontextprotocol.io) · [sqlite-vec](https://github.com/asg017/sqlite-vec) · [Tree-sitter](https://tree-sitter.github.io/) · [fastembed](https://github.com/qdrant/fastembed) · [Ollama](https://ollama.com/)
  429. ---
  430. <p align="center">
  431. <strong>If CCE saves you tokens, give it a star.</strong>
  432. </p>
  433. <!-- mcp-name: io.github.ai-elara/code-context-engine -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.