cartographer
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.
npx skills add majiayu000/claude-skill-registry --skill cartographer --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Cartographer Maps codebases of any size using parallel Sonnet subagents with 1M token context windows. **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
- Quick Start
- Workflow
- Step 1: Check for Existing Map
- Step 2: Scan the Codebase
- Step 3: Plan Subagent Assignments
- Step 4: Spawn Sonnet Subagents in Parallel
- Step 5: Synthesize Reports
- Step 6: Write CODEBASEMAP.md
- Step 7: Update CLAUDE.md
- Update Mode
- Token Budget Reference
- Troubleshooting
Option 1: If uv is available (preferred) uv run .claude/skills/cartographer/scripts/scan-codebase.py . --format json Option 2: Direct execution (uses shebang) Option 3: Explicit python3 python3 .claude/skills/cartographer/scripts/scan-codebase.py . --format json Option 4: Explicit python (some systems) python .claude/skills/cartographer/scripts/scan-codebase.py . --format json With uv (if available) uv pip install tiktoken Or standard pip
What does the cartographer skill do?
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.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill cartographer --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.