Codebase Context
Your coding agent doesn't understand your codebase.
A local MCP server and CLI that indexes your repo with Tree-sitter and local embeddings. It brings relevant source files, symbol references and saved team decisions into your AI agent (including Claude Code, Codex CLI, OpenCode, Cursor, etc.).
Runs locally via MCP (stdio). Indexing and search stay on your machine by default.
Lane A: Raw Native Grep
21 calls shown · 7 source files referenced1. rg -n "partial call|verify partial|inherited from a trait|trait.*method|method bodies|partial calls" .
Lane B: Codebase Context MCP
12 calls shown1. codebase_context({ query: "Don't verify partial calls for method bodies inherited from a trait. Resolved issue #2228. Find likely files and symbols related to partial call verification and trait method inheritance.", maxResults: 8 }) (result: 6 ranked locations)
Get started
Add it to your coding agent
Give your agent a way to find relevant code and saved team decisions in this repository.
Use Node.js 22+. Your tool starts CBC when it connects; your agent selects the repository you're working in.
Run once in PowerShell or a macOS/Linux terminal:
Claude Code
claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.2.0Start a new Claude Code session in this project. Approve the server if asked.
Client docs ↗Optional: set a fixed project folder
Leave blank to let the agent select its repository. A full path adds a default folder to the command above; Windows Copy as path works.
Then try it in your project
First use may need local indexing and a model download. Ask your agent:
Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project when checking get_indexing_status and searching. Wait for indexing if needed, read codebase://context, then search_codebase and open a returned source file. Show me the relevant files.
Replace [feature] with something you want to find.
Check that your agent sees the right project and can open a returned source file.
Surface repository conventions alongside matching code.
A search can point your agent to relevant files, patterns used in the project and saved decisions. Here is an authentication example from angular-spotify.
Task
Find where authentication is handled
angular-spotify
Files to inspect
unauthorized-modal.component.tsUI shown when authorization fails
store/auth.store.tsAuthentication state and token handling
models/spotify-authorize.tsAuthorization request model
Conventions used here
- Components
- Standalone
- State
- RxJS
- Reactivity
- Effect
Example component
card.component.tsSaved project decision
Handle refresh tokens and first-time login together.
Local by default
Local indexing is the default
Local indexing and local embeddings are the default. A cloud embedding provider is optional; selecting one sends code chunks to that provider.
Your coding client has its own model and privacy settings, so it may separately send tool results or files to its model provider.
Evidence
Tested against other local tools
The benchmark compares five open-source code-context tools on open-source repository tasks. It reports files returned and retained no-context attempts without combining them into one score.
See the full benchmarkCurrent limits
What this does not prove
Codebase Context helps an agent find project evidence. It cannot guarantee a correct edit. The current benchmark does not prove patch correctness or universal token savings. The indexing measurements are shown only with their limits and are not used to rank tools.