Codebase Context
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.
Related MCP server: Carto MCP Server
Quick Start
claude mcp add codebase-context -- npx -y codebase-contextThe server runs in two modes. Use stdio unless you need multiple clients connected at once:
Mode | How it runs | When to use |
stdio (default) | Process spawned by the client | One AI client talking to one or more repos |
HTTP | Long-lived server at | Multiple clients sharing one server |
Client support at a glance:
Client | stdio | HTTP |
Claude Code | Yes | No (stdio only) |
Claude Desktop | Yes | No |
Cursor | Yes | Yes — |
Windsurf | Yes | Not yet |
Codex | Yes | Yes — |
VS Code (Copilot) | Yes | No |
OpenCode | Yes | Not documented yet |
Copy-pasteable templates: templates/mcp/stdio/.mcp.json and templates/mcp/http/.mcp.json.
Full per-client setup, HTTP server instructions, and local build testing: docs/client-setup.md.
First Use
Get a conventions map of your codebase before exploring or editing:
# See your codebase conventions — architecture layers, patterns, golden files
npx -y codebase-context map
# Then search for what you need
npx -y codebase-context search --query "auth middleware"Your AI agent uses the same map via the codebase://context MCP resource on first call.
Common First Commands
Three commands to understand a repo before you edit it:
# What are the main conventions and best examples?
npx -y codebase-context map
# Then search for the local example you need
npx -y codebase-context search --query "auth middleware"
# What patterns is the team actually using right now?
npx -y codebase-context patternsThis is also what your AI agent consumes automatically via MCP tools; the CLI is the human-readable version of the same map-plus-search flow.
What it does
The Search Tool (search_codebase)
One call returns ranked results with file, summary, score, compact type (componentType:layer), pattern trend signals, relationship hints, related team memories, a search quality assessment, and a preflight decision card when intent="edit". The decision card shows ready (boolean), nextAction when not ready, patterns (do/avoid), bestExample, impact coverage ("3/5 callers in results"), and whatWouldHelp.
Default output is lean — if the agent wants code, it calls read_file. Add includeSnippets: true for inline code with scope headers (e.g. // AuthService.getToken()).
See docs/capabilities.md for the full field reference.
Patterns & Conventions (get_team_patterns)
Detects what your team actually does by analyzing the codebase: adoption percentages for DI, state management, testing, and library patterns; trend direction (Rising / Stable / Declining) from git recency; golden files ranked by modern pattern density; conflicts when two approaches both exceed 20%.
Team Memory (remember + get_memory)
Record a decision once. It surfaces automatically in search results and preflight cards from then on. Conventional commits (refactor:, migrate:, fix:, revert:) from the last 90 days auto-extract into memory during indexing — no setup required.
Memory types: convention, decision, gotcha, failure. Confidence decay: conventions never decay, decisions 180-day half-life, gotchas/failures 90-day. Stale memories get flagged instead of blindly trusted.
Tools
Tool | What it does |
| Hybrid search + decision card when |
| Pattern frequencies, golden files, conflict detection |
| Concrete references to a symbol (count + snippets) |
| Record a convention, decision, gotcha, or failure |
| Query team memory with confidence decay scoring |
| Project structure, frameworks, dependencies |
| Style guide rules for the current project |
| Import cycles between files |
| Full or incremental re-index + git memory extraction |
| Progress and stats for the current index |
Multi-project
One server, multiple repos. Three cases:
Case | What happens |
One project | Routing is automatic |
Multiple projects, active project already set | Routes to the active project |
Multiple projects, ambiguous | Returns |
project accepts a project root path, file path, file:// URI, or relative subproject path (e.g. apps/dashboard).
{
"name": "search_codebase",
"arguments": {
"query": "auth interceptor",
"project": "apps/dashboard"
}
}If you get selection_required, retry with one of the paths from availableProjects. Full routing details and response shapes in docs/capabilities.md.
Language Support
10 languages with full symbol extraction via Tree-sitter: TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Go, Rust. 30+ languages with indexing and retrieval coverage, including PHP, Ruby, Swift, Scala, Shell, and config formats. Angular, React, and Next.js have dedicated analyzers; everything else uses the Generic analyzer with AST-aligned chunking when a grammar is available.
Configuration
Variable | Default | Description |
|
|
|
| — | Required only if using |
| — | Bootstrap root for CLI and single-project MCP clients |
| — | Set to |
|
| Local embedding model override |
| — | Set to |
|
| HTTP server port override (same as |
|
| Override the server config file path |
Performance
First indexing: 2-5 minutes for ~30k files (embedding computation).
Subsequent queries: milliseconds from cache.
Incremental updates:
refresh_indexwithincrementalOnly: trueprocesses only changed files (SHA-256 manifest diffing).
File Structure
.codebase-context/
memory.json # Team knowledge (should be persisted in git)
index-meta.json # Index metadata and version (generated)
intelligence.json # Pattern analysis (generated)
relationships.json # File/symbol relationships (generated)
index.json # Keyword index (generated)
index/ # Vector database (generated)Recommended .gitignore:
# Codebase Context - ignore generated files, keep memory
.codebase-context/*
!.codebase-context/memory.jsonWhat to add to your CLAUDE.md / AGENTS.md
Paste this into .cursorrules, CLAUDE.md, AGENTS.md, or wherever your AI reads project instructions:
## Codebase Context (MCP)
**Start of every task:** Call `get_memory` to load team conventions before writing any code.
**Before editing existing code:** Call `search_codebase` with `intent: "edit"`. If the preflight card says `ready: false`, read the listed files before touching anything.
**Before writing new code:** Call `get_team_patterns` to check how the team handles DI, state, testing, and library wrappers — don't introduce a new pattern if one already exists.
**When asked to "remember" or "record" something:** Call `remember` immediately, before doing anything else.
**When adding imports that cross module boundaries:** Call `detect_circular_dependencies` with the relevant scope after adding the import.These are the behaviors that make the most difference day-to-day. Copy, trim what doesn't apply to your stack, and add it once.
Links
Benchmark — current discovery suite results and gate truth
Demo — real CLI walkthrough
Client Setup — per-client config, HTTP setup, local build testing
Capabilities Reference — tool API, retrieval pipeline, decision card schema
CLI Gallery — formatted command output examples
Motivation — research and design rationale
Contributing — dev setup and eval harness
License
Elastic-2.0
Available Tools
11 toolsdetect_circular_dependenciesA
Routes to the active/current project automatically when known. Analyze the import graph to detect circular dependencies between files. Circular dependencies can cause initialization issues, tight coupling, and maintenance problems. Returns all detected cycles sorted by length (shorter cycles are often more problematic).
Inputs: scope, project, project_directory.
get_codebase_healthA
Routes to the active/current project automatically when known. Get actionable codebase health signals from the latest index. Returns the highest-risk files and their reasons, or a single file when requested.
Inputs: file, limit, level, project, +1 more.
get_codebase_metadataB
Routes to the active/current project automatically when known. Get codebase metadata including framework information, dependencies, architecture patterns, and project statistics.
Inputs: project, project_directory.
get_indexing_statusA
Routes to the active/current project automatically when known. Get current indexing status: state, statistics, and progress. Use refresh_index to manually trigger re-indexing when needed.
Inputs: project, project_directory.
get_memoryA
Routes to the active/current project automatically when known. Retrieves team conventions, architectural decisions, and known gotchas. CALL BEFORE suggesting patterns, libraries, or architecture.
Filters: category (tooling/architecture/testing/dependencies/conventions), type (convention/decision/gotcha), query (keyword search).
Inputs: category, type, query, project, +1 more.
get_style_guideA
Routes to the active/current project automatically when known. Query style guide rules and architectural patterns from project documentation.
Inputs: query, category, project, project_directory.
get_symbol_referencesA
Routes to the active/current project automatically when known. Find concrete references to a symbol in indexed chunks. Returns total usageCount and top usage snippets.
Inputs: symbol (required), limit, project, project_directory.
get_team_patternsA
Routes to the active/current project automatically when known. Get actionable team pattern recommendations based on codebase analysis. Returns consensus patterns for DI, state management, testing, library wrappers, etc.
Inputs: category, project, project_directory.
refresh_indexA
Routes to the active/current project automatically when known. Re-index the codebase. Supports full re-index or incremental mode. Use incrementalOnly=true to only process files changed since last index.
Inputs: reason, incrementalOnly, project, project_directory.
rememberA
Routes to the active/current project automatically when known. CALL IMMEDIATELY when user explicitly asks to remember/record something.
USER TRIGGERS:
"Remember this: [X]"
"Record this: [Y]"
"Save this for next time: [Z]"
DO NOT call unless user explicitly requests it.
HOW TO WRITE:
ONE convention per memory (if user lists 5 things, call this 5 times)
memory: 5-10 words (the specific rule)
reason: 1 sentence (why it matters)
Skip: one-time features, code examples, essays
Inputs: type (required), category (required), memory (required), reason (required), +3 more.
search_codebaseA
Routes to the active/current project automatically when known. Search the indexed codebase. Default compact mode returns at most 6 ranked results with light graph context (importedByCount, topExports, layer), a patternSummary, bestExample, nextHops, and response-budget metadata. Use mode="full" for today's richer response with full hints arrays and all memories — identical shape as before this parameter existed. IMPORTANT: Pass the intent="edit"|"refactor"|"migrate" to get preflight: edit readiness check with evidence gating.
Inputs: query (required), mode, intent, limit, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct aspect of codebase context: detection, health, metadata, indexing, memory, style guide, references, patterns, refresh, remember, and search. No two tools have overlapping purposes; descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_codebase_health, detect_circular_dependencies). The only exception is 'remember' which is a single verb but remains clear and fits the pattern.
11 tools is well-scoped for a codebase context server. It covers indexing, querying, analysis, and memory without being overwhelming. Each tool earns its place.
The tool set covers reading and writing codebase knowledge, analysis (dependencies, health, references), and search. Minor gaps exist, such as no direct file content retrieval or code review integration, but the domain of 'context' is well-served.
Maintenance
Related MCP Connectors
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Serves your design system and coding standards to coding agents, so they stop guessing.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Related MCP Servers
- AlicenseBqualityCmaintenanceProvides AI assistants with persistent memory of your project architecture, development history, and technical decisions, allowing them to give context-aware coding help without needing repeated explanations.1661 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding tools to query your live codebase for routes, import graph, domain context, and blast radius, eliminating hallucinations about project structure.80MIT
- AlicenseAqualityDmaintenanceAnalyzes codebases from local directories, GitHub, and Azure DevOps, providing intelligent context to AI coding assistants through repository structure, critical files, and semantic maps.144MIT
- AlicenseAqualityBmaintenanceSelf-hosted semantic code search for AI coding agents. Indexes many repositories at once with tree-sitter AST chunking, local llama.cpp embeddings and Qdrant, so Claude Code, Cursor, Codex and any MCP client can find code by meaning, trace usages and callers, and read the git history behind each chunk. No API keys, and your code never leaves your machine.21835MIT