Repo of the day: claude-context, your whole codebase as context for Claude Code

💡 What it is: your whole codebase as context

claude-context is a Model Context Protocol (MCP) plugin that adds semantic code search to Claude Code and other coding agents. In practice: you feed it your project once, it splits it into chunks, turns them into embeddings and stores them in a vector database. From then on, whenever the agent needs to understand the code, it queries the index in natural language and gets back only the relevant fragments.

The difference with the classic approach is stark. Without a tool like this, Claude Code discovers the codebase «by hand»: it opens files, reads folders, follows imports, and every read eats space in the context window. With claude-context that discovery work is done by an index: the agent stops browsing and starts searching. The project is open source under the MIT license and is shipped as an official npm package.

# adds claude-context as an MCP server
claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-your-key \
  -e MILVUS_ADDRESS=your-zilliz-endpoint \
  -e MILVUS_TOKEN=your-api-key \
  -- npx @zilliz/claude-context-mcp@latest

🧠 The problem: why big projects «burn» tokens

The context window is a finite, expensive resource. When you ask Claude Code to change a function in a large project, the agent first has to figure out where that function lives and how it connects to the rest: without an index, the only way is to read. The more files it reads, the more tokens it spends, and the more the context fills up with code that the final answer doesn't need.

This produces two annoying effects: sessions that cost more than necessary and less precise answers, because the model gets distracted by irrelevant files loaded «just in case». On codebases with millions of lines the brute-force approach simply doesn't scale. claude-context flips the logic: index once, then on every question retrieve only the bare minimum.

⚙️ How it works under the hood

The core is a hybrid search: claude-context combines BM25 (keyword search, great when you know the exact name) with dense embedding search (which finds code by meaning, even when you use different words than the source). Together they retrieve better than either one alone.

Upstream there's intelligent chunking: instead of cutting the code every N characters, claude-context parses it as an Abstract Syntax Tree and splits along syntactic boundaries — functions, classes, methods — so each block stays a unit of meaning. And to avoid re-indexing everything on every save it uses Merkle trees: it detects changed files and updates only those. Incremental indexing, not from scratch every time.

• Hybrid search: BM25 (keywords) + dense vectors (meaning).
• AST chunking: blocks aligned to functions and classes, not blind cuts.
• Incremental indexing: Merkle trees, only modified files get updated.
• Multi-language: TypeScript, Python, Java, C#, Go, Rust, PHP, Ruby and more.

🚀 How to use it: from indexing to your first search

The day-to-day flow is disarming. Once the MCP server is set up, you open Claude Code in the project folder and tell it «Index this codebase». Indexing starts — you can ask «What's the indexing status?» to see the percentage — and from then on you search in natural language: «Find the functions that handle user authentication».

On the tooling side, the server exposes four essential commands to the agent: `index_codebase` to build the index, `search_code` to query it with hybrid search, `get_indexing_status` for progress, and `clear_index` to start over. You don't need to memorize them: the agent invokes them for you when it recognizes that the request is a search over the code.

> Index this codebase
  …indexing in progress (AST + embeddings)…

> What's the indexing status?
  Completed 100% · ready to search

> Find the functions that handle user authentication
  auth/session.ts:42 · login()  ·  score 91%
  auth/tokens.ts:17 · verifyJwt()  ·  score 88%

🔌 Not just Claude Code: many clients, one setup

Even though the name says Claude, claude-context is a standard MCP server and works with a long list of agents: besides Claude Code and Claude Desktop, the docs cover OpenAI Codex CLI, Gemini CLI, Cursor, Windsurf, Cline, Roo Code, Augment, Qwen Code and more. You configure it once and reuse it with the editor you prefer.

For those who live in the IDE there's also a VS Code extension («Semantic Code Search») that uses the same engine without going through an agent. The MCP configuration is the usual handful of lines — a `claude mcp add` command or a JSON/TOML block: if you've already connected an MCP server, nothing changes here. The mechanism is identical to the one we've covered for Claude Code, Codex and VS Code.

# the key is mcp_servers (not mcpServers) on Codex
[mcp_servers.claude-context]
command = "npx"
args = ["@zilliz/claude-context-mcp@latest"]
env = { OPENAI_API_KEY = "your-key", MILVUS_TOKEN = "your-api-key" }
startup_timeout_ms = 20000

📊 How much it really saves

The number going around is around 40% fewer tokens at equivalent retrieval quality: it comes from the controlled evaluation the authors published in the repo's `evaluation` folder. Read it for what it is — a measurement by the team building the project — but it isn't isolated: independent reviews and user reports on Reddit talk about reductions in the 30-50% range in long sessions.

The saving logic is intuitive: if the agent receives three targeted snippets instead of ten whole files, the context stays lean and the same answer costs less. On a large project and over long sessions that's where you feel the difference, both on the bill and in the clarity of the answers. On a single file, of course, the benefit is negligible.

repo      zilliztech/claude-context
stars     ~11,800 · MIT license · by Zilliz (Milvus team)
stack     TypeScript · Python · Node.js ≥ 20
engine    hybrid BM25 + vectors · AST chunking
storage   Milvus / Zilliz Cloud · embeddings OpenAI/Voyage/Gemini/Ollama
saving    ~40% tokens (authors' evaluation)

⚠️ What to know before adopting it

It isn't friction-free. claude-context needs two external ingredients: a vector database (Milvus locally, or Zilliz Cloud, which has a free tier) and an embedding provider (OpenAI, VoyageAI, Gemini or Ollama locally). You have to configure the relevant keys, and that's the extra step compared to a «zero-cost» MCP.

Then there's a privacy angle to weigh with your head: by default the embeddings of your code are computed by an external service and stored in a vector database. On proprietary code or under NDA the fully local route is preferable — Ollama for embeddings and self-hosted Milvus — so the code never leaves your machines. It's a setup choice, not a limitation of the project, but make it deliberately before indexing sensitive repositories.

🏢 Why it's interesting for developers and SMBs

For developers, claude-context is a case study of RAG applied to code: incremental indexing, syntactic chunking and hybrid search are exactly the bricks you'd use to build an internal search engine. Seeing them packaged in a ready-to-use MCP server is, in itself, a small architecture lesson.

For an SMB introducing AI into development the value is twofold: on one hand you contain the cost of agent sessions on real projects (which are rarely small), on the other you make the assistant more reliable, because it works on the right code instead of a random selection. Fewer tokens spent and more on-target answers are two metrics a tech lead grasps at once. And the fully local variant satisfies those with confidentiality constraints too.

🗺️ Where to start

The low-risk path: create a free Zilliz Cloud account (or spin up a local Milvus), get an embedding key, add the server with `claude mcp add` and index a test project, not the company monorepo right away. Run two or three natural-language searches and compare the answers with what you got without an index: in ten minutes you'll know whether the retrieval helps you.

If the code is sensitive, start directly from the local configuration with Ollama. And if you want to frame the MCP mechanism before getting hands-on, the deep dives below explain how to connect an MCP server to Claude Code, Codex and VS Code. Studying how claude-context holds index, embeddings and search together is worth as much as using it.

More articles from the blog