A Claude Code skill that explains AI-made session changes as a cohesive story — the WHY, not just the WHAT — with cross-file connection mapping, in a self-contained HTML report.
After a Claude Code session, run /review-changes to get a readable HTML report that:
- Tells the story of what changed and why, chapter by chapter
- Shows inline diffs woven into each chapter at the moment the narrative references them
- Maps connections between files — which changes caused other changes, and why
- Quick or Deep — fast narrative overview or thorough per-method analysis with a dependency graph
- Clone or copy this repository
- Install via Claude Code plugin system (see Claude Code documentation for plugin installation)
- Or reference the commands directly from your project's
.claude/directory
Generate a code review narrative for changes made in the current session.
Depth mode:
| Mode | Output |
|---|---|
quick (default) |
Chapter story + inline diffs + connection table |
deep |
Full story + method-level detail + trade-offs + SVG dependency graph |
Language level:
| Level | Audience | Style |
|---|---|---|
explain |
Junior / new to codebase | Defines terms, uses analogies, no jargon assumed |
standard (default) |
Mid-level engineers | Current voice — assumes engineering knowledge |
expert |
Senior engineers | Terse, trade-offs only, skips obvious reasoning |
Examples:
/review-changes
/review-changes quick
/review-changes deep
/review-changes quick explain
/review-changes deep expert
/review-changes quick standard
Close the session and auto-generate a Quick review.
Reports are written to .claude/reviews/YYYYMMDD-HHMMSS-review.html in your project directory.
- Self-contained — all CSS inlined, no CDN, no external fonts
- Renders offline in Chrome, Firefox, and Edge
- Safe to open directly from disk
The .claude/reviews/ directory is automatically added to .gitignore on first run.
To set a persistent language level for your project, create .claude/reviewer.json:
{
"default_level": "explain"
}Valid values: "explain", "standard", "expert". Command arguments override this setting for one-off use.
When the skill is active, it maintains .claude/.session-manifest.json — a lightweight file that captures the intent of each edit as it happens. This eliminates expensive re-analysis at review time and makes Quick mode significantly faster.
The manifest is maintained automatically. No configuration required.
To automatically generate a Quick review every time a Claude session ends, add to .claude/settings.json:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "/* see Claude Code documentation for current skill-from-hook invocation syntax */"
}
]
}
]
}
}Note: Skill-from-hook invocation syntax varies by Claude Code version. See the Claude Code documentation for the exact command to use in your environment. The hook should trigger
/review-changes quickwhen the session ends.
The following are automatically excluded from all reviews:
| Pattern | Reason |
|---|---|
.env*, *.env |
Environment secrets |
appsettings.*.json |
Application secrets |
secrets/** |
Secrets directory |
*.key, *.pem, *.p12, *.pfx |
Private keys / certificates |
**/node_modules/** |
Dependency noise |
**/.git/** |
Git internals |
Excluded files are noted in the report as filename — excluded from review (sensitive file pattern).
Each /review-changes invocation uses approximately 14% of the context window on a typical 10-file session (~67% token overhead over baseline on a 200K context). This is expected — the skill reads your session diff and generates a narrative, which has a real token cost.
Because the skill is on-demand only (you explicitly choose to run it), this overhead is incurred only when you want it. It does not run passively or consume background tokens.
Use Quick mode (default) for routine reviews. Deep mode adds per-method detail and a dependency graph, with proportionally higher overhead.
| Limitation | Detail |
|---|---|
git mv rename detection |
Sessions where files are only renamed (no content change) report "No changes detected." v1.1 will add rename detection via git diff --find-renames. |
| Stop hook syntax | The auto-mode hook command cannot be documented statically — syntax varies by Claude Code version. See the Claude Code documentation. |
| Context compaction | If context is compacted before /review-changes runs and no manifest exists, early session changes may not appear in the report. Starting each session with the skill active (so the manifest is maintained) eliminates this risk. |
- Claude Code with skill/plugin support
- No other dependencies — pure Claude reasoning, no scripts, no external tools
MIT