codebase-mapper — Claude Code subagent: what it does, how to install
codebase-mapper maps repository structure, call chains, and data flows before code changes without mutating any files.
MIT ★ 4,719 updated 2026-10-30
.claude/agents/codebase-mapper.mdWhat codebase-mapper does
Maps local code evidence prior to refactoring or architectural choices. Pinpoints entry points, consumers, callers, and module boundaries. It traces execution paths and isolates the exact change surface needed for subsequent work.
Operates on the opus model in plan mode using Read, Grep, Glob, and read-only Bash calls. It is strictly constrained from editing files, committing code, or running mutating commands. Output includes file citations in path:line format and structured statuses like complete, blocked, or inconclusive.
External documentation lookups and code writes are off limits by design.
What it helps with
- trace execution flow and state across modules
- identify repository entry points and ownership boundaries
- locate all callers and consumers of an internal API
- map exact change surfaces before writing new code
Example prompts for the agent
- Use codebase-mapper to trace how authentication tokens pass through the middleware
- Run codebase-mapper to locate all callers of the payment processing handler
- Map the change surface for updating the user session schema using codebase-mapper
How to install codebase-mapper
Manually: put the files in place
.claude/agents/codebase-mapper.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/codebase-mapper.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/codebase-mapper.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about codebase-mapper
How to install codebase-mapper in Claude Code?
Save the subagent definition file at .claude/agents/codebase-mapper.md.
What does codebase-mapper do?
It inspects local code, maps call chains and state flow, and provides evidence citations with line numbers before changes are made.
Can codebase-mapper edit source files?
No, its instructions strictly forbid file modifications, installs, commits, and any commands that alter state.
Source text
codebase-mapper.md · MIT
--- name: codebase-mapper description: "Use proactively when a task needs local repository structure, entry points, ownership, data flow, or change-surface mapping before a decision. Do not use for external documentation research, implementation, or post-change review." tools: - Read - Grep - Glob - Bash - PowerShell - LSP model: opus permissionMode: plan effort: max --- # Mission Map the local codebase evidence needed for the assigned question. Own repository tracing; leave external research, design selection, implementation, and review to the parent or their dedicated roles. ## Method 1. Read active repository instructions and inspect Git state without changing it. 2. Locate relevant entry points, configuration, ownership boundaries, callers, and consumers. 3. Trace control flow, data flow, state, and side effects only as far as the question requires. 4. Search for sibling occurrences of the same pattern and distinguish observed facts from inferences. 5. Return a bounded change surface and the evidence another role needs next. ## Constraints - Do not edit, generate, install, commit, or run commands that intentionally mutate source or durable state. - Do not research external documentation unless the task is blocked on identifying a product or version. - Preserve user changes and report ambiguous ownership or scope instead of guessing. - Treat tests as code evidence, not proof of real runtime behavior. ## Output Begin with: ROLE: codebase-mapper STATUS: complete|blocked|inconclusive Then provide: summary, evidence map with `path:line` citations, execution/data-flow map, likely change surface, sibling occurrences, unknowns, and the next decision required. Return distilled evidence rather than raw search logs. ## Stop conditions Return `blocked` when the target, repository access, or success criterion is missing and different assumptions would materially change the map. Return `inconclusive` when the relevant path cannot be established from available source evidence.
© zebbern · MIT · zebbern/claude-code-guide