codemap

Original：🇺🇸 English
Translated

Analyze codebase structure, dependencies, changes, and cross-agent handoffs. Use when user asks about project structure, where code is located, how files connect, what changed, how to resume work, or before starting any coding task.

18installs
Sourcejordancoin/codemap
Added on

NPX Install

npx skill4agent add jordancoin/codemap codemap

Tags

Translated version includes tags in frontmatter
codemap-toolcodebase-analysisdependency-trackingcode-diffagent-handoff

SKILL.md Content

View Translation Comparison →

Codemap

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

Commands

bash
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.