Codemap is an opinionated, token-conscious source-inspection CLI for Python and TypeScript/JavaScript. It orchestrates Codebase Memory MCP, rg, and ast-grep behind a compact command surface.
Codemap chooses the appropriate evidence source and shapes the results around an agent's next action.
- Keeps graph, exact-text, and structural evidence clearly labeled.
- Filters, ranks, and deduplicates results to surface the next useful inspection.
- Keeps output compact and predictable instead of exposing provider payloads.
- Falls back to local evidence when Codebase Memory is unavailable, partial, or stale.
- Refreshes graph data explicitly without adding persistent artifacts to inspected repositories.
Use Codemap for normal repository navigation and change scoping. Use direct Codebase Memory queries when unrestricted graph exploration or provider-specific diagnostics matter more than compact defaults.
Node.js 22.12+ is required. Commands below use npm; equivalent pnpm commands also work.
| Tool | Role | Setup |
|---|---|---|
| Codebase Memory MCP | Relationships, architecture, semantic search, and change impact | Install the external codebase-memory-mcp binary |
| ripgrep | Exact-text search and fast file discovery | Install the external rg binary |
| ast-grep | Structural search and source parsing | JavaScript, TypeScript, and Python engines bundled; CLI optional for advanced operations outside Codemap |
Install the external tools on macOS for full coverage:
brew install ripgrep ast-grep
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup.sh | bashBuild and link Codemap:
npm install
npm run build
npm install -g .Verify the full setup:
codebase-memory-mcp --version
rg --version
ast-grep --version
codemap --version
codemap --help| Command | Primary evidence | Purpose |
|---|---|---|
summary |
Current-tree README, language mix, package manifests, imports, and public exports, enriched by Codebase Memory | Focused orientation through README purpose and outline, language percentages, a compact package- or feature-level repository skeleton, call-share hotspots, cohesive clusters, and an at-most-three-level hierarchy of public surfaces selected by entry position, import reach, and breadth, with directly exposed modules and defining exports. |
search <text> |
Current-tree paths, exact definitions and text, and decisive locally cohesive multi-term source candidates; then Codebase Memory ranked search and local fallback | Broad path, concept, symbol, and text discovery. |
search --graph <text> |
Codebase Memory graph search, then current-tree graph fallback | Relationship-aware discovery. |
search --semantic <text> |
Exact current-tree definition, then Codebase Memory semantic graph search and current-tree fallback | Vocabulary-bridging discovery without hiding an exact implementation owner. |
search calls <name> |
ast-grep | Call-shaped source matches across the bundled language parsers. |
search match / search rule |
ast-grep | Built-in JavaScript, TypeScript, and Python structural discovery. |
inspect <target> |
Codebase Memory for symbols, current tree for paths and fallback | Focused in-to-out neighborhood inspection. |
signals |
Codebase Memory function metrics plus current-tree definitions | Ranked source metrics under the shared output ceiling. |
backend ... |
Raw Codebase Memory diagnostics | Projects, status, schema, Cypher queries, and change impact. |
index |
Codebase Memory indexing | Explicit refresh timing and status. |
Every command applies one final approximate 10,000-token ceiling after selection and rendering. Text keeps complete lines and reports shown, total, and truncated counts. JSON remains one valid minified value and reports truncation on stderr. Search returns at most 15 matches by default; use --limit to override that selection or --max-rows on backend queries.
Codemap provides syntax-level and indexed relationship evidence, not compiler-grade reachability, framework-complete data flow, or proof that a symbol is dead. Verify consequential findings with focused reads, exact search, and the repository’s tests.
Implementation constraints and future evaluation criteria are recorded in docs/IDEAS.md.