Agent Retrospective

agent-retrospective is a Rust CLI that turns local Claude Code and Codex history into a polished retrospective you can read, share, and learn from.

It scans your local session archives, reconstructs substantive working sessions, aggregates patterns across them, and writes:

• an HTML report for browsing
• a JSON export for downstream analysis

The tool is designed for people who want something closer to a personal /insights page for their coding-agent work.

What It Does

• Scans Claude Code history from ~/.claude/projects
• Scans Codex history from ~/.codex/sessions
• Reconstructs branches and keeps the most substantive path
• Caches parsed session metadata for faster reruns
• Extracts per-session facets such as goals, friction, outcomes, and helpfulness
• Aggregates usage patterns across projects, tools, languages, and workflows
• Produces a standalone HTML retrospective and a machine-readable JSON export

Install

From source:

git clone https://github.com/jimmystridh/agent-retrospective.git
cd agent-retrospective
cargo build --release

Then run:

./target/release/agent-retrospective --open

If you prefer an installed binary:

cargo install --path .
agent-retrospective --open

Tagged GitHub releases are also configured to publish prebuilt binaries for supported platforms.

Quick Start

Generate a report from both Claude Code and Codex history and open it in your browser:

agent-retrospective --open

Or without installing first:

cargo run --release -- --open

Common Commands

Scan both sources:

agent-retrospective --source all

Only scan Claude Code:

agent-retrospective --source claude

Only scan Codex:

agent-retrospective --source codex

Parse more uncached sessions on a run:

agent-retrospective --max-new-sessions 500

Rebuild caches from scratch:

agent-retrospective --force-refresh

Write outputs somewhere else:

agent-retrospective --output-dir /tmp/agent-retrospective

Override the source locations:

agent-retrospective \
  --claude-projects-dir /path/to/.claude/projects \
  --codex-sessions-dir /path/to/.codex/sessions

Insight Modes

agent-retrospective supports three analysis modes:

• auto: Use Claude-backed analysis when a local Claude runtime is available, otherwise fall back to heuristics
• heuristic: Keep analysis fully local and rule-based
• claude: Require Claude-backed analysis and fail if Claude is unavailable

Examples:

agent-retrospective --insight-mode heuristic
agent-retrospective --insight-mode claude --claude-model opus

Claude-backed analysis uses the local Claude login or ANTHROPIC_API_KEY when available. In that mode, transcript excerpts and derived summaries may be sent through the Claude SDK to generate richer session facets and the final retrospective narrative.

Output

By default, files are written to ~/.agent-retrospective/:

• HTML report: ~/.agent-retrospective/report.html
• JSON export: ~/.agent-retrospective/report.json
• Session cache: ~/.agent-retrospective/cache/session-meta/
• Facet cache: ~/.agent-retrospective/cache/facets/

The CLI also prints a short run summary including source paths, number of sessions scanned, number analyzed, date range, skipped malformed files, and the output paths.

How It Works

1. Discover session files from Claude Code and/or Codex.
2. Reuse cached metadata when possible.
3. Parse uncached transcripts up to --max-new-sessions.
4. Filter down to substantive sessions.
5. Derive session facets with heuristics or Claude-backed analysis.
6. Aggregate cross-session patterns and render the report.

The first run is usually the slowest. Later runs are much faster because both session metadata and extracted facets are cached.

Notes

• Session caches are namespaced by source, so Claude Code and Codex sessions do not collide.
• Large histories are intentionally processed incrementally to keep first-run latency reasonable.
• claude mode is strict and errors if Claude access is not available.
• auto mode prints a fallback notice when it cannot use Claude.

CLI Reference

Generate a retrospective report from local Claude Code and Codex session history

Usage: agent-retrospective [OPTIONS]

Options:
      --claude-projects-dir <CLAUDE_PROJECTS_DIR>
          [default: ~/.claude/projects]
      --codex-sessions-dir <CODEX_SESSIONS_DIR>
          [default: ~/.codex/sessions]
      --output-dir <OUTPUT_DIR>
          [default: ~/.agent-retrospective]
      --source <SOURCE>
          [default: all] [possible values: all, claude, codex]
      --max-new-sessions <MAX_NEW_SESSIONS>
          [default: 200]
      --force-refresh
      --insight-mode <INSIGHT_MODE>
          [default: auto] [possible values: auto, heuristic, claude]
      --claude-model <CLAUDE_MODEL>
          [default: opus]
      --open
  -h, --help
  -V, --version