/cartographer

name: cartographer
description: Maps and documents codebases of any size by orchestrating parallel subagents. Creates docs/CODEBASE_MAP.md with architecture, file purposes, dependencies, and navigation guides. Updates CLAUDE.md with a summary. Use when user says "map this codebase", "cartographer", "/cartographer", "create codebase map", "document the architecture", "understand this codebase", or when onboarding to a new project. Automatically detects if map exists and updates only changed sections.

Cartographer

Maps codebases of any size using parallel Sonnet subagents.

**CRITICAL: Opus orchestrates, Sonnet reads.** Never have Opus read codebase files directly. Always delegate file reading to Sonnet subagents - even for small codebases. Opus plans the work, spawns subagents, and synthesizes their reports.

Quick Start

1. Run the scanner script to get file tree with token counts 2. Analyze the scan output to plan subagent work assignments 3. Spawn Sonnet subagents in parallel to read and analyze file groups 4. Synthesize subagent reports into `docs/CODEBASE_MAP.md` 5. Update `CLAUDE.md` with summary pointing to the map

Workflow

Step 1: Check for Existing Map

First, check if `docs/CODEBASE_MAP.md` already exists:

**If it exists:** 1. Read the `last_mapped` timestamp from the map's frontmatter 2. Check for changes since last map:

• Run `git log --oneline --since="<last_mapped>"` if git available
• If no git, run the scanner and compare file counts/paths

3. If significant changes detected, proceed to update mode 4. If no changes, inform user the map is current

**If it does not exist:** Proceed to full mapping.

Step 2: Scan the Codebase

Run the scanner script to get an overview. Try these in order until one works:

# Option 1: UV (preferred - auto-installs tiktoken in isolated env)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/cartographer/scripts/scan-codebase.py . --format json

# Option 2: Direct execution (requires tiktoken installed)
${CLAUDE_PLUGIN_ROOT}/skills/cartographer/scripts/scan-codebase.py . --format json

# Option 3: Explicit python3
python3 ${CLAUDE_PLUGIN_ROOT}/skills/cartographer/scripts/scan-codebase.py . --format json

**Note:** The script uses UV inline script dependencies. When run with `uv run`, tiktoken is automatically installed in an isolated environment - no global pip install needed.

If not using UV and tiktoken is missing:

pip install tiktoken
# or
pip3 install tiktoken

The output provides:

• Complete file tree with token counts per file
• Total token budget needed
• Skipped files (binary, too large)

Step 3: Plan Subagent Assignments

Analyze the scan output to divide work among subagents:

**Token budget per subagent:** ~150,000 tokens (safe margin under Sonnet's 200k context limit)

**Grouping strategy:** 1. Group files by directory/module (keeps related code together) 2. Balance token counts across groups 3. Aim for more subagents with smaller chunks (150k max each)

**For small codebases (<100k tokens):** Still use a single Sonnet subagent. Opus orchestrates, Sonnet reads - never have Opus read the codebase directly.

**Example assignment:**

Subagent 1: src/api/, src/middleware/ (~120k tokens)
Subagent 2: src/components/, src/hooks/ (~140k tokens)
Subagent 3: src/lib/, src/utils/ (~100k tokens)
Subagent 4: tests/, docs/ (~80k tokens)

Step 4: Spawn Sonnet Subagents in Parallel

Use the Task tool with `subagent_type: "Explore"` and `model: "sonnet"` for each group.

**CRITICAL: Spawn all subagents in a SINGLE message with multiple Task tool calls.**

Each subagent prompt should: 1. List the specific files/directories to read 2. Request analysis of:

• Purpose of each file/module
• Key exports and public APIs
• Dependencies (what it imports)
• Dependents (what imports it, if discoverable)
• Patterns and conventions used
• Gotchas or non-obvious behavior

3. Request output as structured markdown

**Example subagent prompt:**

You are mapping part of a codebase. Read and analyze these files:
- src/api/routes.ts
- src/api/middleware/auth.ts
- src/api/middleware/rateLimit.ts
[... list all files in this group]

For each file, document:
1. **Purpose**: One-line description
2. **Exports**: Key functions, classes, types exported
3. **Imports**: Notable dependencies
4. **Patterns**: Design patterns or conventions used
5. **Gotchas**: Non-obvious behavior, edge cases, warnings

Also identify:
- How these files connect to each other
- Entry points and data flow
- Any configuration or environment dependencies

Return your analysis as markdown with clear headers per file/module.

Step 5: Synthesize Reports

Once all subagents complete, synthesize their outputs:

1. **Merge** all subagent reports 2. **Deduplicate** any overlapping analysis 3. **Identify cross-cutting concerns** (shared patterns, common gotchas) 4. **Build the architecture diagram** showing module relationships 5. **Extract key navigation paths** for common tasks

Step 6: Write CODEBASE_MAP.md

**CRITICAL: Get the actual timestamp first!** Before writing the map, fetch the current time:

date -u +"%Y-%m-%dT%H:%M:%SZ"

Use this exact output for both the frontmatter `last_mapped` field and the header text. Never estimate or hardcode timestamps.

Create `docs/CODEBASE_MAP.md` using this structure:

---
last_mapped: YYYY-MM-DDTHH:MM:SSZ
total_files: N
total_tokens: N
---

# Codebase Map

> Auto-generated by Cartographer. Last mapped: [date]

## System Overview

[Mermaid diagram showing high-level architecture]

```mermaid
graph TB
    subgraph Client
        Web[Web App]
    end
    subgraph API
        Server[API Server]
        Auth[Auth Middleware]
    end
    subgraph Data
        DB[(Database)]
        Cache[(Cache)]
    end
    Web --> Server
    Server --> Auth
    Server --> DB
    Server --> Cache

[Adapt the above to match the actual architecture]

Directory Structur