
claude-retrospective
Retrospective plugin that analyzes Claude Code sessions to surface successful patterns and problem areas.
- version
- 1.1.1
- GitHub stars
- 165
What it does
- Adds the
retrospectingskill, 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.mdor 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-pluginsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install claude-retrospective@bitwarden-marketplaceRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceAnalyzing 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
-
Determine range type:
- Time-based: Parse relative or absolute time
- Commit-based: Validate commit references exist
- Branch-based: Resolve branch names to commits
-
Validate git repository:
git rev-parse --git-dir -
Check range has commits:
git log <range> --oneline | head -1If 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:
- Large changes (>100 lines modified): Always include
- New files: Include (especially if >50 lines)
- Deleted files: Note but don't diff
- Architecture files:
build.gradle.kts,AndroidManifest.xml, module configs - 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:
- Always start with concise summary
- Ask user: "Would you like detailed diffs for specific files?"
- 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:
- Inform: User understands scope of changes at a glance
- Focus: Highlights most significant changes first
- Actionable: Provides paths and diffs for deeper review
- Efficient: Doesn't waste context on unnecessary details
- 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:
| Depth | Duration | Use Case | Data Collection |
|---|---|---|---|
| Quick | 5-10 min | Simple sessions, rapid feedback | Git stats only, error summary, 2-3 questions |
| Standard | 15-20 min | Typical sessions, balanced analysis | Full commits, selective diffs, metadata, 5-7 questions |
| Comprehensive | 30+ min | Complex sessions, deep-dive analysis | Everything: 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:
- Analyze session to identify improvement opportunities
- Suggest specific updates to
.claude/CLAUDE.md,SKILL.md, or agent definitions - Show proposed changes to user
- 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.mdor 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:
- Session Assessment: Determine appropriate analysis depth based on session size
- Scope Definition: Establish time/commit range and session goals
- Data Collection: Gather git history, logs, code quality metrics, user feedback
- Analysis: Calculate metrics, identify patterns, assess communication effectiveness
- Report Generation: Create structured report using appropriate template
- Validation: Gather user feedback on report accuracy
- Configuration Improvements: Suggest updates to Claude configuration files
- 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:
- Bitwarden Contributing Guidelines
- Repository standards in root
README.md - Code quality requirements in
.editorconfig
Support
- Issues: GitHub Issues
- Documentation: Claude Code Docs
- Marketplace: Bitwarden AI Marketplace
Details
- Marketplace
- bitwarden/ai-plugins
- Source
- plugins/claude-retrospective
- Category
- Community
More from bitwarden/ai-plugins
All 25- atlassian-readerv1.2.1
- bitwarden-abacusv0.2.0
- bitwarden-abacus-toolsv1.3.0
- bitwarden-adr-toolsv1.0.0
- bitwarden-ai-telemetryv1.5.1
- bitwarden-atlassian-toolsv2.9.1
- bitwarden-code-reviewv3.1.0
- bitwarden-delivery-toolsv4.0.1
- bitwarden-design-toolsv0.1.0
- bitwarden-designerv0.1.0
- bitwarden-devops-engineerv0.3.1
- bitwarden-doc-parityv1.1.0
- bitwarden-initv1.2.2
- bitwarden-mailcatcher-toolsv1.0.0
- bitwarden-product-analystv0.1.7
- bitwarden-retrospective-toolsv1.2.0
- bitwarden-security-engineerv2.1.0
- bitwarden-shepherdv1.0.1
- bitwarden-software-engineerv1.1.0
- bitwarden-stripe-toolsv1.0.0
- bitwarden-tech-leadv3.1.0
- bitwarden-testing-toolsv1.5.1
- bitwarden-testmo-toolsv1.0.0
- claude-config-validatorv2.3.1
Similar to claude-retrospective
More Development Tools
reamorluto/rea466.8K starsReverse engineer anything with agents, from app behavior down to native binaries.
superpowersobra/superpowers319.5K starsCore skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques
claude-apianthropics/skills196.9K starsClaude API and SDK documentation skill for building LLM-powered applications
prompts.chatf/prompts.chat178.2K starsAccess thousands of AI prompts and skills directly in your AI coding assistant. Search prompts, discover skills, save your own, and improve prompts with AI.
agent-sdk-devanthropics/claude-code156.1K starsDevelopment kit for working with the Claude Agent SDK
ui-ux-pro-maxnextlevelbuilder/ui-ux-pro-max-skill152.6K starsProfessional UI/UX design intelligence for AI coding assistants. Includes searchable databases of styles, colors, typography, charts, and UX guidelines for Reac