dev_map

Get a high-level overview of your codebase structure.

Overview

dev_map generates a hierarchical view of your repository showing:

Directory structure with component counts
Hot Paths — Most referenced files in the codebase
Change Frequency — Which directories are actively changing (v0.4+)
Exports — Public API with function signatures
Smart Depth — Adaptive expansion based on density

This helps AI assistants quickly understand codebase organization and activity.

Parameters

Parameter	Type	Default	Description
`depth`	number	`2`	Maximum depth (1-5)
`focus`	string	`""`	Focus on specific directory
`includeExports`	boolean	`true`	Show exported symbols
`includeHotPaths`	boolean	`true`	Show most referenced files
`includeChangeFrequency`	boolean	`false`	Show change frequency indicators ✨ v0.4
`smartDepth`	boolean	`false`	Adaptive depth based on density
`tokenBudget`	number	`2000`	Max tokens for output

Example Output

With Change Frequency (v0.4+)


# Codebase Map
 
## Hot Paths (most referenced)
1. `packages/core/src/indexer/index.ts` (RepositoryIndexer) - 47 refs
2. `packages/core/src/vector/store.ts` (AntflyVectorStore) - 32 refs
3. `packages/mcp-server/src/server/mcp-server.ts` (MCPServer) - 28 refs
 
## Directory Structure
 
└── packages/ (195 components)
    ├── 🔥 core/ (45 components) — 12 commits in 30d
    │   ├── src/ (42 components)
    │   │   └── exports: function search(query): Promise<Result[]>, class RepositoryIndexer
    │   └── dist/
    ├── ✏️ mcp-server/ (28 components) — 3 commits in 30d
    │   └── exports: class MCPServer, class SearchAdapter
    ├── 📝 cli/ (15 components) — 2 commits in 90d
    └── subagents/ (35 components)
 
**Total:** 195 indexed components across 24 directories

Change Frequency Indicators

Indicator	Meaning
🔥	Hot — 5+ commits in the last 30 days
✏️	Active — 1-4 commits in the last 30 days
📝	Recent — Commits in the last 90 days
(none)	No recent changes

Features

Hot Paths (PageRank)

Shows the most architecturally important files in your codebase, ranked by PageRank over the weighted dependency graph. Unlike simple reference counting, PageRank identifies files that are depended on by other important files — not just files with many direct imports.

Inspired by aider’s repo map .

Subsystems

Shows connected components in the dependency graph — groups of files that depend on each other, forming independent subsystems. Helps agents understand codebase boundaries.


Subsystems (3 connected):
  1. packages/core (45 files)
  2. packages/cli (12 files)
  3. packages/mcp-server (18 files)

Change Frequency ✨ v0.4

Shows which directories are actively being modified:


{
  "includeChangeFrequency": true
}

This helps AI assistants:

Identify areas under active development
Avoid conflicts with ongoing work
Understand project focus areas

Smart Depth

When enabled, expands directories with many components and collapses sparse ones:


{
  "smartDepth": true,
  "smartDepthThreshold": 10
}

Directories with ≥10 components get expanded
Sparse directories get collapsed
First 2 levels always shown

Focus Directory

Zoom into a specific part of the codebase:


{
  "focus": "packages/core/src",
  "depth": 4
}

Signatures in Exports

Exports show function/class signatures (truncated to 60 chars):


└── exports: function search(query, opts): Promise<Result[]>, class Indexer

Use Cases

Onboarding


Show me the overall structure of this codebase

Finding Entry Points


What are the main components in packages/mcp-server?

Understanding Architecture


Show the codebase map with hot paths to understand the core modules

Scoping Work


Focus on packages/core/src with depth 4 to see all scanner components

Tips

Start with default depth (2) for overview
Use focus to drill into specific areas
Enable smartDepth for large codebases
Hot paths reveal the most important code
Signatures help understand APIs without reading files

dev_refs — Query relationships for hot path files
dev_search — Search within focused area
dev_status — Check indexing completeness