# Codebase Churn

> Analyze a git repository's history and produce an SVG treemap of file churn — area = lines changed, color = commit frequency. Use when user wants to find unstable areas of a codebase, predict bug-prone files, see "where do we change the most", spot refactor candidates, or invokes /codebase-churn.

- Skill: `risadams/codebase-churn` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add risadams/codebase-churn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/risadams/codebase-churn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: risadams (https://skillmd.com/u/risadams)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/risadams/codebase-churn

---


# codebase-churn

Generate a churn treemap from git history. Premise: files changed often (high commits) and heavily (high line churn) tend to harbor more bugs. Stable files are usually safer. Big + hot tiles are where to look first.

## Quick start

From the target repo:

```bash
python3 ~/.claude/skills/codebase-churn/scripts/churn_treemap.py \
  -o churn-treemap.svg --report churn-report.md
```

Open `churn-treemap.svg` in a browser. Hover any tile for path, commit count, lines added/deleted.

## Output

- **SVG treemap** — area = total lines changed (added + deleted); color = commit count on a log scale (blue = stable → red = volatile).
- **Markdown report** (`--report PATH`) — ranked table of top files for tracking over time or pasting into a doc.

## How to read it

| Tile | Meaning | Action |
| :--- | :--- | :--- |
| Big + red | Frequent and heavy edits | Refactor candidate. Likely under-tested. Bug-prone. |
| Big + blue | One large rewrite, then quiet | Probably stabilized. Verify it has tests. |
| Small + red | Many tiny touches (configs, version bumps) | Often a noisy interface or fragile contract. |
| Small + blue | Stable | Safe to leave alone. |

## Common flags

- `--since "6 months ago"` — restrict the window. Defaults to all history.
- `--until "2026-01-01"` — pair with `--since` to compare windows.
- `--top 100` — limit how many files appear (default 200).
- `--exclude REGEX` — repeatable. Lockfiles, `node_modules/`, `dist/`, `*.min.*` are excluded by default.
- `--no-default-excludes` — keep them in.
- `-C path/to/repo` — analyze a different repo than the cwd.
- `paths...` — restrict to subpaths (forwarded to `git log -- ...`).

## Workflow

1. Run from the repo root with default settings.
2. Open the SVG. Identify the 3–5 hottest (largest red) tiles.
3. For each, ask: do they have tests? Are they touched by many people, or one? Have recent bugs landed there?
4. Re-run with `--since "3 months ago"` and compare to the all-history view to spot newly-volatile areas.
5. Capture `--report` snapshots at intervals to track whether refactors actually lower churn.

## Notes

- Pure Python 3 stdlib. No `pip install`.
- Renames are normalized (`{old => new}` collapses to the new path).
- Binary files are skipped (git reports `-` for their numstat).
- Squarified treemap layout (Bruls/Huijing/van Wijk) keeps tile aspect ratios near 1.