kingbootoshi/cartographer
Overview
This skill maps and documents codebases of any size by orchestrating parallel subagents to read and analyze files and then synthesizing their reports into a single CODEBASE_MAP.md. It creates or updates docs/CODEBASE_MAP.md with architecture diagrams, file purposes, dependencies, and navigation guides, and appends a short summary to CLAUDE.md. The orchestrator delegates file reading to Sonnet subagents and only synthesizes their structured outputs.
How this skill works
The orchestrator scans the repo to produce a token-aware file tree and plans subagent assignments balancing ~150k-token chunks. It spawns Sonnet subagents in parallel to read specified file groups and return structured markdown analyses. Finally, it merges and deduplicates subagent reports, produces architecture diagrams, writes docs/CODEBASE_MAP.md, and updates CLAUDE.md with a brief summary.
When to use it
- Onboarding to a new or unfamiliar project
- When you need a high-level architecture overview and navigation guide
- Before making large changes or refactors to understand dependencies
- To generate or refresh documentation for maintenance or audits
- When you need a focused update after recent code changes
Best practices
- Always run the scanner first to get token counts and skipped-file info
- Group files by logical module and balance token budgets (~150k tokens per subagent)
- Spawn all Sonnet subagents in a single orchestration step to run them in parallel
- Use git diffs or scanner comparisons to update only changed modules
- Keep the map in docs/CODEBASE_MAP.md and update CLAUDE.md with a 2–3 sentence summary
Example use cases
- Generate a complete CODEBASE_MAP.md for a medium or large monorepo before onboarding
- Update the codebase map after merging a feature that touches multiple modules
- Produce a quick architectural diagram and navigation guide prior to a refactor
- Identify cross-cutting gotchas and dependency hotspots before a security review
- Create task-specific guides (e.g., add API endpoint, modify auth) for new contributors
FAQ
The orchestrator plans and synthesizes work; Sonnet subagents read files and return structured analyses. The orchestrator must never read files directly.
How does it detect whether to update the map?
It checks docs/CODEBASE_MAP.md frontmatter for last_mapped, then uses git logs since that timestamp or rescans and compares file lists/token counts to find meaningful changes.
What if the scanner fails due to missing tiktoken?
Install tiktoken (pip3 install tiktoken) or run the scanner via the provided uv run wrapper which auto-installs dependencies in an isolated environment.
