How do I install the Codebase Churn skill?

Run npx skillmds@latest add risadams/codebase-churn in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Codebase Churn safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Codebase Churn?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Codebase Churn free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Codebase Churn?

risadams (@risadams) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Codebase Churn by risadams — Agent Skill

Name: Codebase Churn
Author: risadams

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.

risadams 5d221ef 3 files · 23.6 KB Updated Sep 17, 2026

File contents

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:

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

Run from the repo root with default settings.
Open the SVG. Identify the 3–5 hottest (largest red) tiles.
For each, ask: do they have tests? Are they touched by many people, or one? Have recent bugs landed there?
Re-run with --since "3 months ago" and compare to the all-history view to spot newly-volatile areas.
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.

---name: codebase-churndescription: 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.---# codebase-churnGenerate 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 startFrom the target repo:```bashpython3 ~/.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 -- ...`).## Workflow1. 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.

Frequently asked questions