Codemap

Codemap gives you instant architectural context about any codebase. Use it proactively before exploring or modifying code.

Commands

codemap . # Project structure and top files codemap --deps # Dependency flow (imports/functions) codemap --diff # Changes vs main branch codemap --diff --ref <branch> # Changes vs specific branch codemap handoff . # Build + save handoff artifact codemap handoff --latest . # Read latest saved handoff codemap handoff --json . # Machine-readable handoff payload codemap handoff --since 2h . # Limit timeline lookback when building codemap handoff --prefix . # Stable prefix snapshot only codemap handoff --delta . # Recent delta snapshot only codemap handoff --detail a.go . # Lazy-load full detail for one changed file

When to Use

ALWAYS run codemap . when:

• Starting any new task or feature

• User asks "where is X?" or "what files handle Y?"

• User asks about project structure or organization

• You need to understand the codebase before making changes

• Exploring unfamiliar code

ALWAYS run codemap --deps when:

• User asks "how does X work?" or "what uses Y?"

• Refactoring or moving code

• Need to trace imports or dependencies

• Evaluating impact of changes

• Finding hub files (most-imported)

ALWAYS run codemap --diff when:

• User asks "what changed?" or "what did I modify?"

• Reviewing changes before commit

• Summarizing work done on a branch

• Assessing what might break

• Use --ref <branch> when comparing against something other than main

ALWAYS run codemap handoff when:

• Handing work from one agent to another (Claude, Codex, MCP client)

• Resuming work after a break and you want a compact recap

• User asks "what should the next agent know?"

• You want a durable summary in .codemap/handoff.latest.json

Output Interpretation

Tree View (codemap . )

• Shows file structure with language detection

• Stars (★) indicate top 5 largest source files

• Directories are flattened when empty (e.g., src/main/java )

Dependency Flow (codemap --deps )

• External dependencies grouped by language

• Internal import chains showing how files connect

• HUBS section shows most-imported files

• Function counts per file

Diff Mode (codemap --diff )

• (new) = untracked file

• ✎ = modified file

• (+N -M) = lines added/removed

• Warning icons show files imported by others (impact analysis)

Handoff (codemap handoff )

• layered output: prefix (stable hubs/context) + delta (recent changed-file stubs + timeline)

• changed file transport uses stubs (path , hash , status , size ) for lower context cost

• risk_files highlights high-impact changed files when dependency context is available

• includes deterministic hashes (prefix_hash , delta_hash , combined_hash ) and cache metrics

• --latest reads saved artifact without rebuilding

Daemon and Hooks

• With daemon state: handoff includes richer timeline and better risk context.

• Without daemon state: handoff still works using git-based changed files.

• Hook behavior:

• session-stop writes .codemap/handoff.latest.json

• session-start may show recent handoff summary (24h freshness window)

• session-start structure output is capped/adaptive for large repos

Examples

User asks: "Where is the authentication handled?" Action: Run codemap . then codemap --deps to find auth-related files and trace their connections.

User asks: "What have I changed on this branch?" Action: Run codemap --diff to see all modifications with impact analysis.

User asks: "How does the API connect to the database?" Action: Run codemap --deps to trace the import chain from API to database files.

User asks: "I want to refactor the utils module" Action: Run codemap --deps first to see what depends on utils before making changes.

User asks: "I'm switching to another agent, what should I pass along?" Action: Run codemap handoff . and share the summary (or --json for tools).

User asks: "I just came back, what was in progress?" Action: Run codemap handoff --latest . and continue from that state.