hindsight
Self-improving Claude Code. Every time you tell your agent it messed up, it learns a rule so it never happens again.
You've typed this before:
"no, you broke the build — src/generated was checked in, why did you delete it?"
And your agent apologized, fixed it… and did the same thing next week, because scolding a stateless agent changes nothing.
hindsight closes the loop. It watches for exactly these messages, finds the precise step in the session transcript where the agent went wrong, and writes a minimal rule to your CLAUDE.md (or a skill, or its own learned-rules file) — automatically, while you keep working. Next session, the mistake is impossible.
# appended to your CLAUDE.md, ~30 seconds after you complained:
- Never delete src/generated: it is checked-in code, not a build artifact.
How it works
flowchart LR
A["you: 'no, that's wrong…'"] --> B["hook<br/>(regex prefilter, ~0ms)"]
B --> C["classifier<br/>(haiku, background)"]
C --> D["diagnostician<br/>(reads transcript,<br/>finds the failing step)"]
D --> E["validator<br/>(deterministic guardrails)"]
E --> F["one minimal rule<br/>→ CLAUDE.md / skill"]
F --> G["audit log<br/>+ /hindsight revert"]
- Detect — a
UserPromptSubmithook screens every message with a zero-cost regex; candidates go to a fast Haiku classifier in the background. Your session never waits. - Diagnose — a read-only agent walks the session transcript backward from your complaint and pins the root failing step: the exact tool call, edit, or claim where things went wrong.
- Fix — it proposes one minimal rule. A deterministic validator enforces hard bounds, then the fix is applied and logged. You get a desktop notification (macOS and most Linux desktops; the audit log is the source of truth everywhere).
- Review —
/hindsightlists every learned rule with the complaint and transcript evidence behind it. One command reverts any rule cleanly.
Install
/plugin marketplace add aadivyaraushan/hindsight
/plugin install hindsight@hindsight
That's it. No API key, no server, no telemetry — it runs on your existing Claude Code login and everything stays on your machine.
One requirement: the background pipeline calls the
claudeCLI headlessly, so the CLI itself must be logged in. Ifclaude -p "hi"says Not logged in, runclaudeonce and/login— even if you normally use the desktop app, which keeps its own login.
Check the pipeline is healthy:
/hindsight status
The safety model
An agent that edits its own instructions needs hard bounds. hindsight's are enforced in deterministic Python — after the LLM, so a clever transcript can't talk its way past them:
| Guardrail | Enforced |
|---|---|
| The LLM never holds a write tool | Diagnostician runs read-only (Read/Grep); a separate validator + applier are the only writers |
| One fix per complaint, one file per fix | Validator rejects multi-file fixes |
| Minimal diffs | ≤ 12 lines added, ≤ 3 removed — anything bigger is parked for human review |
| Evidence required | Every fix must quote the failing transcript step; the quote is verified against the transcript |
| Content firewall | Rules that touch permissions, credentials, URLs, settings or hook files are refused |
| No self-modification | hindsight can never edit its own code, prompts, or hooks |
| Rate-limited | Max 3 fixes per session, 10 per day |
| Fully auditable | Append-only log.jsonl with complaint + evidence + exact diff for every decision |
| Cleanly revertable | /hindsight revert <id> applies the inverse edit — and refuses if the file changed underneath |
Reviewing what it learned
/hindsight # recent detections and live rules
/hindsight show hs-… # complaint, evidence quote, exact diff for one fix
/hindsight revert hs-… # cleanly undo a rule
/hindsight prune # walk through live rules, keep or drop each
/hindsight status # pipeline health check
FAQ
What does it cost?
Nothing extra. Classification and diagnosis run through your existing claude CLI login. The prefilter means most messages never trigger any model call at all.
What if it learns a wrong rule?
Rules are bounded to a few lines, logged with their evidence, and one command away from reverted. /hindsight prune is a 60-second periodic cleanup.
Does it phone home?
No. There is no server. Transcripts, rules, and logs never leave ~/.claude/.
Which files will it edit?
Your project's CLAUDE.md, a skill's SKILL.md when the skill's own instructions caused the failure, or its own learned.md / .claude/hindsight-learned.md files. Never settings, hooks, or code.
Does it work in headless (claude -p) runs?
Detection runs there too, but Claude Code tears down async hooks when a headless session exits, so a diagnosis may be cut short. Interactive sessions are the primary use case.
How it's built
scripts/detect.sh— hook entry; sentinel + prefilter + fully detached spawnscripts/classify.sh/diagnose.sh— background pipeline overclaude -p --barescripts/validate_fix.py/apply_fix.py— the deterministic guardrail + write layer (zero-dependency Python, fully tested)prompts/— classifier and diagnostician promptscommands/hindsight.md— the review surface
Run the tests: python3 -m pytest tests/ -q
Deeper dive: docs/how-it-works.md
Contributing
Issues and PRs welcome. The test suite defines the contract — start there. Anything that loosens a guardrail needs a very good story.