PatrickSys/codebase-context

Your coding agent doesn't understand your codebase.
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.
Set up your AI client
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:
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:
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:
| Client | Shortest current setup |
| --------------------------- | ---------------------------------------------------------------------------- |
| Gemini CLI | gemini mcp add --scope user codebase-context npx -y codebase-context@2.2.0 |
| Cursor | Add .cursor/mcp.json |
| VS Code with GitHub Copilot | Add .vscode/mcp.json |
| GitHub Copilot CLI | copilot mcp add codebase-context -- npx -y codebase-context@2.2.0 |
| Windsurf | Add ~/.codeium/windsurf/mcp_config.json |
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.
What your agent gets
Relevant code
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.
Team patterns and examples
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.
Project memory
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.