Codebase Context

Coding agents can read files, but they still have to discover how your repository is organized, which patterns your team follows, and which examples are worth copying.

Codebase Context gives an agent a local view of that information through code search, team patterns, strong examples, and project memory. It runs as an MCP server - a local tool that your editor or command-line agent can call while it works - and keeps the index on your machine by default.

Choose your coding tool and run its command once. Use Node.js 22 or newer. These commands use published npm 2.2.0 and do not require a project folder in your configuration:

# Claude Code
claude mcp add --scope user --transport stdio codebase-context -- npx -y [email protected]

# Codex CLI
codex mcp add codebase-context -- npx -y [email protected]

# OpenCode 1.x (keep the quoted separator on Windows)
opencode mcp add codebase-context '--' npx -y [email protected]

Start a new agent session in your project, then ask:

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. The agent supplies the repository path in its tool calls, so the registration can serve different projects. Initial indexing may need a local model download. The October 6 isolated checks proved these client registrations and published-package project selection/search; they did not establish a full native agent investigation.

For Codex Desktop, create or merge .codex/config.toml in the project you want to search:

[mcp_servers.codebase-context]
command = "npx"
args = ["-y", "[email protected]"]
startup_timeout_sec = 120

Trust the project if asked, restart Codex, and start a new task there. Use the prompt above. Config placement alone does not establish successful first use; this no-folder recipe has not been accepted in a fresh native Desktop task.

Other clients use their own setup commands:

Check an existing same-name entry before replacing it. To give the server a default folder, append that folder's absolute path to the npx arguments. The client setup guide covers scopes, optional fixed-folder configuration, verification limits and the unreleased installer. Published 2.2.0's interactive init has registration bugs; use the commands above.

The client setup guide has the exact commands and config for every client, plus what was checked locally and what still relies on official instructions.

The default connection is stdio (standard input/output): your client starts the server when it needs it. HTTP is an advanced, client-dependent option; verify the setup guide and client support before relying on it.

search_codebase ranks files and symbols for the task instead of returning an unstructured dump. The agent can ask for a compact result first, then read the code it needs.

get_team_patterns shows the approaches used in the repository and points to representative files. Published 2.2.0 includes dedicated analyzers for Angular, React and Next.js, with a generic analyzer for other stacks. NestJS support belongs to the newer source candidate.

remember stores a convention, decision, gotcha, or past failure for the project. get_memory retrieves relevant entries in later sessions, including when the agent or editor changes.

1. Index locally. Codebase Context scans the project, builds a keyword index, and creates local semantic embeddings - numeric representations used to match code by meaning as well as exact words.
2. Understand the repository. The agent can request a compact codebase map with structure, patterns, and representative files.
3. Find the code for the task. Search returns ranked files and symbols; the agent reads the selected files before editing.

The same information is available from the terminal. Run these commands from your project root. The first index can take a while because it scans the project and creates local embeddings; once it is ready, inspect the map and search for the code you need:

# Build or refresh the local index
npx -y [email protected] reindex

# Repository structure, patterns, and representative files
npx -y [email protected] map

# Ranked code search
npx -y [email protected] search --query "auth middleware"

# Current team patterns
npx -y [email protected] patterns

One stdio server can route across several repositories. Supply project in tool calls to select the intended repository; a successful selection becomes the default for later calls in that process. Some clients also announce workspace roots: one root can auto-select, while an ambiguous selection asks for a project instead of guessing. MCP deprecated Roots in its July 2026 revision, so explicit project selection is the documented default rather than a dependency on client discovery.

These are real CLI results from the open-source angular-spotify repository.

Patterns and representative files

The map shows the patterns found in the project, how common they are, and files that demonstrate them.

Search before an edit

The search result shows ranked files, relevant project patterns, and what the agent should read before it changes code.

More examples are available in the CLI gallery and walkthrough.

Code and indexes stay on the machine with the default local embedding provider. Docker, a GPU, and an API key are not required.

Cloud embeddings are optional. If you select a cloud provider, code chunks are sent to that provider to create the search index. The provider, model, project root, and local HTTP port can be changed through environment variables or the project config; see the capabilities reference.

This is the privacy boundary of Codebase Context itself. Your AI client may send search results or file contents to the model provider configured in that client. Codebase Context does not control that connection. If you commit and push .codebase-context/memory.json, the recorded project memory also travels with the repository.

Generated indexes belong in .gitignore. Project memory can be kept in version control when the team wants to share it:

.codebase-context/*
!.codebase-context/memory.json

Codebase Context runs locally through the Model Context Protocol (MCP), with indexed code kept on your machine by default.

Its ranked code search combines Match words, Search by meaning, and Rank results to give the agent ranked files, a best example, project patterns, relationships, and relevant memory before they edit.

The benchmark reports a corrected 100-attempt retrieval family across five local code-context tools: 99 completed attempts and 1 failed attempt. Codebase Context recovered 25.7% of expected gold files with 11.5% file precision in that fixed adapter run; jCodeMunch recovered 27.1% with 11.0% file precision. Raw-native is a deterministic lexical adapter here, not a full normal coding-agent baseline. These are retrieval observations, not a winner or a coding-quality claim. The sanitized evidence extract records the exact values and source hashes.

The same report retains a separate 300-attempt repeatability history, a 30-run two-task full-agent pilot, and a metered replay whose tool-use validity remains unresolved. A historical Codebase Context indexing observation with embeddings enabled took about 12 minutes 31 seconds, but it does not establish warm-use speed, query latency, install cost, or a cross-tool index-speed ranking. The report does not combine these families into a pooled score and does not establish patch correctness or end-to-end coding quality. Earlier public reports are preserved separately in the benchmark archive.

The method and failures are documented so the measurements can be inspected with their limits.

• Local semantic indexing does more work than a plain text index, especially on a fresh checkout and CPU-only machine.
• Retrieval measurements describe expected-file coverage, file precision, and reported peakPrivateGb, not patch correctness or end-to-end coding quality.
• The paired token observation covers two frozen investigation tasks and records observed agent behavior; it is not a universal token or time guarantee.
• Setup checks differ by client. The detailed guide distinguishes a written config, a config recognized by the client, a local connection, and instructions checked only against official docs.
• Published 2.2.0 has dedicated Angular, React and Next.js analyzers; NestJS support is in the newer source candidate. Other projects use the generic analyzer and the language parsers available for that stack.
• The default searchable-chunk limit is 5,000 per project. Larger repositories can raise it in .codebase-context/config.json.
• The agent must identify its repository in tool calls when no default or unambiguous client root is available. Concurrent HTTP client isolation is not established by the stdio routing checks.

• Client setup - commands, config, proof level, and client limits
• Capabilities - tools, response fields, routing, and configuration
• CLI - terminal commands and example output
• Benchmark - method, measurements, and failures
• Demo - a complete repository walkthrough
• Motivation - the design problem and research background
• Contributing - local development and evaluation commands
• Changelog - release history

Elastic-2.0. See LICENSE.