Codebase Explainer

A CLI tool that generates an architecture map and onboarding doc for any unfamiliar codebase — by orchestrating parallel Claude Code subagents, each exploring one module in isolation, then merging their findings.

bin/explain examples/toy-repo
cat output/ARCHITECTURE.md

See examples/sample-output/ for real generated output from the toy repo included in this project — no setup required to see what it produces. For a real-world test — not just a toy fixture — see examples/sample-output-click/, generated by running this tool against pallets/click, a widely-used open-source library neither the tool nor I had prior context on.

Why this exists

Understanding a codebase you didn't write is one of the most common, most time-consuming parts of the job, especially under a deadline. This tool automates the first pass: instead of one linear read-through, a coordinator identifies the repo's modules and spins up a subagent per module to explore concurrently, each with its own isolated context window, then merges their findings into one coherent map.

How it works

The core of this project is Claude Code configuration, not a Python application — .claude/skills/explain/SKILL.md and .claude/agents/module-explorer.md are the tool. A thin CLI wrapper (bin/explain) makes it runnable as a normal shell command by driving Claude Code's headless mode (claude -p) instead of requiring an interactive session every time.

codebase-explainer/
├── CLAUDE.md                        # project conventions Claude Code reads every session
├── .claude/
│   ├── skills/explain/SKILL.md      # the /explain command - coordinator logic
│   └── agents/module-explorer.md    # subagent - explores exactly one module
├── bin/explain                      # CLI wrapper around `claude -p`
├── scripts/validate_agents.py       # validates skill/subagent frontmatter
├── tests/test_validate_agents.py    # test suite for the validator
├── .github/workflows/validate.yml   # CI: lint config + run tests on every push
└── examples/
    ├── toy-repo/                    # tiny real codebase used as a demo fixture
    ├── sample-output/                # real output from running the tool on toy-repo
    └── sample-output-click/          # real output from running the tool on pallets/click

Usage

Fastest way to see it work — no Claude Code install required, just read the committed example:

cat examples/sample-output/ARCHITECTURE.md

Run it yourself against the included toy repo, or any repo of your own:

bin/explain examples/toy-repo
# or
bin/explain /path/to/any/other/repo

Output lands in output/ARCHITECTURE.md and output/ONBOARDING.md.

Interactively, inside a Claude Code session started from this directory:

/explain examples/toy-repo

Development

pip install -r requirements.txt
python scripts/validate_agents.py .   # lint the skill/subagent config
pytest tests/ -v                      # run the test suite

Both run automatically in CI on every push (.github/workflows/validate.yml).

Status

Weekend project built to learn Claude Code's subagent architecture hands-on. examples/toy-repo is an intentionally tiny fixture for demoing/testing; examples/sample-output-click shows it handling a real, unfamiliar open-source library instead — including one place where it adapted its own module-detection rule on the fly (click's source has no subdirectories) and flagged the deviation rather than forcing a bad fit.

One honestly-reported limitation from that run: the qualitative analysis held up under spot-checking against the real source, but a specific numeric claim (an exact import count) didn't — a good reminder that this kind of tool needs a human to verify specifics, not just trust the output.