New advertisers: 50% off your first month with code FIRSTMONTHSee slots
bitwarden avatar

claude-retrospective

Retrospective plugin that analyzes Claude Code sessions to surface successful patterns and problem areas.

version
1.1.1
GitHub stars
165
View on GitHub

What it does

  • Adds the retrospecting skill, which combines git history, session logs, code metrics, and user feedback into a structured report
  • Offers Quick, Standard, and Comprehensive analysis depths, with the recommended depth set by session size
  • Ties each finding to concrete evidence, such as file:line citations, and proposes changes to .claude/CLAUDE.md or skill files
  • Designed for post-session reviews, feature retrospectives, and trend analysis across several sessions

Comprehensive analysis of Claude Code sessions to identify successful patterns, problematic areas, and opportunities for improvement.

Add marketplace

/plugin marketplace add bitwarden/ai-plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install claude-retrospective@bitwarden-marketplace

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Analyzing Git Sessions

Core Responsibility

Generate structured analysis of git activity for specified timeframe or commit range, including commit history, file changes, statistics, and optional diffs.

Inputs

Accept from user:

  • Time range: "last 2 hours", "since 10am", "today", "since 2025-10-23 14:00"
  • Commit range: "abc123..def456", "HEAD~5..HEAD", "feature-branch..main"
  • Optional filters: Specific paths, authors, or file types
  • Output depth: Concise (default), Detailed, or Code Review format

Working Process

Step 1: Parse and Validate Input

  1. Determine range type:

    • Time-based: Parse relative or absolute time
    • Commit-based: Validate commit references exist
    • Branch-based: Resolve branch names to commits
  2. Validate git repository:

    git rev-parse --git-dir
    
  3. Check range has commits:

    git log <range> --oneline | head -1
    

    If empty, inform user and exit.

Step 2: Extract Commit History

# Get all commits in range
git log <range> --oneline --no-decorate

# Get detailed commit info
git log <range> --format="%h|%an|%ar|%s" --no-decorate

# Count commits
git log <range> --oneline | wc -l

Store commit data for summary.

Step 3: Generate Statistics

Overall change statistics:

# Summary stats (insertions/deletions by file)
git diff <start>..<end> --stat

# Numeric stats for parsing
git diff <start>..<end> --numstat

# Count total changes
git diff <start>..<end> --shortstat

Author breakdown (if multiple authors):

git shortlog <start>..<end> -sn

File categorization:

  • Identify new files (show in status "A")
  • Identify deleted files (show in status "D")
  • Identify renamed files (show in status "R")
  • Modified files with change magnitude

Step 4: Identify Key Files for Detailed Analysis

Prioritization rules:

  1. Large changes (>100 lines modified): Always include
  2. New files: Include (especially if >50 lines)
  3. Deleted files: Note but don't diff
  4. Architecture files: build.gradle.kts, AndroidManifest.xml, module configs
  5. Test files: Flag separately for test coverage assessment

Extract key file list:

# Files changed with line counts
git diff <start>..<end> --numstat | sort -rn -k1 -k2

Limit to top 10 files by default to avoid context overflow.

Step 5: Generate Selective Diffs (Based on Depth)

Concise mode: No diffs, stats only

Detailed mode: Diffs for top 3-5 key files

git diff <start>..<end> -- path/to/key/file.kt

Code Review mode: Diffs for all modified files, grouped by module

# Group by directory
git diff <start>..<end> --name-only | cut -d'/' -f1-2 | sort -u

# Generate diffs per module
for module in modules; do
  git diff <start>..<end> -- $module/
done

Context overflow protection:

  • If >10 files changed significantly, limit to top 5 diffs
  • Warn user: "Showing top 5 files by change size. Request specific files for full diffs."

Step 6: Present Structured Summary

Format based on depth:

Concise Summary
## Git Session Summary

**Range**: <start-commit> to <end-commit> (<timeframe>)
**Commits**: X commits by Y author(s)
**Files Changed**: A modified, B added, C deleted
**Net Changes**: +X -Y lines

### Commits

- abc123 Commit message 1
- def456 Commit message 2
  ...

### Top Files Changed

1. path/to/file1.kt (+50 -20)
2. path/to/file2.kt (+30 -15)
   ...
Detailed Summary

Includes:

  • Full commit list with authors and timestamps
  • Complete file list with change stats
  • Author breakdown
  • Top 3-5 diffs for review
Code Review Format
## Code Review Summary

### Overview

- **PR Title**: [Suggested from commit messages]
- **Changes**: X files across Y modules
- **Scope**: [Inferred from changed files]

### Commits

[Formatted commit list suitable for PR description]

### Changes by Module

**Module: app**

- file1.kt: Description of changes
- file2.kt: Description of changes

**Module: core**
...

### Key Changes

[Diffs for significant modifications]

### Test Coverage

- Test files modified: X
- New tests added: ~Y

Output Guidelines

Commit Messages

  • Show short hash (7 chars)
  • Show first line of commit message only
  • Truncate long messages to 80 chars
  • Group by author if multiple contributors

File Paths

  • Use relative paths from repo root
  • Format as code: path/to/file.kt
  • Include line change magnitude: (+X -Y)
  • Highlight file type (source, test, config)

Statistics

Present in clear tables:

| Metric        | Count |
| ------------- | ----- |
| Commits       | 15    |
| Files Changed | 23    |
| Insertions    | +450  |
| Deletions     | -180  |

Diffs

  • Include file path as header: ### path/to/file.kt
  • Use code blocks with syntax highlighting
  • Show context lines (git default: 3 lines before/after)
  • Truncate very large diffs (>200 lines) with summary

Context Budget Management

Monitor diff sizes:

  • Small session (<10 files, <500 lines): Safe for detailed mode
  • Medium session (10-30 files, 500-2000 lines): Use selective diffs
  • Large session (>30 files, >2000 lines): Concise mode with warnings

Progressive disclosure:

  1. Always start with concise summary
  2. Ask user: "Would you like detailed diffs for specific files?"
  3. Generate diffs on demand rather than upfront

Fallback for large sessions: "This session modified 45 files with 5000+ line changes. Showing concise summary. Request specific files or modules for detailed diffs."

Anti-Patterns to Avoid

Don't:

  • Generate diffs for all files in large sessions (context overflow)
  • Include full diffs without asking (waste context on unneeded details)
  • Ignore file types (treat test changes same as source changes)
  • Lose context on what user wants to know
  • Use generic summaries ("modified 10 files") without specifics

Do:

  • Ask user what level of detail they need
  • Prioritize key files by change magnitude
  • Categorize files (source, test, config, docs)
  • Provide actionable summaries
  • Offer to drill down on specific files

Success Criteria

A good git session analysis should:

  1. Inform: User understands scope of changes at a glance
  2. Focus: Highlights most significant changes first
  3. Actionable: Provides paths and diffs for deeper review
  4. Efficient: Doesn't waste context on unnecessary details
  5. Adaptable: Adjusts depth based on session size and user needs

Example Outputs

See contexts/example-outputs.md for detailed examples of concise summaries and code review formats.

Readme

Claude Retrospective Plugin

Comprehensive analysis of Claude Code sessions to identify successful patterns, problematic areas, and opportunities for improvement through multi-source data collection and evidence-based insights.

Overview

The Claude Retrospective plugin provides systematic session analysis capabilities for Claude Code, helping you understand what worked well, what didn't, and how to continuously improve your AI-assisted development workflows. By examining git history, conversation logs, code quality metrics, and user feedback, it generates actionable retrospective reports that drive continuous improvement.

Features

Multi-Source Data Collection

Systematically gathers data from all available sources:

  • Git History: Commits, diffs, file changes during session timeframe
  • Claude Native Session Logs: Conversation transcripts from ~/.claude/projects/{project-dir}/{session-id}.jsonl
  • Code Quality Metrics: Test coverage, compilation status, standard compliance
  • User Feedback: Direct input about goals, satisfaction, and pain points
  • Sub-agent Analysis: Feedback from specialized agents used during the session

Flexible Analysis Depths

Choose the right level of analysis for your needs:

DepthDurationUse CaseData Collection
Quick5-10 minSimple sessions, rapid feedbackGit stats only, error summary, 2-3 questions
Standard15-20 minTypical sessions, balanced analysisFull commits, selective diffs, metadata, 5-7 questions
Comprehensive30+ minComplex sessions, deep-dive analysisEverything: full logs, diffs, quality metrics, 8-10 questions

The skill automatically recommends an appropriate depth based on session size (commits, log volume) but allows user override.

Evidence-Based Insights

Every finding is backed by concrete evidence:

  • Quantitative Metrics: Session scope, quality indicators, efficiency metrics
  • Qualitative Assessment: Successful patterns, problematic areas, root causes
  • Specific References: File:line citations for all claims
  • Actionable Recommendations: What, why, how, and expected impact

Configuration Improvement Loop

Retrospectives can identify patterns that should become standard practice:

  1. Analyze session to identify improvement opportunities
  2. Suggest specific updates to .claude/CLAUDE.md, SKILL.md, or agent definitions
  3. Show proposed changes to user
  4. Apply with approval, creating continuous improvement cycle

Context-Aware Processing

Intelligent handling of large sessions to prevent context overflow:

  • Checks session size before loading data
  • Adjusts depth automatically based on available context budget
  • Uses targeted extraction for large log files (>2000 lines)
  • Progressive disclosure: start high-level, drill down on request

Installation

Add Bitwarden Marketplace (if not already added)

/plugin marketplace add bitwarden/ai-marketplace

Install the Plugin

/plugin install claude-retrospective@bitwarden-marketplace

Usage

Basic Invocation

Natural language:

  • "Can you do a retrospective on what we just accomplished?"
  • "How did that session go?"
  • "Analyze the last 2 hours of work"
  • "What could we improve about how we worked together?"

Direct skill invocation:

/skill retrospecting

Use Cases

1. Post-Session Review

Scenario: You've completed a coding session and want to understand what worked well and what could be improved.

Usage:

Do a retrospective on the last 2 hours of work

Output:

  • Quantitative metrics (commits, files changed, test coverage)
  • Success patterns identified with evidence
  • Pain points with root causes
  • Prioritized recommendations for future sessions

2. Feature Implementation Analysis

Scenario: You've completed a significant feature implementation and want detailed analysis of the approach and outcomes.

Usage:

I want a comprehensive retrospective on the authentication refactor we completed today

Output:

  • Detailed git analysis with commit-by-commit review
  • Code quality assessment
  • Architecture decisions made and their rationale
  • Testing coverage and quality
  • Communication effectiveness
  • Reusable patterns extracted for future use

3. Troubleshooting Workflow Issues

Scenario: A session felt inefficient or frustrating, and you want to identify specific bottlenecks.

Usage:

Analyze why testing took so long in this session

Output:

  • Focused analysis on testing workflow
  • Identification of specific delays (test failures, environment issues, unclear requirements)
  • Root cause analysis for each bottleneck
  • Specific recommendations to improve testing efficiency

4. Pattern Library Building

Scenario: You want to extract successful approaches from a particularly effective session to replicate in future work.

Usage:

This session went really smoothly - help me identify the patterns we should keep using

Output:

  • Successful patterns documented with examples
  • Environmental factors that contributed to success
  • Recommendations for codifying patterns in configuration files
  • Suggestions for .claude/CLAUDE.md or skill updates

5. Multi-Session Trend Analysis

Scenario: You want to analyze patterns across multiple sessions to identify systemic issues or improvements.

Usage:

Analyze all sessions from the last week and identify trends

Output:

  • Aggregated metrics across sessions
  • Common success patterns and recurring issues
  • Workflow trends (improving, declining, stable)
  • Strategic recommendations for long-term improvement

Skills Included

retrospecting

Description: Performs comprehensive analysis of Claude Code sessions, examining git history, conversation logs, code changes, and user feedback to generate actionable retrospective reports.

Working Process:

  1. Session Assessment: Determine appropriate analysis depth based on session size
  2. Scope Definition: Establish time/commit range and session goals
  3. Data Collection: Gather git history, logs, code quality metrics, user feedback
  4. Analysis: Calculate metrics, identify patterns, assess communication effectiveness
  5. Report Generation: Create structured report using appropriate template
  6. Validation: Gather user feedback on report accuracy
  7. Configuration Improvements: Suggest updates to Claude configuration files
  8. Archive Information: Document where session logs are stored

Output: Structured markdown reports saved to ${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/


extracting-session-data

Description: Locates, lists, filters, and extracts structured data from Claude Code native session logs stored in ~/.claude/projects/{project-dir}/{session-id}.jsonl.

Capabilities:

  • locate-logs.sh: Find log directories and session file paths
  • list-sessions.sh: Enumerate sessions with metadata (ID, size, lines, date, branch)
  • extract-data.sh: Parse JSONL logs and extract specific data types:
    • Metadata (session info, timestamps, branch)
    • User prompts
    • Tool usage statistics
    • Errors and failed tool calls
    • Thinking blocks (if extended thinking enabled)
    • Text responses
    • Session statistics
  • filter-sessions.sh: Find sessions by criteria (date range, branch, size, errors, keywords)

Key Principle: Extracts raw data only - returns data to calling skills for analysis without interpretation.


analyzing-git-sessions

Description: Analyzes git commits and changes within a timeframe or commit range, providing structured summaries for code review, retrospectives, or work logs.

Capabilities:

  • Parse time ranges ("last 2 hours", "since 10am") or commit ranges ("abc123..def456")
  • Extract commit history with authors and timestamps
  • Generate change statistics (insertions/deletions by file)
  • Identify key files for detailed analysis (prioritized by change size)
  • Provide selective diffs based on depth (concise/detailed/code review)
  • Categorize files by type (source, test, config, docs)
  • Handle large sessions with context overflow protection

Output Formats:

  • Concise: Stats only, no diffs
  • Detailed: Top 3-5 file diffs
  • Code Review: Full analysis grouped by module

Report Structure

Quick Retrospective Template

## Session Summary

- Duration: X hours
- Goals: [What you were trying to accomplish]
- Outcome: [Success/Partial/Issues]

## Highlights

- [Top 2-3 successes]

## Challenges

- [Main 1-2 issues encountered]

## Key Learnings

- [Most important insight]

## Action Items

1. [First priority improvement]
2. [Second priority improvement]

Comprehensive Retrospective Template

## Executive Summary

- Session scope metrics
- Overall assessment
- Key achievements

## Session Metrics

[Quantitative data table]

## What Went Well

[Success patterns with evidence]

## Pain Points

[Issues with root cause analysis]

## Workflow Analysis

- Communication effectiveness
- Tool usage patterns
- Decision-making quality

## Code Quality Assessment

- Test coverage
- Compilation success
- Standard compliance

## Recommendations

[Prioritized by impact: High/Medium/Low]

## Patterns for Future Reference

- Successful approaches to replicate
- Anti-patterns to avoid

## Configuration Suggestions

[Proposed updates to .claude files]

File Organization

plugins/claude-retrospective/
├── .claude-plugin/
│   └── plugin.json                       # Plugin manifest
├── skills/
│   ├── retrospecting/
│   │   ├── SKILL.md                      # Main retrospective skill
│   │   ├── README.md                     # User documentation
│   │   ├── contexts/
│   │   │   └── session-analytics.md     # Analysis framework (auto-loaded)
│   │   ├── templates/
│   │   │   └── retrospective-templates.md # Report templates (auto-loaded)
│   │   ├── reports/                      # Generated reports (YYYY-MM-DD-*.md)
│   │   └── scripts/
│   │       └── analyze-session-logs.sh  # Helper script
│   ├── extracting-session-data/
│   │   ├── SKILL.md                      # Log extraction skill
│   │   ├── README.md                     # Extraction documentation
│   │   └── scripts/
│   │       ├── locate-logs.sh           # Find log directories
│   │       ├── list-sessions.sh         # List all sessions
│   │       ├── extract-data.sh          # Extract specific data types
│   │       └── filter-sessions.sh       # Filter by criteria
│   └── analyzing-git-sessions/
│       ├── SKILL.md                      # Git analysis skill
│       ├── README.md                     # Git analysis documentation
│       └── contexts/
│           └── example-outputs.md       # Example git summaries
└── README.md                             # This file

Tips for Best Results

Provide Clear Session Goals

When asked "What were you trying to accomplish?", be specific:

  • ✅ Good: "Refactor authentication to use biometric providers and add unit tests"
  • ❌ Less helpful: "Work on authentication"

Be Honest About Pain Points

Candid feedback leads to better insights:

  • Where did you get confused?
  • What took longer than expected?
  • What would you change about the workflow?

Use Retrospectives Regularly

  • After major features: Capture complex implementation insights
  • Weekly/sprint boundaries: Track progress and improvement trends
  • After challenging sessions: Learn from difficulties
  • After smooth sessions: Identify what made them effective

Follow Up on Recommendations

Retrospectives are most valuable when acted upon:

  • Implement high-priority improvements in next session
  • Update configuration files with better practices
  • Share learnings with team (if applicable)

Dependencies

Required:

  • bash (v4.0+)
  • jq (JSON parser for log extraction)

Scripts check for jq and provide installation instructions if missing:

brew install jq  # macOS
apt-get install jq  # Linux

Privacy & Security

What Data is Analyzed

  • Git commits and diffs visible in your repository
  • Claude Code native session logs from ~/.claude/projects/{project-dir}/
  • File contents of changed files
  • Your explicit feedback responses

Data Storage

  • All analysis happens locally in your session
  • Reports stored in your repository (.claude/skills/retrospecting/reports/)
  • No data sent to external services
  • Session logs managed by Claude Code (can be deleted after retrospective if desired)

Sensitive Information

If your session involved sensitive data:

  • Review generated reports before committing them
  • Retrospectives can be run without committing reports
  • You can request specific sections be excluded from the report

Troubleshooting

"Session logs not found"

  • Session logs are automatically generated by Claude Code in ~/.claude/projects/{project-dir}/
  • Project directory is derived from your working directory (slashes replaced with dashes)
  • Example: /Users/user/project → ~/.claude/projects/-Users-user-project/
  • You can still do a retrospective using git history + your feedback if logs are unavailable

"Report seems generic"

  • Provide more specific session goals upfront
  • Add detailed feedback when prompted
  • Request a comprehensive retrospective for deeper analysis

"Analysis doesn't match my experience"

  • The validation step is designed for this feedback
  • Tell the skill what's missing or incorrect
  • It will refine the analysis based on your input

"Context window exceeded"

  • Request a "quick" retrospective for large sessions
  • The skill will summarize logs instead of reading them fully
  • Focus on specific areas rather than comprehensive analysis

Contributing

Contributions welcome! Please follow:

Support

Details

Marketplace
bitwarden/ai-plugins
Source
plugins/claude-retrospective
Category
Community

More from bitwarden/ai-plugins

All 25

Similar to claude-retrospective

More Development Tools