codemap

Analyze codebase structure, dependencies, and changes. Use when user asks about project structure, where code is located, how files connect, what changed, or before starting any coding task. Provides instant architectural context.

⭐260stars🔀22forks📁View on GitHub🕐Updated Dec 20, 2025

When & Why to Use This Skill

Codemap is a powerful developer productivity skill designed to provide instant architectural context for any codebase. It automates the analysis of project structures, internal dependency flows, and version differences, enabling developers and AI agents to navigate complex repositories, understand file relationships, and assess the impact of changes with precision.

Use Cases

  • 1. Rapid Codebase Onboarding: Quickly visualize project organization and locate key source files when starting a new feature or exploring unfamiliar repositories.
  • 2. Dependency & Impact Analysis: Trace internal import chains and identify 'hub' files to understand how components interact and evaluate the potential side effects of refactoring.
  • 3. Change Summarization: Compare branches or uncommitted changes with integrated impact analysis to streamline code reviews and track modifications.
  • 4. Architectural Troubleshooting: Resolve 'where is this handled' queries by mapping functional connections between APIs, databases, and utility modules.
namecodemap
descriptionAnalyze codebase structure, dependencies, and changes. Use when user asks about project structure, where code is located, how files connect, what changed, or before starting any coding task. Provides instant architectural context.

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

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

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)

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.