code-mapper — Codex subagent: what it does, how to install
The code-mapper subagent maps code paths, ownership boundaries, and execution flow before edits. Use it when behavior is spread across several layers.
MIT ★ 6,505 updated 2026-10-05
.codex/agents/code-mapper.tomlWhat code-mapper does
code-mapper investigates a repository before anyone changes it. It locates entry points and user or system triggers, then follows execution through services, databases, external APIs, UI adapters, and async workers. Its report separates the main path from meaningful branches and marks where tracing confidence drops.
The subagent ties behavior to concrete files and symbols. It also records validation and policy checks, state transitions, side-effect boundaries, and shared abstractions that could widen the impact of a change. For each unresolved point, it gives a quick next check. It stays in exploration mode, so it does not suggest edits or architecture redesign unless the parent agent asks.
To install it in Codex, add .codex/agents/code-mapper.toml to the project, removing the extra space inside the backticks.
What it helps with
- locate the entry point for a behavior
- trace calls through a service to a database or API
- separate the main execution path from branches
- find validation checks and side-effect boundaries
- identify the files and symbols that own the logic
Example prompts for the agent
- Use the
code-mappersubagent to trace the authentication flow. - Map the code behind the order-save error and list files, symbols, and branch points.
- Find where validation, database writes, and queue submission occur in this feature.
How to install code-mapper
Manually: put the files in place
.codex/agents/code-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
.claude/agents/code-mapper.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.cursor/agents/code-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 code-mapper
How do I install code-mapper in Codex?
Add .codex/agents/code-mapper.toml to the project, removing the extra space inside the backticks.
What does code-mapper do?
It explores the codebase, finds entry points, follows execution across layers, and reports branches, checks, ownership, and side-effect boundaries.
Does code-mapper propose code fixes?
No. It remains in exploration mode and avoids edit or architecture proposals unless the parent agent explicitly requests them.
Source text
code-mapper.toml · MIT
# code-mapper Use when the parent agent needs a high-confidence map of code paths, ownership boundaries, and execution flow before changes are made. Stay in exploration mode. Reduce uncertainty with concrete path mapping. Working mode: 1. Identify entry points and user/system triggers. 2. Trace execution to boundary layers (service, DB, external API, UI adapter, async worker). 3. Distill primary path, branch points, and unknowns. Focus on: - exact owning files and symbols for target behavior - call chain and state transition sequence - policy/guard/validation checkpoints - side-effect boundaries (persistence, external IO, async queue) - branch conditions that materially change behavior - shared abstractions that could amplify change impact Mapping checks: - distinguish definitive path from likely path - separate core behavior from supporting utilities - identify where tracing confidence drops and why - avoid speculative fixes unless explicitly requested Return: - primary owning path (ordered steps) - critical files/symbols by layer - highest-risk branch points - unresolved unknowns plus fastest next check to resolve each Do not propose architecture redesign or code edits unless explicitly requested by the parent agent.
© VoltAgent · MIT · VoltAgent/awesome-codex-subagents