Skip to content
Skills Library
Programming · Analysis

codemap

/codemap

Analyze codebase structure, dependencies, changes, cross-agent handoffs, and get code-aware intelligence. Use when user asks about project structure, where code is located, how files connect, what changed, how to resume work, before starting any coding task, when you need risk analysis and skill guidance, or when Codemap should tune project config before analysis.

Repository
codemap ↗
Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
3
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (3). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Analyze codebase structure, dependencies, changes, cross-agent handoffs, and get code-aware intelligence. Use when user asks about project structure, where code is located, how files connect, what changed, how to resume work, before starting any coding task, when you need risk analysis and skill guidance, or when Codemap should tune project config before analysis.

Original author description

Analyze codebase structure, dependencies, changes, cross-agent handoffs, and get code-aware intelligence. Use when user asks about project structure, where code is located, how files connect, what changed, how to resume work, before starting any coding task, when you need risk analysis and skill guidance, or when Codemap should tune project config before analysis.

How it works

  1. Commands
  2. First-Use Setup
  3. When to Use
  4. Hook Output
  5. Builtin Skills
  6. Output Interpretation
  7. MCP Tools
  8. HTTP API
Original SKILL.md headings · 178 lines, 1,213 words
SKILL.md preview
---
name: codemap
description: Analyze codebase structure, dependencies, changes, cross-agent handoffs, and get code-aware intelligence. Use when user asks about project structure, where code is located, how files connect, what changed, how to resume work, before starting any coding task, when you need risk analysis and skill guidance, or when Codemap should tune project config before analysis.
---

# 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 find "<query>"          # Where is X defined (names first, then body text); grep exact symptoms
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 skill export <dir>      # Write every builtin as <dir>/<name>/SKILL.md for a host
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 .`)
- `⭐️ name ←N` marks a hub: N files import it (a Go package is marked on its directory); the legend under the tree says so
- `hooks.go 2535L` is the file's line count, shown at 100+ lines; read a range instead of the whole file
- `x.go (+3 tests)` folds same-directory tests into their source; `+N other tests` counts tests with no source beside them (a `tests/` dir lists its files)
- `page-*.yml ×9` collapses 4+ siblings that differ only in numbers or hashes; `dir/ (untracked, N files, SIZE)` is a wholly untracked directory
- Directories flattened when containing single subdirectory; a directory holding one file prints as `dir/FILE`
- After the tree: the legend, then `Hubs (top 10 of N, by importers):` with one hub per line (`←73  scanner/`, full path, line count when 100+), then the next commands

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

Versions

RepositoryScoreLicence
This page · jordancoin/codemap100MIT
AZidan/archflow100MIT
alvinunreal/oh-my-opencode-slim100MIT
jordancoin/codemap100MIT
ils15/copilot-global-config100MIT
azidan/codemap100MIT
ialameh/sift-coder100MIT
jellydn/my-ai-tools96MIT
QDinvest/Code-Map-QD96MIT

Database snapshot: 13.11.2026 · package version 82248ac20991 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90explore
    Systematic codebase exploration using codemap's analysis tools. Use when understanding how code works, tracing dependencies, or onboarding to a new area.
  • 100project-analyze
    This skill should be used when the user asks to "analyze project structure", "explain this codebase", "show dependencies", "find high-risk files", "assess refactor impact", "understand architecture", or run ProjectMind for local codebase analysis.
  • 100codemap-export
    Use to export the codemap as machine-readable JSON for downstream tooling. Same data as /codemap, different format. "Export the codemap", "give me the codemap as JSON".
  • 90rc-codemap
    Builds and refreshes per-directory codemap.md as a cheap structure map. Use before exploring a large repo. Do not use to trace one bug.
  • 100config-setup
    Set up or tune .codemap/config.json so Codemap focuses on code-relevant parts of the repo. Use when config is missing, boilerplate, noisy, or mismatched to the stack.
  • 100codemap-refresh
    Use when code has changed since codemap files were generated and the user wants them brought up to date: "refresh", "update the diagrams", "docs are stale". Detects which docs/codemap files are outdated and regenerates only those, preserving manual edits.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.