codebase-context

Map your team's conventions before your AI agent starts searching.

You're tired of AI agents writing code that "just works" but still misses how your team actually builds things. They search too broadly, pick generic examples, and spend tokens exploring before they understand the shape of the repo.

codebase-context changes the first step. Start with a bounded conventions map that shows the architecture, dominant patterns, and strongest local examples. Then search for the exact file, symbol, or workflow you need.

Here's what codebase-context does:

Starts with a bounded conventions map - The first call shows architecture layers, active patterns, golden files, and next calls without dumping vendored repos, fixtures, generated output, or oversized entrypoint lists into the default surface.

Finds the right local example - Search does not just return code. Each result comes back with pattern signals, file relationships, and quality indicators so the agent can move from the map to the most relevant local example instead of wandering through raw hits.

Knows what is current - Conventions are detected from your code and git history, not only from rules you wrote. The map distinguishes what is common from what is rising or declining, and points at the files that best represent the current direction.

Adds support signals when you need them - Team memory and edit-readiness checks stay available, but as supporting context after the map and search have already narrowed the work.

Map first, search second, local-first throughout. Your code never leaves your machine by default.

See the current discovery benchmark for the checked-in discovery-only proof. The gate is still pending_evidence, and claimAllowed remains false.

What it looks like

Real CLI output against angular-spotify, the repo used for the launch screenshots.

Lead signal: pattern drift and golden files

This is the part most tools miss: what the team is doing now, what it is moving away from, and which files are the strongest examples to follow.

Before editing: preflight and impact

When the agent searches with edit intent, it gets a compact decision card: confidence, whether it's safe to proceed, which patterns apply, the best example, and which files are likely to be affected.

More CLI examples in docs/cli.md. Full walkthrough: demo.md on GitHub.

Quick Start

claude mcp add codebase-context -- npx -y codebase-context

The server runs in two modes. Use stdio unless you need multiple clients connected at once:

Client support at a glance:

... View full README on GitHub