code-context-engine: A Local MCP Index That Lets AI Agents Search Your Codebase Instead of Reading It

The problem code-context-engine targets: agents re-reading files they already saw

An agent working on a codebase spends most of its input budget on file contents. When Claude Code or Codex needs to answer a question about where a function is defined, it opens files, reads them, and puts them in the context window. The same files get read again in the next session, and again after a restart. The cost is proportional to how much source the agent touches, not to how much of it is relevant.

code-context-engine, abbreviated CCE throughout the README, takes the position that the agent should query an index instead. The README frames the pitch as "Index your codebase. AI searches instead of re-reading files." The audience is specific: developers running one or more of Claude Code, VS Code with Copilot, Cursor, Gemini CLI, OpenAI Codex, OpenCode, Tabnine or Pi, who care about input token spend and about not shipping source to a hosted indexing service. The README lists "Keep code private" as a use case and states that everything runs locally with no cloud indexing.

The secondary claim is cross-session memory. The README says decisions and context survive restarts, which matters if your agent loses the thread of a design discussion every time you close the terminal. That is a different benefit from token savings, and the README treats both as reasons to install.

How the local MCP server answers a query: tree-sitter parsing plus sqlite-vec retrieval

CCE is a Python package that runs as a Model Context Protocol server on your machine. The dependency list in pyproject.toml shows the two halves of the mechanism. Parsing is handled by tree-sitter and a set of per-language grammar packages: tree-sitter-python, tree-sitter-javascript, tree-sitter-typescript, tree-sitter-php, tree-sitter-go, and others truncated in the file. Storage and retrieval use sqlite-vec, a SQLite extension for vector search, with numpy for the embedding math.

The data flow the README implies is: `cce init` walks the project, parses each source file into syntax nodes with tree-sitter, embeds those chunks, and writes them into a SQLite database with vector indexing. Your editor's agent then connects to the MCP server and issues search calls instead of file reads. The README does not document the tool names the server exposes, the chunking strategy, or the database location, so anyone evaluating this should read the source under src/ rather than assume a particular retrieval design.

Embeddings come from one of two places. The `[local]` extra pulls in a local embedding model. If you already run Ollama, the README says CCE auto-detects it at localhost:11434 and uses nomic-embed-text. That second path matters because it lets you avoid a second model download if Ollama is already part of your setup.

Installing code-context-engine and running cce init on a real project

The README gives a one-shot command using uvx, which installs and runs without a persistent tool install. Note the `[local]` extra: it selects the bundled local embedding model rather than relying on Ollama.

uvx --from "code-context-engine[local]" cce init

If you would rather keep the tool installed, the README offers a persistent variant. Either uv or pipx works.

uv tool install "code-context-engine[local]"
cd /path/to/your/project
cce init

After `cce init` finishes, restart your editor. The README's claim is that every subsequent question hits the index instead of re-reading files. You should see the config file for your editor appear in the project tree, and the README's table maps each editor to what gets written: Claude Code gets `.mcp.json` plus `CLAUDE.md`, VS Code and Copilot get `.vscode/mcp.json` plus `.github/copilot-instructions.md`, Cursor gets `.cursor/mcp.json` plus `.cursorrules`, Gemini CLI gets `.gemini/settings.json` plus `GEMINI.md`, and OpenAI Codex gets a per-project section inside the user-global `~/.codex/config.toml` plus `AGENTS.md`. OpenCode writes `opencode.json`, Tabnine writes `.tabnine/agent/settings.json` and `TABNINE.md`, and Pi writes `.mcp.json` and `AGENTS.md`.

To target one agent instead of letting detection decide, the README documents `--agent claude`, `--agent codex`, `--agent copilot`, `--agent pi`, and `--agent all`. There is also a plugin path that avoids requiring the Python package on each machine:

cce init --plugin

The README says this generates an Agent Plugin directory that works with VS Code, Cursor, Copilot, Codex, ChatGPT and Kiro, and that the plugin launches CCE through uvx on demand. That is the variant to consider for a team where you do not want every developer to install Python tooling first.

One prerequisite is easy to miss: tree-sitter grammars need a C compiler. The README lists `xcode-select --install` on macOS, `build-essential` and `cmake` on Ubuntu and Debian, `gcc`, `gcc-c++` and `cmake` on Fedora and RHEL, and Visual Studio Build Tools with the C++ workload plus CMake on Windows. Python 3.11 or newer is required.

The tree-sitter version cap, and why cce init can crash without it

The most informative thing in pyproject.toml is a comment above the tree-sitter dependency. CCE pins `tree-sitter>=0.22,<0.26` and the comment explains why: the 0.26 core changed the Node and Point ABI, while the tree-sitter grammar wheels are still built against the 0.25.x ABI. Mixing a 0.26 core with 0.25 grammars corrupts memory when reading Node.start_point or end_point, crashing `cce init` with SIGSEGV or SIGBUS. The comment cites issues #113 and #114.

Two things follow. First, if you install CCE into an environment that already has tree-sitter 0.26 or later, you are in the failure mode the maintainers documented, and the crash happens during indexing rather than at import time, which makes it look like a project-specific problem. Second, the comment notes that `uv tool install` resolves dependencies fresh from PyPI and ignores uv.lock, so the cap has to live in the dependency declaration itself. An installer that ignores the lockfile will still respect the pin.

The cap is a real constraint, not a temporary annoyance you can route around by upgrading. The comment states the cap should be lifted only when all grammar packages ship 0.26-ABI releases. Until then, a project that pins tree-sitter 0.26 for its own reasons will conflict with CCE.

Where code-context-engine is the wrong tool

The 94% figure comes from a benchmark the project publishes and links from its own README, run against FastAPI. It is a vendor benchmark on one repository, and the README does not present it as a general constant. Treat it as a starting hypothesis about your own codebase, not a promise. Token savings depend on how much of your work is question-answering over existing code versus writing new code, and on how large the files are that the agent would otherwise read.

The Beta classifier is explicit in pyproject.toml: `Development Status :: 4 - Beta`. Version numbers are in the 0.4.x line, with v0.4.26 released on 2026-08-12. The last push to the default branch was on 2026-08-23, so the project is being worked on, but a 0.x version series means the interface can change between releases. If you are wiring CCE into a shared developer image or a CI pipeline, pin the version.

Small projects are the clearest case against it. If your repository is a few hundred lines across a handful of files, the agent's file reads are already cheap, and you have added a Python install, a C compiler requirement, a local embedding model, and an index that goes stale as you edit. The README does not describe how the index is refreshed after a commit, which is the operational question that decides whether this is a convenience or a source of wrong answers. For a monorepo with a build system that already produces a symbol graph, you may get better results from that graph than from a fresh embedding index.

Privacy is a genuine advantage here, but it is also a constraint: the README states there is no cloud indexing, so the embedding quality is whatever your local model or Ollama's nomic-embed-text provides. You are not trading up to a hosted embedding service.

How CCE differs from a hosted code-context service

The obvious comparison is a hosted code intelligence service that indexes your repository on its own infrastructure and exposes retrieval through an API or an editor plugin. The architectural difference is where the index lives and what computes the embeddings. A hosted service can run a larger embedding model and a more expensive reranker, because it amortizes that cost across customers and does not care about your laptop's thermals. CCE runs everything locally: SQLite with sqlite-vec for storage and vector search, tree-sitter for parsing, and either a bundled local model or Ollama at localhost:11434.

That changes the failure modes. A hosted service fails when the network is down or the vendor changes its pricing. CCE fails when your local embedding model is too weak to rank the right chunk, or when the index is out of date relative to your working tree. It also changes the security review: with CCE there is no data processing agreement to negotiate, because the README says no source leaves the machine. If your organization cannot send source to a third party at all, that difference is the deciding factor, not the token numbers.

The second comparison is doing nothing and letting the agent read files. That is the correct baseline, and it is cheap to measure: run a session with CCE configured and one without, on the same task, and compare input token counts. The README's own benchmark page is the reference for how the project measures this; replicating it on your repository is the only way to know whether the 94% number applies to you.

Licence, maintenance and what an upgrade costs you

CCE is MIT licensed, per both the README badge and the `license = "MIT"` field in pyproject.toml. MIT is permissive: you can use it commercially, modify it, and redistribute it, provided the copyright notice and licence text travel with copies. The repository also carries CODE_OF_CONDUCT.md, CONTRIBUTING.md and SECURITY.md at the top level, which is a normal open source layout. Nothing here needs a lawyer for the common case, but if you fork and ship CCE inside a product, keep the LICENSE file intact.

The upgrade cost is dominated by the tree-sitter pin. Every time you bump CCE, your resolver has to satisfy `tree-sitter>=0.22,<0.26` alongside your other dependencies. If another tool in the same environment wants 0.26, you have a conflict that the maintainers have already explained is not cosmetic: the ABI mismatch crashes indexing. Expect the cap to be lifted only when the grammar packages catch up.

The release cadence visible in the repository is v0.4.24 on 2026-06-21, v0.4.25 on 2026-07-01, and v0.4.26 on 2026-08-12, with the last push on 2026-08-23. That is frequent enough that pinning a known-good version is worth the small effort. The README does not document a rollback procedure or an index format migration path, so before upgrading in a team setting, check CHANGELOG.md for whether the on-disk index needs rebuilding.

Editorial conclusion

Adopt code-context-engine if you run Claude Code, Cursor, Copilot, Gemini CLI or Codex on a repository large enough that repeated file reads dominate your input tokens, and you are comfortable running a Beta-stage Python package that compiles tree-sitter grammars locally. Do not adopt it if you need a stable 1.0 API, if your build environment cannot provide a C compiler, or if you cannot tolerate a package pinning tree-sitter below 0.26 for ABI reasons. Before rolling it out across a team, verify three things on your own repository: that `cce init` completes without a SIGSEGV on your platform and Python version, that the generated `.mcp.json` or editor-specific config matches the agent you actually use, and that the token reduction you observe in your own sessions resembles the 94% figure the README reports from its FastAPI benchmark rather than assuming it transfers.

Frequently asked questions

Official sources

1. elara-labs/code-context-engine on GitHub
2. License: MIT
3. Project website
4. README
5. Releases