review-ledger

A Claude Code plugin for incremental code review. Claude checks your code for bugs, performance problems and security issues. It also keeps a ledger inside each project of exactly which files and functions it has reviewed, at which version, and what it found.

Next time you ask for a review, Claude checks the ledger first and only looks at code that is new or changed. Unchanged code is skipped, so you don't pay tokens to re-review it.

Install

Inside Claude Code (any project):

/plugin marketplace add ikjbi/codeReview
/plugin install review-ledger@codereview

Run /reload-plugins or restart Claude Code. The plugin is installed for your user, so it works in every project. Each project gets its own ledger.

To update later: /plugin marketplace update codereview.

Requirements: python3 (standard library only) and, ideally, git. Without git it still works, but it can't show diffs, so changed files are re-reviewed in full.

Usage

Command	What it does
/review-ledger:review	Review everything in the project that is new or changed since the last review
/review-ledger:review src/api	Same, limited to a file or directory
/review-ledger:review --focus security	Weight the review toward bugs, performance and/or security
/review-ledger:review --all	Ignore earlier reviews and review everything in scope again
/review-ledger:review --recheck	Don't hunt for new issues; only check whether open findings are fixed
/review-ledger:status	Show coverage and open findings without reviewing anything
/review-ledger:fix F-0003 F-0007	Fix specific findings (or --severity high for all high and critical)

You can also just say "review my code for bugs". Claude picks up the review skill automatically.

Claude doesn't change your code during a review. It reports findings and offers to fix them.

How it works

On every review Claude runs the bundled helper scripts/ledger.py plan, which sorts each source file into one of these groups:

Group	Meaning	What Claude does
NEW	never reviewed	reads and reviews the whole file
CHANGED	content hash differs from the reviewed version	reviews only the diff (ledger.py diff) and rechecks that file's open findings
RECHECK	unchanged, but imports a changed file	checks only the call sites of the changed code
UNCHANGED	same content hash as when reviewed	skips it

Some details:

• Fingerprints, not just file names. Each reviewed file is stored with its git blob hash, so any edit, even one made outside git, marks it as changed. Saying "this file was reviewed" stays true.
• Exact diffs. When a file is recorded, its reviewed version is written into the local git object database (git hash-object -w). Later ledger.py diff shows exactly what changed since that version, even if you never committed it. On another machine it falls back to diffing against the commit that was checked out at review time.
• Function-level records. For each file the ledger lists the functions, methods and classes that were examined, with short notes. Functions that disappear from a file are dropped automatically.
• Tracked findings. Every finding gets an ID (F-0001), severity, category, location and status (open, fixed, wontfix, false-positive, obsolete), so open issues carry over between sessions.
• Resumable. Claude records after each batch of files, so an interrupted review keeps its progress and the next session continues from there.
• Dependents check. The RECHECK group is a heuristic: it looks for import lines that name a changed module. It catches most JS/TS/Python/Go/Rust/Java-style imports. It can't see module-wide visibility such as Swift's.

What gets written to your project

Everything goes in .code-review/ at the project's git root:

File	Purpose
ledger.json	The machine-readable ledger (files, hashes, functions, findings, sessions). Claude reads it only through the helper script, never directly
REVIEW_LOG.md	Human-readable report regenerated after every change: open findings, reviewed files and functions, resolved findings, session history
config.json	Optional settings, see below

Commit .code-review/ so the review history follows the repo across machines and teammates.

config.json

{
  "extra_extensions": [".yaml", ".html"],
  "exclude": ["src/generated/*", "*.test.ts"],
  "max_file_kb": 256
}

• extra_extensions: file types to review on top of the built-in list of common source extensions.
• exclude: glob patterns, matched against the path relative to the project root and against the file name.
• max_file_kb: files larger than this are skipped, since they're usually generated.

Files ignored by .gitignore, plus common build and dependency folders (node_modules, dist, build, vendor, Pods, .venv, …), are always skipped. To review an excluded file anyway, name it explicitly: /review-ledger:review path/to/file.

Helper script reference

The skills call scripts/ledger.py for you, but you can also run it yourself from anywhere inside a project:

python3 scripts/ledger.py plan [paths...] [--all] [--verbose] [--json]
python3 scripts/ledger.py diff <paths...> [--context N] [--whole-functions]
python3 scripts/ledger.py record [--input file.json]      # JSON on stdin
python3 scripts/ledger.py finding F-0001 --status fixed --note "..."
python3 scripts/ledger.py show F-0001
python3 scripts/ledger.py status [--json]
python3 scripts/ledger.py prune                           # forget deleted files
python3 scripts/ledger.py render                          # regenerate REVIEW_LOG.md

The record input format is documented in skills/review/SKILL.md.

Repository layout

.claude-plugin/
  plugin.json         plugin manifest
  marketplace.json    lets this repo be added as a marketplace
skills/
  review/SKILL.md     /review-ledger:review
  status/SKILL.md     /review-ledger:status
  fix/SKILL.md        /review-ledger:fix
scripts/
  ledger.py           bookkeeping helper (stdlib-only Python)

Development

Test local changes without reinstalling:

claude --plugin-dir /path/to/codeReview
claude plugin validate /path/to/codeReview

Bump version in .claude-plugin/plugin.json with each release. Installed copies only update when the version changes.