codemap

# 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 ```bash 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 |