Code Explanation

Produce a thorough written explanation of an entire repository so someone new can understand what it does, how it is built, and how the pieces fit together. The output is a CODE_EXPLANATION/ folder of markdown files: one OVERVIEW.md and a series of numbered deep-dive documents.

The goal is genuine understanding, not a file inventory. A good explanation reads like a knowledgeable engineer walking a new teammate through the codebase: it names the important abstractions, shows real code, and explains why things are shaped the way they are.

Workflow

1. Establish the structural map with treecap

Before reading any code, get a bird's-eye view of the repo layout. Use treecap, a tree viewer that caps how many entries it shows per folder so large repos stay readable.

Resolve the tool in this order:

1. treecap, preferred. Check with which treecap.
2. If it is missing, install it: pip install treecap (it is a PyPI package: https://pypi.org/project/treecap/). If pip isn't available, try pip3 install treecap or python -m pip install treecap.
3. If installation fails or is declined, fall back to tree (which tree).
4. If neither exists, fall back to a manual listing (e.g. find . -type f filtered sensibly), but prefer the real tools.

Run it on the target repo. Sensible defaults:

treecap -W 0 -L 3        # full width (all entries), 3 levels deep

-W caps entries shown per directory (0 = unlimited; the default is 5). -L caps display depth. Start broad, then re-run deeper or with a higher width on the directories that turn out to matter (e.g. treecap src -W 0). treecap skips .git, node_modules, __pycache__, and .venv by default, which is usually what you want.

Capture this tree, you'll embed a trimmed version of it in OVERVIEW.md.

2. Read the code and build a mental model