retros

claude-code-retros

A Claude Code plugin that auto-captures session retrospectives so observations don't evaporate when sessions end.

What it does

After every substantive Claude Code session, a Stop hook spawns a backgrounded claude --resume --fork-session -p subprocess. The forked session inherits the parent's full transcript, picks a topic slug, captures observations (learnings, dead ends, mental-model corrections, capability gaps, etc.), and writes a markdown retro to ~/.claude/retros/. Parent session is never blocked.

Periodically you run /retro — Claude groups unprocessed retros into bodies of work, surfaces patterns, discusses contributions to friction, and proposes structural follow-ups (CLAUDE.md edits, memory entries, skill changes, tooling unblocks). You confirm; the actions land. Reviewed retros get a ## Processed: section appended in place.

The two stages are deliberately decoupled: capture is cheap and unilateral (just writes a file), action is human-gated.

Install

On the machine where you developed it (already installed)

~/.claude/settings.json already has:

"extraKnownMarketplaces": {
  "claude-code-retros": {
    "source": { "source": "directory", "path": "/Users/<you>/projects/claude-code-retros" }
  }
},
"enabledPlugins": {
  "retros@claude-code-retros": true
}

On a fresh machine

1. git clone <this-repo> ~/projects/claude-code-retros
2. Add to ~/.claude/settings.json:

   "extraKnownMarketplaces": {
     "claude-code-retros": {
       "source": { "source": "directory", "path": "/Users/<you>/projects/claude-code-retros" }
     }
   },
   "enabledPlugins": {
     "retros@claude-code-retros": true
   }
   

   (Or push to GitHub and use a "source": "github" form — see below.)
3. Restart Claude Code. /capture-retro and /retro should appear in the skill list.

From GitHub (for cross-machine sync)

Push this repo to GitHub, then on each machine:

"extraKnownMarketplaces": {
  "claude-code-retros": {
    "source": { "source": "github", "repo": "<you>/claude-code-retros" }
  }
}

Slash commands

• /capture-retro — manually invoke a retro for the current session. Picks a topic slug, computes a filename, captures observations, writes the file. Normally fires automatically; manual invocation is for edge cases.
• /retro — review unprocessed retros. Loads everything in ~/.claude/retros/ lacking a ## Processed: section, groups by body of work, surfaces patterns, proposes actions. Bias is toward discussion over action.

Status line indicator (optional, manual)

The plugin can't own your status line because it's a single user-level setting. Add this snippet to ~/.claude/statusline-command.sh if you want a retros:N indicator:

# Build unprocessed-retros segment: count retro files lacking a `## Processed:` section.
retro_part=""
retro_dir="$HOME/.claude/retros"
if [ -d "$retro_dir" ]; then
  unprocessed=$(grep -L "^## Processed:" "$retro_dir"/*.md 2>/dev/null | wc -l | tr -d ' ')
  if [ "${unprocessed:-0}" -gt 0 ] 2>/dev/null; then
    retro_part="retros:${unprocessed}"
  fi
fi

Then append [ -n "$retro_part" ] && parts+=("$retro_part") wherever your script assembles its parts array.

Architecture (one-liner per piece)

• hooks/auto-retro-stop.sh — Stop hook. Five guards (loop guard, transcript exists, trivial-skip, session_id, marker dedup). Spawns nohup claude -p --resume <sid> --fork-session --settings '{"disableAllHooks":true}' --strict-mcp-config --permission-mode bypassPermissions --allowedTools "Bash,Read,Write,Glob,Grep" -- "<prompt>" &. Exits 0 — never blocks parent.
• commands/capture-retro.md — the skill the fork (or you) invokes. Picks topic slug, runs date, writes ~/.claude/retros/<datetime>-<slug>.md.
• commands/retro.md — the review facilitator.

Storage

• Retros: ~/.claude/retros/<datetime>-<topic-slug>.md — markdown, append-only.
• Markers (hook dedup): ~/.claude/retros/.captured-<session-id> — hidden, one per session.
• Fork debug logs: /tmp/retro-fork-<session-id>.log.

Known design choices

• One retro per session, enforced by the marker-file dedup — within a session, only the first Stop event captures.
• Parent never blocks — the hook spawns the fork-resume in the background and exits immediately.
• Fork inherits parent context via --resume (so retros have real subjective signal, unlike a cold-start subagent).
• Hooks fully disabled in the fork via --settings '{"disableAllHooks":true}' — no recursion, no Warp notification per retro.
• Retros stay in ~/.claude/retros/ regardless of project — project-scoped storage is a known follow-up; today everything is user-level.

Built with the help of itself