Skip to content

Commit b7bc5cc

Browse files
PatrickSysPatrickSys
authored
feat(cli): status formatter + CLI gallery docs (#56)
* feat(cli): status formatter + CLI gallery docs * Streamline memory tool
1 parent 9929bb0 commit b7bc5cc

File tree

7 files changed

+718
-183
lines changed

7 files changed

+718
-183
lines changed

‎README.md‎

Lines changed: 101 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# codebase-context
22

3-
## Local-first second brain for AI Agents working on your codebase
3+
## Local-first second brain for AI agents working on your codebase
44

55
[![npm version](https://img.shields.io/npm/v/codebase-context)](https://www.npmjs.com/package/codebase-context) [![license](https://img.shields.io/npm/l/codebase-context)](./LICENSE) [![node](https://img.shields.io/node/v/codebase-context)](./package.json)
66

@@ -20,7 +20,7 @@ Here's what codebase-context does:
2020

2121
One tool call returns all of it. Local-first - your code never leaves your machine.
2222

23-
<!-- TODO: Add demo GIF: search_codebase("How does this app attach the auth token to outgoing API calls?") → AuthInterceptor top result + preflight + agent proceeds or asks -->
23+
<!-- TODO: Add demo GIF: search_codebase("How does this app attach the auth token to outgoing API calls?") -> AuthInterceptor top result + preflight + agent proceeds or asks -->
2424
<!-- ![Demo](./docs/assets/demo.gif) -->
2525

2626
## Quick Start
@@ -93,9 +93,57 @@ Open Settings > MCP and add:
9393
}
9494
```
9595

96-
## Codex
96+
### Codex
9797

98-
Run codex mcp add codebase-context npx -y codebase-context "/path/to/your/project"
98+
```bash
99+
codex mcp add codebase-context npx -y codebase-context "/path/to/your/project"
100+
```
101+
102+
## New to this codebase?
103+
104+
Three commands to get what usually takes a new developer weeks to piece together:
105+
106+
```bash
107+
# What tech stack, architecture, and file count?
108+
npx -y codebase-context metadata
109+
110+
# What does the team actually code like right now?
111+
npx -y codebase-context patterns
112+
113+
# What team decisions were made (and why)?
114+
npx -y codebase-context memory list
115+
```
116+
117+
This is also what your AI agent consumes automatically via MCP tools; the CLI is the human-readable version.
118+
119+
### CLI preview
120+
121+
```text
122+
$ npx -y codebase-context patterns
123+
┌─ Team Patterns ──────────────────────────────────────────────────────┐
124+
│ │
125+
│ UNIT TEST FRAMEWORK │
126+
│ USE: Vitest – 96% adoption │
127+
│ alt CAUTION: Jest – 4% minority pattern │
128+
│ │
129+
│ STATE MANAGEMENT │
130+
│ PREFER: RxJS – 63% adoption │
131+
│ alt Redux-style store – 25% │
132+
│ │
133+
└──────────────────────────────────────────────────────────────────────┘
134+
```
135+
136+
```text
137+
$ npx -y codebase-context search --query "file watcher" --intent edit --limit 1
138+
┌─ Search: "file watcher" ─── intent: edit ────────────────────────────┐
139+
│ Quality: ok (1.00) │
140+
│ Ready to edit: YES │
141+
│ │
142+
│ Best example: index.ts │
143+
└──────────────────────────────────────────────────────────────────────┘
144+
```
145+
146+
See `docs/cli.md` for the full CLI gallery.
99147

100148
## What It Actually Does
101149

@@ -135,43 +183,8 @@ getToken(): string {
135183

136184
Default output is lean — if the agent wants code, it calls `read_file`.
137185

138-
```json
139-
{
140-
"searchQuality": { "status": "ok", "confidence": 0.72 },
141-
"preflight": {
142-
"ready": false,
143-
"nextAction": "2 of 5 callers aren't in results — search for src/app.module.ts",
144-
"patterns": {
145-
"do": ["HttpInterceptorFn — 97%", "standalone components — 84%"],
146-
"avoid": ["constructor injection — 3% (declining)"]
147-
},
148-
"bestExample": "src/auth/auth.interceptor.ts",
149-
"impact": {
150-
"coverage": "3/5 callers in results",
151-
"files": ["src/app.module.ts", "src/boot.ts"]
152-
},
153-
"whatWouldHelp": [
154-
"Search for src/app.module.ts to cover the main caller",
155-
"Call get_team_patterns for auth/ injection patterns"
156-
]
157-
},
158-
"results": [
159-
{
160-
"file": "src/auth/auth.interceptor.ts:1-20",
161-
"summary": "HTTP interceptor that attaches auth token to outgoing requests",
162-
"score": 0.72,
163-
"type": "service:core",
164-
"trend": "Rising",
165-
"relationships": { "importedByCount": 4, "hasTests": true },
166-
"hints": {
167-
"callers": ["src/app.module.ts", "src/boot.ts"],
168-
"tests": ["src/auth/auth.interceptor.spec.ts"]
169-
}
170-
}
171-
],
172-
"relatedMemories": ["Always use HttpInterceptorFn (0.97)"]
173-
}
174-
```
186+
For scripting and automation, every CLI command accepts `--json` for machine output (stdout = JSON; logs/errors go to stderr).
187+
See `docs/capabilities.md` for the field reference.
175188

176189
Lean enough to fit on one screen. If search quality is low, preflight blocks edits instead of faking confidence.
177190

@@ -194,18 +207,18 @@ Record a decision once. It surfaces automatically in search results and prefligh
194207

195208
### All Tools
196209

197-
| Tool | What it does |
198-
| ------------------------------ | ------------------------------------------------------------------------------------------- |
199-
| `search_codebase` | Hybrid search + decision card. Pass `intent="edit"` to get `ready`, `nextAction`, patterns, caller coverage, and `whatWouldHelp`. |
200-
| `get_team_patterns` | Pattern frequencies, golden files, conflict detection |
210+
| Tool | What it does |
211+
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
212+
| `search_codebase` | Hybrid search + decision card. Pass `intent="edit"` to get `ready`, `nextAction`, patterns, caller coverage, and `whatWouldHelp`. |
213+
| `get_team_patterns` | Pattern frequencies, golden files, conflict detection |
201214
| `get_symbol_references` | Find concrete references to a symbol (usageCount + top snippets). `confidence: "syntactic"` = static/source-based only; no runtime or dynamic dispatch. |
202-
| `remember` | Record a convention, decision, gotcha, or failure |
203-
| `get_memory` | Query team memory with confidence decay scoring |
204-
| `get_codebase_metadata` | Project structure, frameworks, dependencies |
205-
| `get_style_guide` | Style guide rules for the current project |
206-
| `detect_circular_dependencies` | Import cycles between files |
207-
| `refresh_index` | Re-index (full or incremental) + extract git memories |
208-
| `get_indexing_status` | Progress and stats for the current index |
215+
| `remember` | Record a convention, decision, gotcha, or failure |
216+
| `get_memory` | Query team memory with confidence decay scoring |
217+
| `get_codebase_metadata` | Project structure, frameworks, dependencies |
218+
| `get_style_guide` | Style guide rules for the current project |
219+
| `detect_circular_dependencies` | Import cycles between files |
220+
| `refresh_index` | Re-index (full or incremental) + extract git memories |
221+
| `get_indexing_status` | Progress and stats for the current index |
209222

210223
## Evaluation Harness (`npm run eval`)
211224

@@ -229,7 +242,7 @@ npm run eval -- tests/fixtures/codebases/eval-controlled tests/fixtures/codebase
229242

230243
The retrieval pipeline is designed around one goal: give the agent the right context, not just any file that matches.
231244

232-
- **Definition-first ranking** - for exact-name lookups (e.g. a symbol name), the file that *defines* the symbol ranks above files that only use it.
245+
- **Definition-first ranking** - for exact-name lookups (e.g. a symbol name), the file that _defines_ the symbol ranks above files that only use it.
233246
- **Intent classification** - knows whether "AuthService" is a name lookup or "how does auth work" is conceptual. Adjusts keyword/semantic weights accordingly.
234247
- **Hybrid fusion (RRF)** - combines keyword and semantic search using Reciprocal Rank Fusion instead of brittle score averaging.
235248
- **Query expansion** - conceptual queries automatically expand with domain-relevant terms (auth → login, token, session, guard).
@@ -289,64 +302,72 @@ Structured filters available: `framework`, `language`, `componentType`, `layer`
289302

290303
## CLI Reference
291304

292-
All MCP tools are available as CLI commands — no AI agent required. Useful for scripting, debugging, and CI workflows.
305+
All MCP tools are available as CLI commands — no AI agent required. Useful for onboarding, scripting, debugging, and CI workflows.
306+
For formatted examples and “money shots”, see `docs/cli.md`.
293307

294308
Set `CODEBASE_ROOT` to your project root, or run from the project directory.
295309

296310
```bash
297311
# Search the indexed codebase
298-
npx codebase-context search --query "authentication middleware"
299-
npx codebase-context search --query "auth" --intent edit --limit 5
312+
npx -y codebase-context search --query "authentication middleware"
313+
npx -y codebase-context search --query "auth" --intent edit --limit 5
300314

301315
# Project structure, frameworks, and dependencies
302-
npx codebase-context metadata
316+
npx -y codebase-context metadata
303317

304318
# Index state and progress
305-
npx codebase-context status
319+
npx -y codebase-context status
306320

307321
# Re-index the codebase
308-
npx codebase-context reindex
309-
npx codebase-context reindex --incremental --reason "added new service"
322+
npx -y codebase-context reindex
323+
npx -y codebase-context reindex --incremental --reason "added new service"
310324

311325
# Style guide rules
312-
npx codebase-context style-guide
313-
npx codebase-context style-guide --query "naming" --category patterns
326+
npx -y codebase-context style-guide
327+
npx -y codebase-context style-guide --query "naming" --category patterns
314328

315329
# Team patterns (DI, state, testing, etc.)
316-
npx codebase-context patterns
317-
npx codebase-context patterns --category testing
330+
npx -y codebase-context patterns
331+
npx -y codebase-context patterns --category testing
318332

319333
# Symbol references
320-
npx codebase-context refs --symbol "UserService"
321-
npx codebase-context refs --symbol "handleLogin" --limit 20
334+
npx -y codebase-context refs --symbol "UserService"
335+
npx -y codebase-context refs --symbol "handleLogin" --limit 20
322336

323337
# Circular dependency detection
324-
npx codebase-context cycles
325-
npx codebase-context cycles --scope src/features
338+
npx -y codebase-context cycles
339+
npx -y codebase-context cycles --scope src/features
326340

327341
# Memory management
328-
npx codebase-context memory list
329-
npx codebase-context memory list --category conventions --type convention
330-
npx codebase-context memory list --query "auth" --json
331-
npx codebase-context memory add --type convention --category tooling --memory "Use pnpm, not npm" --reason "Workspace support and speed"
332-
npx codebase-context memory remove <id>
342+
npx -y codebase-context memory list
343+
npx -y codebase-context memory list --category conventions --type convention
344+
npx -y codebase-context memory list --query "auth" --json
345+
npx -y codebase-context memory add --type convention --category tooling --memory "Use pnpm, not npm" --reason "Workspace support and speed"
346+
npx -y codebase-context memory remove <id>
333347
```
334348

335349
All commands accept `--json` for raw JSON output suitable for piping and scripting.
336350

337-
## Tip: Ensuring your AI Agent recalls memory:
351+
## What to add to your CLAUDE.md / AGENTS.md
338352

339-
Add this to `.cursorrules`, `CLAUDE.md`, or `AGENTS.md`:
353+
Paste this into `.cursorrules`, `CLAUDE.md`, `AGENTS.md`, or wherever your AI reads project instructions:
340354

341-
```
342-
## Codebase Context
355+
```markdown
356+
## Codebase Context (MCP)
357+
358+
**Start of every task:** Call `get_memory` to load team conventions before writing any code.
343359

344-
**At start of each task:** Call `get_memory` to load team conventions.
360+
**Before editing existing code:** Call `search_codebase` with `intent: "edit"`. If the preflight card says `ready: false`, read the listed files before touching anything.
345361

346-
**When user says "remember this" or "record this":**
347-
- Call `remember` tool IMMEDIATELY before doing anything else.
362+
**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.
363+
364+
**When asked to "remember" or "record" something:** Call `remember` immediately, before doing anything else.
365+
366+
**When adding imports that cross module boundaries:** Call `detect_circular_dependencies` with the relevant scope after adding the import.
348367
```
349368

369+
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.
370+
350371
## Links
351372

352373
- [Motivation](./MOTIVATION.md) - Research and design rationale

‎docs/capabilities.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,15 @@ Technical reference for what `codebase-context` ships today. For the user-facing
44

55
## CLI Reference
66

7-
All 10 MCP tools are exposed as CLI subcommands. Set `CODEBASE_ROOT` or run from the project directory.
7+
All shipped capabilities are available locally via the CLI (human-readable by default, `--json` for automation).
8+
For a “gallery” of commands and examples, see `docs/cli.md`.
89

910
| Command | Flags | Maps to |
1011
|---|---|---|
1112
| `search --query <q>` | `--intent explore\|edit\|refactor\|migrate`, `--limit <n>`, `--lang <l>`, `--framework <f>`, `--layer <l>` | `search_codebase` |
1213
| `metadata` | — | `get_codebase_metadata` |
1314
| `status` | — | `get_indexing_status` |
14-
| `reindex` | `--incremental`, `--reason <r>` | `refresh_index` |
15+
| `reindex` | `--incremental`, `--reason <r>` | equivalent to `refresh_index` |
1516
| `style-guide` | `--query <q>`, `--category <c>` | `get_style_guide` |
1617
| `patterns` | `--category all\|di\|state\|testing\|libraries` | `get_team_patterns` |
1718
| `refs --symbol <name>` | `--limit <n>` | `get_symbol_references` |
@@ -95,8 +96,9 @@ Returned as `preflight` when search `intent` is `edit`, `refactor`, or `migrate`
9596
};
9697
bestExample?: string; // Top 1 golden file (path format)
9798
impact?: {
98-
coverage: string; // "X/Y callers in results"
99-
files: string[]; // Top 3 impact candidates (files importing results)
99+
coverage?: string; // "X/Y callers in results"
100+
files?: string[]; // Back-compat: top impact candidates (paths only)
101+
details?: Array<{ file: string; line?: number; hop: 1 | 2 }>; // When available
100102
};
101103
whatWouldHelp?: string[]; // Concrete next steps (max 4) when ready=false
102104
}
@@ -111,7 +113,8 @@ Returned as `preflight` when search `intent` is `edit`, `refactor`, or `migrate`
111113
- `patterns.avoid`: declining patterns, ranked by % (useful for migrations)
112114
- `bestExample`: exemplar file for the area under edit
113115
- `impact.coverage`: shows caller visibility ("3/5 callers in results" means 2 callers weren't searched yet)
114-
- `impact.files`: which files import the results (helps find blind spots)
116+
- `impact.details`: richer impact candidates with optional `line` and hop distance (1 = direct, 2 = transitive)
117+
- `impact.files`: back-compat list of impact candidate paths (when details aren’t available)
115118
- `whatWouldHelp`: specific next searches, tool calls, or files to check that would close evidence gaps
116119

117120
### How `ready` is determined

0 commit comments

Comments
 (0)