claude-human-review

claude-human-review

A plugin that helps you actually understand the code Claude Code writes for you. After every turn that edits files, Claude pauses, drops short doc comments on the classes and functions it touched (JSDoc for TS/JS, docstrings for Python, and so on), then explains what changed and why in plain English. You either approve the changes or undo them. The review itself is tuned to stay short so the token cost is minimal.

Keywords: claude code review, claude code approval, approve claude changes, undo claude changes, AI code review, human-in-the-loop, claude code plugin, claude code hooks.

---

Features

• Stop-hook gate: blocks Claude from ending any turn that edited files until a review is shown.
• Plain-English review: 60 to 120 words covering what changed, why, and any hidden risks.
• Inline doc comments: drops one-line JSDoc, docstrings, //, etc. on new or changed classes and functions, and skips trivial helpers and tests.
• Approve / Undo prompt: reply 1 or 2. Approve keeps the change, Undo reverts every file this turn.
• Snapshot-based undo: restores from on-disk snapshots, works in any directory (git or not), survives context compaction.
• New-file cleanup: Undo deletes files Claude created, not just reverts them.
• Risk flagging: auth, SQL, crypto, migrations, new deps, and unsnapshotted files get called out in a "Worth a second look" section.
• Read-only turns skip: Read, Bash, Grep, and Glob-only turns never interrupt you.
• Kill switch: HUMAN_REVIEW_DISABLED=1 claude turns the gate off without uninstalling.

---

Contents

• Install
• Why this exists
• Heads up: token usage
• What you'll see
• How the review differs from a default Claude summary
• How to use it
• How it works under the hood
• Why not just use CLAUDE.md?
• State and storage
• Repository layout
• Behavior details and edge cases
• Limitations
• Contributing
• License

---

Install

Option A: install from GitHub (recommended)

Two slash-commands inside Claude Code:

/plugin marketplace add IrtezaAsadRizvi/claude-human-review
/plugin install claude-human-review@claude-human-review

The first command registers this repo as a plugin marketplace. The second installs the plugin. Restart Claude Code once after installing so the hooks register, then the review gate fires on the next turn that edits files.

To pull updates later:

/plugin marketplace update claude-human-review

Option B: install from a local clone (for development)

If you want to hack on the plugin yourself, clone the repo and point Claude Code at your local copy:

git clone https://github.com/IrtezaAsadRizvi/claude-human-review.git

Then inside Claude Code:

/plugin marketplace add /absolute/path/to/claude-human-review
/plugin install claude-human-review@claude-human-review

Edits to skills/human-review/SKILL.md and the hook scripts take effect on the next Claude Code restart.

Option C: Claude Code official plugin marketplace

Submitted to Anthropic's community marketplace. Pending approval. Once live:

/plugin marketplace add claude-plugins-official
/plugin install claude-human-review@claude-plugins-official

Requirements

• Claude Code (any version with plugin and hook support).
• Python 3.9 or newer on PATH. The hooks are pure Python, no third-party dependencies.
• Bash for the approve and undo helper scripts.

---

Why this exists

Claude Code writes code fast. Faster than you can read it. If you work that way for a few weeks, you end up sitting on a codebase you kind of wrote, kind of didn't, and don't fully understand. That's painful when something breaks, when a teammate asks why a piece of code is shaped the way it is, when an auditor wants a walkthrough, or when you come back six months later to extend it.

The goal of this project is simple: make the human developer more educated about the code going into their project.

Every review is a short lesson. Here's what changed. Here's why. Here's what to watch out for. You read it, you decide, you move on. Over time that adds up, and you end up fluent in your own codebase instead of a passenger in it.

Approve keeps the change. Undo throws it out. Either way, you saw it.

---

Heads up: token usage

The plugin is tuned to stay cheap. The skill targets 60–120 words per review and drops sections when they'd be filler, so the output overhead per turn is small. Inline doc comments follow the same rule: one short line per symbol, only on classes, functions, exported symbols, and non-obvious config blocks, and only where the purpose isn't already obvious from the name. No JSDoc spam, no docstrings for three-line helpers.

You're paying a handful of extra tokens to actually understand what Claude just did to your code, and to get a real Undo button if you don't like it. For serious AI-human collaboration, that's cheap.

If you want to claw tokens back on the input side, caveman compresses prompts. Pairs well with a plugin that already keeps output lean.

---

What you'll see

When Claude finishes a turn that edited files, your terminal shows something like this:

## Review: what I just did

**What changed**
- `src/auth/session.py`: session cookie SameSite=Lax → Strict, added Secure flag.
- `tests/test_auth.py`: two cases for the new flags; fixture expects `secure=True`.

**Why**
Read "tighten cookie handling" as CSRF hardening. Strict will break cross-site embeds; I assumed you have none.

**Worth a second look**
- Strict breaks OAuth redirects landing on your domain.
- Secure drops cookies on plain-HTTP localhost dev.

1. Approve: accept these changes.
2. Undo: revert all files this turn.

Reply 1 to keep it or 2 to roll it back.

Alongside the review, Claude adds a one-line doc comment above any class, function, or config block it created or materially changed. JSDoc in TS/JS, docstrings in Python, // in Go, and so on. Example, in a file Claude just touched:

/** Validates a JWT and returns the decoded claims, or null if it's expired or signed with the wrong key. */
export function verifySession(token: string): Claims | null { ... }

Trivial helpers, tests, and anything already documented are left alone, so the diff stays small.

---

How the review differs from a default Claude summary

Claude already recaps its work at the end of a turn if it feels like it. This review is a different artifact, on purpose.

	Default Claude recap	This plugin's review
Shape	Freeform prose, varies turn to turn	Fixed template: What changed / Why / Worth a second look
Length	Anywhere from one line to a full page	60 to 120 words, hard cap 200
Per-file detail	Often re-narrates each chunk	One line per file, goal-level, 12 words max
Risks	Mentioned only if they came up while coding	Dedicated section, targets auth, SQL, crypto, new deps, migrations, unsnapshotted files
Invisible risks	Usually missed	Explicitly called out: dynamic imports, loosened checks, swallowed exceptions
Ending	Turn just ends, you decide what to do	Forced 1. Approve / 2. Undo choice
Guaranteed?	No, Claude may skip it	Yes, enforced by the Stop hook

The goal is a fixed-shape artifact you can scan in under 30 seconds and decide keep-or-revert, not a narrative of what was done.

---

How to use it

There's nothing to do. Once installed, the plugin runs itself. From your side it looks like this:

1. You prompt Claude as normal. Something like "refactor the auth middleware to use JWT."
2. Claude edits files as normal. You don't see anything different while it works.
3. At the end of the turn Claude pauses and writes the review shown above.
4. You reply:
   • 1 or approve: changes stick, session state clears, you're done.
   • 2 or undo: every file edited this turn gets reverted. Newly created files get deleted.
   • Anything else is treated as a fresh prompt. The previous turn is implicitly accepted and the plugin starts tracking the new one.

What counts as a change

Tool Claude used	Triggers a review?
Edit, Write, NotebookEdit	Yes
Read, Bash, Grep, Glob	No

Read-only exploration turns never interrupt you. Only turns that actually changed your files do.

Turn it off temporarily

Set an environment variable before launching Claude Code:

HUMAN_REVIEW_DISABLED=1 claude

The Stop hook honors this flag and lets Claude stop silently. Snapshots and edit logs still get written harmlessly, so you can flip the flag back on mid-session if you change your mind.

---

How it works under the hood

Three Claude Code hooks coordinate through a per-session state directory.

PreToolUse  (Edit, Write, NotebookEdit): snapshot.py   copies the original file
PostToolUse (Edit, Write, NotebookEdit): track_edits.py logs the edit
Stop        (end of turn):               review_gate.py blocks stop, injects review prompt

When the Stop hook fires with a non-empty edit log, it blocks Claude from stopping and injects a prompt telling Claude to load the human-review skill. That skill contains the template, tone rules, and example Claude uses to write the review. Your 1 or 2 reply routes to two small Bash helpers (scripts/approve.sh and scripts/undo.sh) that do the actual state mutation.

Undo uses filesystem snapshots, not git, so it works the same way in any directory: git repo, non-repo, or a folder full of untracked files.

---

Why not just use CLAUDE.md?

Fair question, and the obvious one. You could drop something like "after every edit, summarize what you did and ask for approve or undo" into your CLAUDE.md, and Claude would try to follow it. It works, sometimes. Here's why the plugin exists anyway.

CLAUDE.md gets read. Hooks get executed.

CLAUDE.md is context Claude reads, weighed against your actual prompt. If your prompt is long or urgent, Claude can deprioritize the review instruction and just stop. There's no enforcement. The Stop hook here literally prevents Claude from ending the turn until the review is out. Deterministic, not probabilistic.

Undo needs snapshots, not memory.

To undo a set of edits you need the pre-edit contents of each file. A CLAUDE.md approach asks Claude to remember those contents and rewrite the files back. That breaks down a lot. Claude's context gets compacted mid-session and the old contents disappear. Claude does a Write without Reading first, so there's nothing to remember. Claude's rewrite of the "original" introduces its own bugs. This plugin snapshots each file to disk before the edit happens, so undo is a deterministic file restore, not another AI rewrite.