hindsight

hindsight

Post-implementation code review for Claude Code. Once a branch is done, hindsight reviews it with fresh eyes and asks: now that we have a working solution, is there a cleaner approach?

Why?

When Claude Code is mid-task, it makes local decisions to keep the work moving. Abstractions get introduced, helpers get extracted, patterns emerge that made sense in flight. Once the task is done and the solution actually works, those choices often look different. A fresh second pass — done by an agent that never saw the journey, only the destination — catches things the original pass can't.

That's hindsight: a separate agent, with its own system prompt and its own tools, that reviews the finished state and tells you whether there's a cleaner version.

Quick start

# Install globally (or use npx)
npm install -g hindsight

# Export your Anthropic API key
export ANTHROPIC_API_KEY=sk-ant-...

# Finish your branch, then:
hindsight

The verdict prints to stdout. That's it.

How it works

Finish a branch
    │
    ▼
Run `hindsight` (defaults to main..HEAD)
    │
    ▼
Phase 1: Triage (Haiku) — was code actually changed?
    │
    ▼
Phase 2: Deep review (Opus) — is there a cleaner solution?
    │
    ▼
Verdict prints to stdout

Requirements

• Node.js 20+
• An Anthropic API key exported as ANTHROPIC_API_KEY. Reviews bill against your API account, not your Claude.ai subscription
• Git

CLI reference

hindsight [options]

Flag	Description
--base <ref>	Diff against <ref>..HEAD instead of main..HEAD
--force	Skip triage — go straight to deep review
--path <dir>	Run against this repo instead of cwd
--triage-model <model>	Phase 1 model. Default: haiku
--review-model <model>	Phase 2 model. Default: opus
help	Print usage

Model values: haiku, sonnet, opus (or a raw Anthropic model ID).

Environment variables

Env var	Equivalent flag
HINDSIGHT_TRIAGE_MODEL	--triage-model
HINDSIGHT_REVIEW_MODEL	--review-model

Flags always win over env vars.

Examples

# Review the whole branch against main (default)
hindsight

# Review against a different base
hindsight --base develop

# Force a deep review (skip triage)
hindsight --force

# Point at a different repo
hindsight --path ~/coding/my-project

# Use Sonnet instead of Opus for the deep review
hindsight --review-model sonnet

Edge cases

• On main with no --base: main..HEAD is empty — hindsight prints a message telling you to pass --base and exits non-zero.
• No code changes: if triage finds only doc/config changes, the verdict is clean and printed to stdout.

Reading the verdict

Verdict: clean
Added auth middleware in src/auth.ts

Verdict: worth refactoring
src/hooks/useUserData.ts (lines 12-45)
  Issue: duplicates logic already in useAuth
  Fix:   consolidate into useAuth and re-export

The new useUserData hook duplicates logic that already lives in useAuth...

• clean — code looks good, no action needed
• minor suggestions — small notes, not worth acting on
• worth refactoring — the agent thinks there's a meaningfully cleaner approach

Costs

Rough per-run costs at current Anthropic pricing:

• Triage only, no code changes: fractions of a cent (Haiku)
• Triage + deep review: a few cents depending on diff size (Opus)

Set a monthly spending cap in the Anthropic Console while you're getting comfortable.

---

Automated reviews (optional)

hindsight also ships as a Claude Code plugin that auto-fires a review after every git commit, git commit --amend, or git rebase Claude runs in a session. This is the "set and forget" mode — you don't run anything manually.

Plugin install

In Claude Code:

/plugin marketplace add danworkman1/hindsight
/plugin install hindsight@danworkman1

Restart Claude Code if prompted. From the next session forward, every commit, amend, or rebase Claude performs triggers an async review.

ANTHROPIC_API_KEY is required. Reviews are made by a hook subprocess that bills against your API account, not your Claude.ai subscription — Anthropic doesn't permit third-party plugins to use subscription auth. Export ANTHROPIC_API_KEY in your shell rc (use ~/.zshenv or ~/.bash_profile so non-interactive shells inherit it). Without the key the hook logs a [skip] line and exits cleanly — your Claude session is never blocked.

Plugin requirements

Everything the CLI needs, plus:

• Claude Code 2.x
• jq (used by the plugin's hook script — almost certainly already on your system)

How the plugin works