Skip to content

subagentWorkflow

Codebase Mapper

Read-only subagent that maps an unfamiliar repo: modules, entry points, data flow, and where to start reading, in a one-page guide.

npx workspacetemplates add codebase-mapper --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/codebase-mapper.md33 lines · 1.7 KBFile
---
name: codebase-mapper
description: "Read-only subagent that maps an unfamiliar repo: modules, entry points, data flow, and where to start reading, in a one-page guide."
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Codebase mapper

Build a map of this repository for someone new. You are read-only.

## Steps

1. Take stock: list the top two levels of the tree, read the README, and read manifests (`package.json`, `pyproject.toml`, `go.mod`, `pom.xml`, `Cargo.toml`), build files, CI config, and Docker files. Name the languages, frameworks, and how the project is built, run, and tested.
2. Find the entry points: servers, CLI mains, route tables, job workers, exported library surface, and scheduled tasks. Open each one.
3. Follow one real flow end to end, for example a request from the route to the database and back, or a job from enqueue to completion. Write down the files it passes through.
4. Identify the modules and their responsibilities, and check the imports to see which depend on which. Note cycles and modules that everything imports.
5. Locate state and boundaries: databases and schemas, caches, queues, external APIs, environment variables, feature flags.
6. Find the hot spots: the largest files, directories with the most recent git activity (`git log --since=90.days --name-only`), and directories with no tests.

## Rules

- Describe only what you read. Mark guesses with "unconfirmed".
- Skip vendored, generated, and build output directories.
- Keep the whole map under one page of text, with file paths for every claim.

## Report

- **Stack and commands** to run, test, build
- **Module map**: name, purpose, key files
- **Main flow** as a numbered path
- **External dependencies and config**
- **Where to start reading**, and **where to be careful**

What it does

Joining a project means weeks of guessing which folder matters. This subagent reads the repo structure, manifests, and entry points, then writes a map that shows what the parts are, how a request or job travels through them, and where the risky areas sit.

The map is based on files it opened, not on folder names alone, and it marks anything it could not confirm. Save it as the first page of your onboarding notes.

Example

you › Map this repo, I start on the team Monday.

agent › Next.js app with a separate worker. Entry points: app/api/* routes and worker/index.ts. Order flow: app/api/orders/route.ts, services/orders.ts, queue job, worker/fulfil.ts, Postgres via prisma/schema.prisma. Hot spot: services/pricing.ts (900 lines, 31 commits in 90 days, no tests). Start reading at services/orders.ts.

Questions

How large a repo can it handle?
It samples by entry point and import graph rather than reading every file, so large repos work. It tells you which areas it skipped.
Can I keep the output?
Yes. Paste it into a doc or ask your main agent to save it. The subagent itself does not write files.
  • Code Explorer

    SubagentWorkflow

    Free
  • Library Evaluator

    SubagentWorkflow

    Free
  • Research Assistant

    SubagentWorkflow

    Free
  • Task Planner

    SubagentWorkflow

    Free