Codemap

Codemap gives you instant architectural context about any codebase. It classifies your intent, detects risk, matches relevant skills, and tracks your working set — all automatically via hooks.

Codemap should also keep its own per-project config healthy. On first use in a repo, or when output is obviously noisy, tune .codemap/config.json before doing deeper analysis so future calls stay code-first instead of asset-first.

Commands

codemap .                       # Project structure and top files
codemap --deps                  # Dependency flow (imports/functions/hubs)
codemap --diff                  # Changes vs main branch
codemap --diff --ref <branch>   # Changes vs specific branch
codemap --importers <file>      # Who imports this file? Is it a hub?
codemap handoff .               # Build + save handoff artifact
codemap handoff --latest .      # Read latest saved handoff
codemap handoff --json .        # Machine-readable handoff payload
codemap skill list              # Show available skills with descriptions
codemap skill show <name>       # Get full skill instructions
codemap skill init              # Create custom skill template
codemap config show             # Show current project config
codemap context                 # Universal JSON context envelope
codemap context --for "prompt"  # With pre-classified intent + matched skills
codemap context --compact       # Minimal for token-constrained agents
codemap serve --port 9471       # HTTP API for non-MCP integrations

First-Use Setup

Before deeper Codemap analysis in a repo:

1. Check .codemap/config.json.
2. If it is missing, clearly boilerplate, or obviously too noisy for the stack, run codemap skill show config-setup and follow it.
3. After writing or improving config, rerun codemap . and codemap --deps.

Treat config as repo memory. Once tuned, future Codemap calls should benefit automatically.

Signals that config needs setup or tuning:

• .codemap/config.json is missing
• config only contains generic auto-detected only values with no real project shaping
• large non-code directories dominate the tree output
• stack-specific noise is overwhelming source structure (.xcassets, screenshots, PDFs, training-data, fixtures, generated files, models, vendor directories)
• the repo stack is obvious, but the config does not reflect it

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

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
• 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

ALWAYS run codemap --importers <file> when:

• About to edit a file — check if it's a hub
• Need to know the blast radius of a change
• Deciding whether to refactor or leave alone

Run codemap skill show <name> when:

• The prompt-submit hook shows matched skills in <!-- codemap:skills [...] -->
• You need guidance for a specific task (hub editing, refactoring, testing)
• Risk level is medium or high

Run codemap skill show config-setup when:

• The repo has no .codemap/config.json
• The config looks like a bare bootstrap and not a real project policy
• Codemap output is cluttered by large non-code directories
• You want Codemap to make better future decisions for this specific repo

Run codemap context when:

• Piping codemap intelligence to another tool
• Need a structured JSON summary of the project state
• Building automation that consumes code-aware context

Run codemap handoff when:

• Switching between agents (Claude, Codex, Cursor)
• Resuming work after a break
• User asks "what should the next agent know?"

Hook Output

The prompt-submit hook fires on every message and provides:

<!-- codemap:intent {"category":"refactor","risk":"high",...} -->
<!-- codemap:skills [{"name":"hub-safety","score":5},...] -->
Skills matched: hub-safety, refactor — run `codemap skill show <name>` for guidance

• Intent categories: refactor, bugfix, feature, explore, test, docs
• Risk levels: low (no hubs), medium (1 hub), high (2+ hubs or 8+ importers)
• Skills are pull-based: only names are shown, run codemap skill show for full body

Builtin Skills

Skill	When to Pull
config-setup	Missing, boilerplate, or noisy .codemap/config.json
hub-safety	Editing files imported by 3+ others
refactor	Restructuring, renaming, moving code
test-first	Writing tests, TDD workflows
explore	Understanding how code works
handoff	Switching between AI agents

Output Interpretation

Tree View (codemap .)

• Stars (⭐) indicate top 5 largest source files
• Directories flattened when containing single subdirectory

Dependency Flow (codemap --deps)

• External dependencies grouped by language
• Internal import chains showing how files connect
• HUBS section shows most-imported files (3+ importers)

Diff Mode (codemap --diff)

• (new) = untracked, ✎ = modified, (+N -M) = lines changed
• Warning icons show hub files (high impact)

Importers (codemap --importers <file>)

• Shows all files that import this file
• Flags hub status (3+ importers = high impact)

Context Envelope (codemap context)

• JSON with project metadata, intent, working set, matched skills, handoff ref
• --compact strips skills and limits working set for token savings

MCP Tools

If codemap MCP server is configured, these tools are available:

Tool	Use For
get_structure	Project tree
get_dependencies	Dependency flow + hubs
get_diff	Changed files with impact
find_file	Search by filename
get_importers	Who imports a file
get_hubs	List all hub files
get_file_context	Full context for one file
get_handoff	Build/read handoff artifact
get_working_set	Files edited this session
list_skills	Available skills (metadata)
get_skill	Full skill instructions
get_activity	Recent coding activity
start_watch / stop_watch	Control daemon
status	Verify MCP connection
list_projects	Discover projects

HTTP API

When codemap serve is running:

Endpoint	Returns
GET /api/context?intent=...	Context envelope
GET /api/skills	All skills metadata
GET /api/skills/<name>	Full skill body
GET /api/working-set	Current working set
GET /api/health	Server health