You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You're tired of AI agents writing generic code that compiles but completely ignores how your team does things — even with well-curated instructions. You correct the agent, it doesn't remember. Next session, same mistakes.
7
+
You're tired of AI agents writing code that 'just works' but fits like a square peg in a round hole - not your conventions, not your architecture, not your repo. Even with well-curated instructions. You correct the agent, it doesn't remember. Next session, same mistakes.
8
8
9
-
This MCP gives agents *just enough* context so they match *how* your team codes, know *why*, and *remember* every correction.
9
+
This MCP gives agents _just enough_ context so they match _how_ your team codes, know _why_, and _remember_ every correction.
10
10
11
-
**Finds the right context** — Search that doesn't just return code. Each result comes back with pattern signals, related team memories, file relationships, and quality indicators. The agent gets curated context, not raw hits.
11
+
Here's what codebase-context does:
12
12
13
-
**Knows your conventions**— Detected from your code, not from rules you wrote. Adoption percentages, trend direction (rising/declining), golden files. What patterns the team is moving toward and what's being left behind.
13
+
**Finds the right context**- Search that doesn't just return code. Each result comes back with analyzed -and quantified- coding patterns and conventions, related team memories, file relationships, and quality indicators. The agent gets curated context, not raw hits.
14
14
15
-
**Remembers across sessions**— Decisions, failures, gotchas — recorded once, surfaced automatically. Conventional git commits (`refactor:`, `migrate:`, `fix:`) auto-extract into memory with zero effort. Stale memories decay and get flagged instead of blindly trusted.
15
+
**Knows your conventions**- Detected from your code, not only from rules you wrote. Seeks team consensus and direction by adoption percentages and trends (rising/declining), golden files. What patterns the team is moving toward and what's being left behind.
16
16
17
-
**Checks before editing**— A preflight card with risk level, patterns to use and avoid, failure warnings, and a `readyToEdit` evidence check. If evidence is thin or contradictory, it says so.
17
+
**Remembers across sessions**- Decisions, failures, things that _should_ work but didn't when you tried - recorded once, surfaced automatically. Conventional git commits (`refactor:`, `migrate:`, `fix:`) auto-extract into memory with zero effort. Stale memories decay and get flagged instead of blindly trusted.
18
18
19
-
One tool call returns all of it. Local-first — your code never leaves your machine.
19
+
**Checks before editing** - A preflight card with risk level, patterns to use and avoid, failure warnings, and a `readyToEdit` evidence check. If evidence is thin or contradictory, it says so.
20
+
21
+
One tool call returns all of it. Local-first - your code never leaves your machine.
20
22
21
23
<!-- TODO: Add demo GIF here showing search_codebase with preflight card output -->
22
24
<!--  -->
23
25
24
26
## Quick Start
25
27
26
-
### Claude Code
28
+
Add it to the configuration of your AI Agent of preference:
27
29
28
-
No config file needed:
30
+
### Claude Code
29
31
30
32
```bash
31
33
claude mcp add codebase-context -- npx -y codebase-context /path/to/your/project
@@ -55,7 +57,7 @@ Add `.vscode/mcp.json` to your project root:
"args": ["-y", "codebase-context", "/path/to/your/project"] // Or "${workspaceFolder}"if your workspace is one project only
59
61
}
60
62
}
61
63
}
@@ -91,19 +93,24 @@ Open Settings > MCP and add:
91
93
}
92
94
```
93
95
96
+
## Codex
97
+
98
+
Run codex mcp add codebase-context npx -y codebase-context "/path/to/your/project"
99
+
94
100
## What It Actually Does
95
101
96
-
Other tools help AI find code. This one helps AI make the right decisions — by knowing what your team does, tracking where patterns are heading, and warning before mistakes happen.
102
+
Other tools help AI find code. This one helps AI make the right decisions - by knowing what your team does, tracking where codebases are heading, and warning before mistakes happen.
97
103
98
104
### The Difference
99
105
100
-
| Without codebase-context | With codebase-context |
101
-
| --- | --- |
102
-
| Generates code using whatever matches or "feels" right | Sees what's rising vs declining in your codebase |
103
-
| Copies any example that fits | Follows your best implementations (golden files) |
104
-
| Repeats mistakes you already corrected | Surfaces failure memories right before trying again |
105
-
| You re-explain the same things every session | Remembers conventions and decisions automatically |
106
-
| Edits confidently even when context is weak | Gets `readyToEdit: false` - knows to ask first |
106
+
| Without codebase-context | With codebase-context |
| Generates code using whatever matches or "sounds" right | Generates code following your team conventions |
109
+
| Copies any example that fits | Follows your best implementations (golden files) |
110
+
| Repeats mistakes you already corrected | Surfaces failure memories right before trying again |
111
+
| You re-explain the same things every session | Remembers conventions and decisions automatically |
112
+
| Edits confidently even when context is weak | Flags high-risk changes when evidence is thin |
113
+
| Sees what the current code does and assumes | Sees how your code has evolved and why |
107
114
108
115
### The Search Tool (`search_codebase`)
109
116
@@ -143,39 +150,39 @@ When the intent is `edit`, `refactor`, or `migrate`, the same call also returns
143
150
}
144
151
```
145
152
146
-
Risk level, what to use, what to avoid, what broke last time, and whether the evidence is strong enough to proceed — all in one response.
153
+
Risk level, what to use, what to avoid, what broke last time, and whether the evidence is strong enough to proceed - all in one response.
147
154
148
155
### Patterns & Conventions (`get_team_patterns`)
149
156
150
157
Detects what your team actually does by analyzing the codebase:
151
158
152
159
- Adoption percentages for dependency injection, state management, testing, libraries
153
160
- Patterns/conventions trend direction (Rising / Stable / Declining) based on git recency
154
-
- Golden files — your best implementations ranked by modern pattern density
155
-
- Conflicts — when the team hasn't converged (both approaches above 20% adoption)
161
+
- Golden files - your best implementations ranked by modern pattern density
162
+
- Conflicts - when the team hasn't converged (both approaches above 20% adoption)
156
163
157
164
### Team Memory (`remember` + `get_memory`)
158
165
159
-
Record a decision once. It surfaces automatically in search results and preflight cards from then on. **Your git commits also become memories**— conventional commits like `refactor:`, `migrate:`, `fix:`, `revert:` from the last 90 days are auto-extracted during indexing.
166
+
Record a decision once. It surfaces automatically in search results and preflight cards from then on. **Your git commits also become memories**- conventional commits like `refactor:`, `migrate:`, `fix:`, `revert:` from the last 90 days are auto-extracted during indexing.
160
167
161
168
-**Types**: conventions (style rules), decisions (architecture choices), gotchas (things that break), failures (we tried X, it broke because Y)
162
169
-**Confidence decay**: decisions age over 180 days, gotchas and failures over 90 days. Stale memories get flagged instead of blindly trusted.
163
170
-**Zero-config git extraction**: runs automatically during `refresh_index`. No setup, no manual work.
164
171
165
172
### All Tools
166
173
167
-
| Tool | What it does |
168
-
| --- | --- |
169
-
|`search_codebase`| Hybrid search with enrichment. Pass `intent: "edit"` for preflight. |
170
-
|`get_team_patterns`| Pattern frequencies, golden files, conflict detection |
171
-
|`get_component_usage`| "Find Usages" — where a library or component is imported |
172
-
|`remember`| Record a convention, decision, gotcha, or failure |
173
-
|`get_memory`| Query team memory with confidence decay scoring |
0 commit comments