commit-narrator

Write commit messages that say why, not just what.

TL;DR: git add -p && /commit-narrator → a conventional-commit message with a real rationale, not "fix stuff".

Why this exists

Most "AI commit message" tools paraphrase the diff back at you. That's noise. A good commit message answers why the change was made, grounded in what the diff actually proves. This plugin runs a deterministic Python helper to classify the change and assemble the skeleton, and then leaves Claude to fill in the rationale from the diff itself — no LLM guesses about your repo's intent.

Install (Claude Code)

git clone https://github.com/mturac/pluginpool-commit-narrator ~/.claude/plugins/commit-narrator

Restart Claude Code; the slash command /commit-narrator appears.

Quick start

git add -p
/commit-narrator

Or invoke the helper directly:

git diff --staged | python3 scripts/narrate.py --diff -
python3 scripts/narrate.py --format json

Flags

Flag	Default	Description
--diff PATH / -	git diff --cached	Read diff from path or stdin
--format	text	text or json

Example output

feat(api): add login throttle

Changed files:
- src/api/auth.py
- tests/test_auth.py

Throttle prevents brute-force enumeration on the /login endpoint by
rate-limiting on (ip, email) — the abuse pattern surfaced in the
2026-Q2 incident review.

How it works

1. Reads the staged diff (or a path you give it).
2. Classifies the change type — feat / fix / refactor / docs / test / chore / perf — using path patterns and patch-hunk heuristics.
3. Derives a scope from the most-touched top-level directory.
4. Emits a conventional-commit subject plus a body listing changed files and a placeholder WHY line.
5. Claude reads the helper's output and the diff, then replaces the placeholder with rationale that the diff actually supports.

Limitations

• Heuristics are intentionally conservative. You'll get chore for messy mixed diffs — that's a signal to split the commit, not a bug.
• The helper itself never calls a network service; only the slash command's Claude pass adds language.

Examples

Step-by-step walkthroughs with real input fixtures and the helper's actual output live in examples/. Three or four scenarios per plugin — from the happy path to the edge cases the test suite guards.

Part of the pluginpool family

Ten focused Claude Code plugins for everyday productivity: commit-narrator · pr-storyteller · test-gap · deps-doctor · env-lint · secret-guard · standup-gen · todo-harvest · flaky-detector · changelog-forge

License

MIT — see LICENSE. Contributions welcome.