retro_tool

A retrospective tool for Claude Code sessions, to help Claude grow. Invoke at any time during or after a Claude Code session to see some ready-to-paste suggested edits to CLAUDE.md. These will help Claude respond more usefully in future.

Usage in a Claude Code session

Type:

/retro

Running manually

python3 retro.py ~/.claude/projects/{encoded-project-path}/{session-id}.jsonl

Session files live at ~/.claude/projects/{encoded-path}/*.jsonl, where the encoded path replaces / with -.

Output format

Each retrospective covers:

• 3–5 moments — what happened, the gap, what better Claude would have done, suggested CLAUDE.md addition for this specific moment
• Suggested CLAUDE.md additions — a clean list of ready-to-paste rules that combine all moments
• Common thread — a single higher-level principle, if one exists, that covers the pattern underlying most moments

How to apply the suggestions

After editing CLAUDE.md in light of these suggestions, restart the Claude session. To apply CLAUDE.md changes without restarting, simply ask Claude to re-read the file:

Please re-read CLAUDE.md

Setup

Requirements

• Claude Code installed and authenticated (claude on your PATH)
• Python 3.8+

1. Install the /retro slash command

Copy both files to your Claude Code commands directory:

cp retro.py retro.md ~/.claude/commands/

Then restart Claude Code to pick up the new command.

How it works

retro.py parses the session JSONL, formats the full conversation, and sends it to claude -p --model opus in a single call. Opus reads the whole conversation holistically — not just isolated snippets — and identifies 3–5 moments where the gap is instructable (i.e. fixable via CLAUDE.md). It ends with a "common thread" section that looks for a higher-level principle covering multiple moments.

Output is written to retro/retro_{timestamp}.md in the project directory.