Retro Daily

A daily retro for your Claude Code sessions

Renders at the top of every Claude Code session via a SessionStart hook:

• All-time + last-7-days totals — sessions, tools, days, cost (API-equivalent)
• Competency grade — 0–100 composite score plus an A–F letter, with per-metric breakdown
• 14-day efficiency sparklines for Edit/Read, auto-approve, first-try, corrections, tool errors, context hygiene
• Year-long contributions heatmap — the green-grid you know from GitHub, sourced from your session history
• Focus areas — concrete, actionable recommendations for your weakest metrics
• Scout findings — a background worker that searches docs.anthropic.com and GitHub for ideas tied to those weak metrics

R E T R O  ·  D A I L Y                                   Sun May 17
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

A L L - T I M E
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   1197 sessions  10626 tools   21 days   15 projects   $6436.49 est.
  tokens  239.0K in  10.6M out  1.82B cache-read  127.2M cache-write

C O M P E T E N C Y
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ███████████████████░░░░░░░░░░░   62.1/100    D
  breakdown   Edit/Read 100  Auto-approve 29  First-try 100  ...

E F F I C I E N C Y
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  metric            value   14-day trend     7d   30d   status
  Edit / Read         1.0   ▄▂▁▃▂▃▂▅▄█▄█▄▁   →    ↑     ⬤ good
  Auto-approve      65.7%   ▇▆▁▇▃▆▆▄▆█▇██▂   ↑    →     ⬤ bad
  First-try         83.4%   ▇██▇▇███▇▇█▇█▁   ↑    ↑     ⬤ good
  Corrections       15.1%   ▇▄▃▄█▂▁▂▁▁▃▁▁▁   ↓    ↓     ⬤ bad
  Tool errors       10.2%   ▂▄▅▁▃▂▂▂▃█▃█▃▁   →    ↓     ⬤ bad
  Ctx hygiene       50.0%   ·········▁▁▁██   ↑    →     ⬤ warn

C O N T R I B U T I O N S
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      May Jun  Jul Aug  Sep Oct Nov  Dec Jan Feb Mar  Apr
     ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
  Mon ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
  ...
  less ■■■■■ more   1197 sessions across 21 days this year

S C O U T   F I N D I N G S
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ● claude code auto approve setup
      → If on Team plan, run `claude --permission-mode auto` ...
      ★ oryband/claude-code-auto-approve · Install as a PreToolUse hook ...

Install

Inside Claude Code:

/plugin marketplace add gyanesh-m/retro-daily
/plugin install retro-daily@retro-daily
/reload-plugins

The repo doubles as its own single-plugin marketplace. State lives under ${CLAUDE_PLUGIN_DATA} (~/.claude/plugins/data/retro-daily-retro-daily/) so plugin updates and uninstalls clean up after themselves.

Test against a local clone before publishing:

claude --plugin-dir ./retro-daily

Configuration

The scripts read the following env vars at session start. The plugin's hooks.json sets path-related ones automatically.

Paths and labels

Set RETRO_DAILY_PLAN_LABEL="Claude Max $100/mo" (or "Claude Pro $20/mo", "API", etc.) if you want the cost footer to name your plan. Claude Code does not expose the active subscription tier programmatically, so this can't be auto-detected.

Background scout (network-facing)

The scout spawns a detached, sandboxed claude -p worker that uses WebSearch (network access to docs.anthropic.com and github.com) to research your weakest metrics. Two knobs control it:

Put either in your shell rc, or in your project's .envrc if you use direnv. The scout is also automatically skipped if a previous worker is still running, or if its weak-metric set matches the last successful run.

Requirements

• python3 (3.9+) — required
• claude CLI on $PATH — required for the scout background worker

Python dependencies

The prompt classifier uses sentence-transformers (~90MB MiniLM, required for topic similarity) and optionally transformers + sentencepiece (~500MB DeBERTa NLI, fallback for reactions that don't match any lexical cue). On the synthetic eval, lexical cues alone classify 49/50 cases correctly — NLI is insurance, not the primary path.

These are installed into a venv at ${RETRO_DAILY_DATA}/.venv so they don't pollute system Python. Plugin install paths are read-only at install time, so the venv isn't auto-bootstrapped. After /plugin install, run once:

bash ~/.claude/plugins/cache/<marketplace>/<plugin>/setup-venv.sh

Or, simpler — clone and run:

git clone https://github.com/gyanesh-m/retro-daily.git
RETRO_DAILY_DATA=~/.claude/plugins/data/retro-daily-retro-daily \
  bash ./retro-daily/setup-venv.sh

First run downloads ~600MB of model deps. The dashboard renders even without the venv — only the embedding-driven prompt outcome classification (APPROVAL / REFINEMENT / CORRECTION) is skipped.

How classification works

The prompt classifier hits 98% on tests/eval.json (a 50-pair synthetic dataset). Run python3 tests/eval_classifier.py to verify against your own labels.

Session tags are surfaced as the topics and interaction_types fields per day in metrics-store.json. Untagged sessions (newly created since the last weekly run) show as untagged until the next tagging cycle.

How it works

Every new Claude Code session fires the SessionStart hook, which calls startup.sh. That script runs four steps sequentially; two of them (scout, tag-sessions) spawn detached claude -p background workers and return immediately, so the rest of the dashboard renders without waiting on network or LLM calls.

Full sequence diagram, state-file inventory, and the OS-level sandbox the background workers run under: docs/internals.md.

Files

Uninstall

Plugin install:

/plugin uninstall retro-daily@retro-daily

This also clears ~/.claude/plugins/data/retro-daily-retro-daily/. Pass --keep-data to preserve the metrics store across reinstalls.

Compatibility notes

Claude Code v2.1.x changed how SessionStart hook output reaches the user. Per the hooks docs:

retro-daily's startup.sh emits a JSON document with both systemMessage (so you see the dashboard rendered in your terminal) and hookSpecificOutput.additionalContext (so Claude can answer questions about your stats). On v2.0.x and earlier (line-by-line output, no full-screen TUI), plain stdout would have rendered directly — the JSON envelope works on both.

If you don't see the dashboard at the top of a fresh session: tail /tmp/claude-startup.log to confirm the hook ran and the dashboard was generated, then read docs/troubleshooting.md.

Troubleshooting

Symptoms and fixes — empty dashboard on v2.1.x, scout stuck at queued · last run never, sandbox unavailable: docs/troubleshooting.md.

_{"Claude" and "Claude Code" are trademarks of Anthropic, PBC. This project is not affiliated with, endorsed by, or sponsored by Anthropic.}