codebase-context exposes its tools as a local CLI so humans can follow the same map-first workflow the MCP server gives to agents:
- Get the bounded conventions map before exploring or editing (
map) - Search for the right local example after the map narrows the repo shape
- Onboard themselves onto an unfamiliar repo
- Debug what the MCP server is doing
- Use outputs in CI/scripts (via
--json)
Output depends on the repo you run it against. The examples below are illustrative (paths, counts, and detected frameworks will vary).
These commands use 2.4.0. If that version is not available on npm yet, use the published 2.2.0 setup guide.
These output examples come from an earlier CLI run; they were not captured from
2.4.0and do not verify an MCP connection.The commands below use
codebase-context@2.4.0and require Node.js 22 or newer. The CLI is intentionally single-project per invocation and targets one root viaCODEBASE_ROOTor the current working directory. MCP registration and project selection are covered in the client setup guide.
# CLI only: run from a repo root, or set CODEBASE_ROOT explicitly:
CODEBASE_ROOT=/path/to/repo npx -y codebase-context@2.4.0 status
# Commands that show --json in their help support machine output. Human mode is default.
npx -y codebase-context@2.4.0 patterns --jsonIf your terminal doesn’t render Unicode box-drawing cleanly:
CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.4.0 patternsmap— conventions map: architecture layers, patterns, golden filesmetadata— tech stack overviewpatterns— team conventions + adoption/trendssearch --query <q>— ranked results; add--intent editfor a preflight cardrefs --symbol <name>— concrete reference evidencecycles— circular dependency detectionstatus— index status/progressreindex— rebuild index (full or incremental)style-guide— find style guide sections in docsmemory list|add|remove— manage team memory (stored in.codebase-context/memory.json)- MCP client registration — use the 2.4.0 recipes in the client setup guide;
initis an interactive HTTP setup wizard with the limitations described there
Run these CLI commands from the project root. Build or refresh the local index first; the first run downloads a local model and indexes the repository; time depends on repository size, CPU and model. Then inspect the conventions map and search for the code you need:
npx -y codebase-context@2.4.0 reindex
npx -y codebase-context@2.4.0 map
npx -y codebase-context@2.4.0 search --query "auth middleware"This is the CLI preparation flow. It is separate from MCP client registration and does not by itself show that an MCP client connected successfully.
npx -y codebase-context@2.4.0 reindex
npx -y codebase-context@2.4.0 mapThe conventions map - run this first on an unfamiliar repo. It shows architecture layers, active patterns with adoption rates and trend direction, and the golden files the team treats as the strongest examples. This is also what the MCP server delivers to AI agents via the codebase://context resource on first call, before search narrows to a specific local example.
Example output (truncated):
┌─ Codebase Map ── angular-spotify ────────────────────────────────────┐
│ │
│ Architecture: feature-based · 3 layers │
│ 47 files · 6 patterns · 3 golden files │
│ │
│ LAYERS │
│ core/ – shared services + DI │
│ features/ – domain modules │
│ shared/ – reusable components │
│ │
│ TOP PATTERNS │
│ Angular standalone components 92% ↑ Rising │
│ RxJS reactive patterns 78% │
│ ↓ NgModules 8% Declining │
│ │
│ GOLDEN FILES │
│ src/features/player/player.component.ts │
│ src/core/auth/auth.service.ts │
│ │
└──────────────────────────────────────────────────────────────────────┘
npx -y codebase-context@2.4.0 metadataExample output:
┌─ codebase-context [monorepo] ────────────────────────────────────────┐
│ │
│ Framework: Angular unknown Architecture: mixed │
│ 130 files · 24,211 lines · 1077 components │
│ │
│ Dependencies: @huggingface/transformers · @lancedb/lancedb · │
│ @modelcontextprotocol/sdk · @typescript-eslint/typescript-estree · │
│ chokidar · fuse.js (+14 more) │
│ │
└──────────────────────────────────────────────────────────────────────┘
npx -y codebase-context@2.4.0 patternsExample output (truncated):
┌─ Team Patterns ──────────────────────────────────────────────────────┐
│ │
│ UNIT TEST FRAMEWORK │
│ USE: Vitest – 96% adoption │
│ alt CAUTION: Jest – 4% minority pattern │
│ │
│ STATE MANAGEMENT │
│ PREFER: RxJS – 63% adoption │
│ alt Redux-style store – 25% │
│ │
└──────────────────────────────────────────────────────────────────────┘
npx -y codebase-context@2.4.0 reindex
npx -y codebase-context@2.4.0 search --query "file watcher" --intent edit --limit 3Example output (truncated):
┌─ Search: "file watcher" ─── intent: edit ────────────────────────────┐
│ Quality: ok (1.00) │
│ Ready to edit: YES │
│ │
│ Best example: index.ts │
└──────────────────────────────────────────────────────────────────────┘
1. src/core/file-watcher.ts:44-74
confidence: ██████████ 1.18
typescript module in file-watcher.ts: startFileWatcher :: (...)
npx -y codebase-context@2.4.0 refs --symbol "startFileWatcher" --limit 10Example output (truncated):
┌─ startFileWatcher ─── 11 references ─── static analysis ─────────────┐
│ │
│ startFileWatcher │
│ │ │
│ ├─ file-watcher.test.ts:5 │
│ │ import { startFileWatcher } from '../src/core/file-watcher.... │
│ │
└──────────────────────────────────────────────────────────────────────┘
npx -y codebase-context@2.4.0 cycles --scope srcExample output:
┌─ Circular Dependencies ──────────────────────────────────────────────┐
│ │
│ No cycles found · 98 files · 260 edges · 2.7 avg deps │
│ │
└──────────────────────────────────────────────────────────────────────┘
npx -y codebase-context@2.4.0 statusExample output:
┌─ Index Status ───────────────────────────────────────────────────────┐
│ │
│ State: ready │
│ Root: /path/to/repo │
│ │
│ → Run `reindex` to re-index (`--incremental` skips unchanged). │
│ │
└──────────────────────────────────────────────────────────────────────┘
npx -y codebase-context@2.4.0 reindex
npx -y codebase-context@2.4.0 reindex --incremental --reason "changed watcher logic"MCP server mode: if you're running codebase-context as an MCP server (long-running process), the index auto-refreshes via a file watcher — you don't need to call
reindexbetween edits. Usereindexfor one-shot CLI runs or to force a full rebuild.
npx -y codebase-context@2.4.0 style-guide --query "naming"Example output:
No style guides found.
Hint: Try broader terms like 'naming', 'patterns', 'testing', 'components'
npx -y codebase-context@2.4.0 memory list
npx -y codebase-context@2.4.0 memory list --query "watcher"
npx -y codebase-context@2.4.0 memory add \
--type gotcha \
--category tooling \
--memory "Use pnpm, not npm" \
--reason "Workspace support and speed"
npx -y codebase-context@2.4.0 memory remove <id>