---
name: jordancoin/codemap
source: https://app.decimal.ai/s/jordancoin-codemap@1/SKILL.md
source_sha256: 853c332e9576
---

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