retro

Never type the same correction twice.

Your coding agent keeps making the same mistakes. You keep typing the same corrections. Every one of them is already written down, in transcripts nobody reads.

Every Claude Code session you ever ran is sitting in ~/.claude/projects/ as a full transcript. Inside those files is a precise record of every time the agent got it wrong: every "no, not like that", every Esc you hit mid-action, every command it retried five times, every session you rage-quit after a failure.

retro reads those transcripts and closes the loop:

your failures → clusters → evidence → a concrete CLAUDE.md diff

This is the Replit-style self-improvement loop (production failures → clusters → evidence → patches), applied to the harness you already own. No fine-tuning, no API keys, no telemetry. Continual learning at the layer you can actually change.

Isn't this just /insights?

Claude Code's built-in /insights gives you a great 30-day usage report with suggestions. retro is a different tool for a different job:

• Evidence, not summaries. Every proposed rule comes with verbatim quotes from your transcripts, dated. You see exactly which failures a rule would have prevented, and can veto it.
• Signals /insights doesn't mine. The agent admitting "you're right" (69 times in my last 45 days), rules you dictated out loud ("запомни, отныне..."), Esc-interrupts and what you said right after.
• Closes the loop. retro doesn't stop at suggestions: it drafts the CLAUDE.md diff, you confirm, it applies.
• Inspectable and hackable. One stdlib Python file, deterministic, bilingual (EN/RU) with pluggable language packs, custom windows (7d/90d/all), JSON output you can pipe anywhere.

Use both: /insights for the big picture, /retro for turning failures into rules.

What about netresearch/retro-skill?

Fair question — netresearch/retro-skill is a separate project with the same /retro command and the same core idea (mine transcripts, propose CLAUDE.md rules, approve each one). We built ours independently; the space clearly has legs if two teams landed on it at once. They're different tools for different users:

• Theirs is a framework — ~37 signals across process hygiene (DCO sign-off, work-on-main, conventional commits, tool-call efficiency), routing to six destinations including PRs against skill repos and CI bootstrap. Depends on jq, gh/glab, git, an optional SQLite coach plugin, and installs via a plugin marketplace / Composer. Great if you run a team with strict git conventions.
• This is a script — one stdlib Python file, zero dependencies, that you can read end to end. It focuses on the human friction: the corrections you type, the "you're right" the agent says back, the Esc-interrupts, the rules you dictate out loud — and it's bilingual (EN/RU) with pluggable language packs. Built for the individual developer's day-to-day.

If you want an enterprise harness, use theirs. If you want a tiny, inspectable tool that catches what you keep re-typing, you're in the right place.

Install

git clone https://github.com/craftwork-design/retro.git && cd retro && ./install.sh

Manual install (also works for updating):

TMP=$(mktemp -d) && git clone https://github.com/craftwork-design/retro.git "$TMP" \
  && rm -rf ~/.claude/skills/retro && mkdir -p ~/.claude/skills \
  && cp -r "$TMP/skill" ~/.claude/skills/retro

Requires Python 3.8+ (stdlib only, no dependencies). On Windows, use Git Bash for the commands above and python instead of python3. If you use a custom CLAUDE_CONFIG_DIR, both the installer and the scanner respect it.

Claude Code only. retro reads ~/.claude/projects/ transcripts. Cursor, Codex, and Zed are on the roadmap, not supported today. New to retro or a fresh machine? Start with /retro all — a brand-new project has almost no history, so the single-project view will look empty until you've used it a while.

Use

Inside Claude Code, in any project:

/retro          # current project, last 30 days
/retro 7d       # last week
/retro all      # every project on this machine

The agent scans your transcripts, clusters recurring friction, and shows you a retro with evidence and a proposed CLAUDE.md diff. Nothing is applied without your confirmation.

Want just the numbers, without the agent? Run the scanner directly:

python3 ~/.claude/skills/retro/scripts/scan.py            # pretty terminal report
python3 ~/.claude/skills/retro/scripts/scan.py --all      # all projects
python3 ~/.claude/skills/retro/scripts/scan.py --format json

What it detects

Languages

Roughly half of the signals are language-agnostic by construction: interrupts, nudge-free repeated instructions (token clustering), repeated pastes, denials, errors, retry loops, abandoned sessions. The lexical detectors (corrections, admissions, rule requests, nudges) ship with English and Russian patterns, morphology-aware.

Other languages plug in as a JSON pattern pack, no code changes:

python3 skill/scripts/scan.py --patterns skill/patterns/example-es.json

See skill/patterns/example-es.json for the format. Language pack PRs are very welcome.

The scanner is deterministic and high-recall; the skill (the model) does the judgment: which candidates are real patterns, what the root cause is, and what minimal rule, hook, or permission change would have prevented them.

Example

# Retro: my-app — last 30 days

Scanned 42 sessions. The biggest issue: test runner confusion.

## Pattern 1: wrong test command (9 failures, 6 sessions)
Evidence: `npm test` failed with "missing script" on Jun 12, 14, 19...
Root cause: repo uses pnpm + vitest, CLAUDE.md never says so
Fix: add rule "Run tests with `pnpm vitest run`, never `npm test`"

## Proposed CLAUDE.md diff
+ ## Commands
+ - Run tests with `pnpm vitest run`, never `npm test`
+ - Dev server is already running on :3000, never start a second one

See examples/report-example.md for a full report.

Privacy

Everything runs on your machine. The scanner is a single stdlib Python file with no dependencies. No network calls, no telemetry, nothing leaves your laptop. Your transcripts are yours.

Roadmap

• HTML report you can actually share (numbers only, no transcript content)
• Hook suggestions generated from denial patterns
• Report history: did last week's fixes reduce this week's corrections?
• retro for teams: one shared set of lessons across 20 engineers, synced rules registry, weekly PR into your repo with evidence. If that sounds like your team, open an issue on this repo.

License

MIT

Independent open-source project. Not affiliated with, endorsed, or sponsored by Anthropic or id Software. Claude and Claude Code are trademarks of Anthropic; DOOM is a trademark of id Software LLC.