Skip to main content
subagent CX Codex

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

Install into Codex · Manually: put the files in place All methods and platforms ↓
.codex/agents/code-mapper.toml
Open on GitHub

What 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-mapper subagent 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.toml

Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/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

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set176

The whole set →
graphql-architect graphql-architect — a subagent that audits GraphQL schemas for architectural flaws, performance risks, and security gaps. Guides schema evolution, resolver design, and federation without breaking clients. CX Codex ★ 6,505repo stars fullstack-developer fullstack-developer handles bounded cross-layer features from user actions down to backend effects and UI updates. Useful when a single worker needs to own the full integration path. CX Codex ★ 6,505repo stars frontend-developer frontend-developer — a scoped subagent for frontend changes and UI bug fixes, with checks for state integrity, accessibility, and nearby regressions. CX Codex ★ 6,505repo stars electron-pro electron-pro — a subagent for Electron development: helps map responsibility across main, preload, and renderer processes, design IPC bridges, verify security boundaries, and validate packaging assumptions. CX Codex ★ 6,505repo stars design-bridge design-bridge converts DESIGN.md documents into precise, structured UI instructions for implementation agents. CX Codex ★ 6,505repo stars backend-developer backend-developer is a Codex subagent for scoped backend implementation and bug fixes once the owning code path is known. It checks a success case and a high-risk failure path. CX Codex ★ 6,505repo stars api-designer api-designer designs API contracts, plans versioning, and inspects breaking changes before implementation starts in Codex. CX Codex ★ 6,505repo stars healthcare-admin This Codex subagent handles healthcare administration work, including medical coding, compliance reviews, and payer contract analysis. Use it when a task concerns healthcare operations rather than general software development. CX Codex ★ 6,505repo stars

Project sponsors

Companies that keep this analytics open