SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI codingcodebase-context

codebase-context

Shows agents which patterns a codebase actually uses, which files a change will affect and when there is too little context to trust an edit. Runs locally.

Open website

About this tool

Purpose

Codebase Context is designed to solve the problem of coding agents not understanding the codebase. Agents can read files, but they still need to discover the repository structure, the patterns the team follows, and examples worth copying on their own. This tool provides agents with a local view through code search, team patterns, strong examples, and project memory, so they consume fewer tokens, spend less time, and produce code that is more familiar with the project style.

Main capabilities

  • Semantic code search: search_codebase ranks files and symbols by task, rather than returning large unstructured chunks of content. Agents can first request compact results, then read the code they need.
  • Team patterns and examples: get_team_patterns shows the approaches used in the repository and points to representative files. Version 2.2.0 includes dedicated analyzers for Angular, React, and Next.js, while other technology stacks use the generic analyzer; NestJS support belongs to a newer source candidate release.
  • Project memory: remember can store conventions, decisions, pitfalls, or past failures; get_memory retrieves relevant entries in subsequent sessions, and works even if the agent or editor changes.
  • Local indexing: scans the project, builds a keyword index, and creates local semantic embeddings (used to match code by meaning, not just by exact words).
  • Repository understanding: agents can request a compact codebase map containing structure, patterns, and representative files.
  • Multi-repository routing: a single stdio server can route across multiple repositories, providing a project parameter in tool calls to select the target repository; a successful selection becomes the default for subsequent calls in that process.

How to use

Run locally via the Model Context Protocol (MCP). The default connection is stdio: the client starts the server when needed. HTTP is an advanced option that depends on client support.

In the AI client, you need to run the corresponding command to register. Node.js 22 or later is required. The command uses the published npm 2.2.0 package, and no project folder is needed in the configuration (the package has a registration defect with interactive init, so use the command given in the documentation). After registration, in a new session, give the agent a prompt similar to:

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.

The initial index may require downloading a local model. Codex Desktop needs to create or merge .codex/config.toml within the project. Other clients use their respective settings commands.

It can also be used from the terminal: run the command in the project root directory; the first index may take a long time because it scans the project and creates local embeddings. Afterward, you can inspect the map and search for the code you need.

Use cases

  • Want to reduce token consumption when agents explore the codebase.
  • Teams want agents to follow existing patterns and use representative examples.
  • Need to preserve project conventions, decisions, and pitfalls across sessions.
  • Perform semantic code retrieval under the premise of local privacy first.
  • Select projects on demand when working across multiple repositories.

Limitations

  • Local semantic indexing is more expensive than plain text indexing, especially on fresh checkouts and CPU-only machines.
  • Retrieval metrics only describe expected file coverage, file precision, and peak private memory; they do not represent patch correctness or end-to-end coding quality.
  • Paired token observations only cover two fixed research tasks and record observed agent behavior, not general token or time guarantees.
  • The level of settings checks differs across clients; the detailed guide distinguishes written configuration, client-recognized configuration, local connections, and instructions checked only against official documentation.
  • 2.2.0 includes dedicated analyzers for Angular, React, and Next.js; NestJS support is among newer source candidates; other projects use the general analyzer and the language parsers available for that technology stack.
  • By default, the upper limit of searchable chunks per project is 5000; larger repositories can increase it in .codebase-context/config.json.
  • When there is no default or explicit client root directory, the agent must specify the repository in the tool call; stdio routing checks have not proven concurrent HTTP client isolation.
  • Cloud embeddings are optional; if a cloud provider is chosen, code chunks are sent to that provider to create the search index. Codebase Context does not control the AI client's own connections that send search or file content to model providers. If .codebase-context/memory.json is committed and pushed, project memory will propagate with the repository. Generated indexes should be added to .gitignore.
  • The license is Elastic-2.0.

Related tools

Browse category