claude-reflect
A self-learning system for Claude Code that captures corrections and discovers workflow patterns — turning them into permanent memory and reusable skills.
What it does
1. Learn from Corrections
When you correct Claude ("no, use gpt-5.1 not gpt-5"), it remembers forever.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ You correct │ ──► │ Hook captures │ ──► │ /reflect adds │
│ Claude Code │ │ to queue │ │ to CLAUDE.md │
└─────────────────┘ └─────────────────┘ └─────────────────┘
(automatic) (automatic) (manual review)
2. Discover Workflow Patterns (NEW in v2)
Analyzes your session history to find repeating tasks that could become reusable commands.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Your past │ ──► │ /reflect-skills │ ──► │ Generates │
│ sessions │ │ finds patterns │ │ /commands │
└─────────────────┘ └─────────────────┘ └─────────────────┘
(68 sessions) (AI-powered) (you approve)
Example: You've asked "review my productivity" 12 times → suggests creating /daily-review
Key Features
| Feature | What it does |
|---|
| Permanent Memory | Corrections sync to CLAUDE.md — Claude remembers across sessions |
| Skill Discovery | Finds repeating patterns in your history → generates commands |
| Multi-language | AI understands corrections in any language |
| Skill Improvement | Corrections during /deploy improve the deploy skill itself |
Installation
# Add the marketplace
claude plugin marketplace add bayramannakov/claude-reflect
# Install the plugin
claude plugin install claude-reflect@claude-reflect-marketplace
# IMPORTANT: Restart Claude Code to activate the plugin
After installation, restart Claude Code (exit and reopen). Then hooks auto-configure and commands are ready.
First run? When you run /reflect for the first time, you'll be prompted to scan your past sessions for learnings.
Prerequisites
- Claude Code CLI installed
- Python 3.6+ (included on most systems)
Platform Support
- macOS: Fully supported
- Linux: Fully supported
- Windows: Fully supported (native Python, no WSL required)
Commands
| Command | Description |
|---|
/reflect | Process queued learnings with human review |
/reflect --scan-history | Scan ALL past sessions for missed learnings |
/reflect --dry-run | Preview changes without applying |
/reflect --targets | Show detected config files (CLAUDE.md, AGENTS.md) |
/reflect --review | Show queue with confidence scores and decay status |
/reflect --dedupe | Find and consolidate similar entries in CLAUDE.md |
/reflect --include-tool-errors | Include tool execution errors in scan |
/reflect-skills | Discover skill candidates from repeating patterns |
/reflect-skills --days N | Analyze last N days (default: 14) |
/reflect-skills --project <path> | Analyze specific project |
/reflect-skills --all-projects | Scan all projects for cross-project patterns |
/reflect-skills --dry-run | Preview patterns without generating skill files |
/skip-reflect | Discard all queued learnings |
/view-queue | View pending learnings without processing |
How It Works
Two-Stage Process
Stage 1: Capture (Automatic)
Hooks run automatically to detect and queue corrections:
| Hook | Trigger | Purpose |
|---|
session_start_reminder.py | Session start | Shows pending learnings reminder |
capture_learning.py | Every prompt | Detects correction patterns and queues them |
check_learnings.py | Before compaction | Backs up queue and informs user |
post_commit_reminder.py | After git commit | Reminds to run /reflect after completing work |
Stage 2: Process (Manual)
Run /reflect to review and apply queued learnings to CLAUDE.md.
Detection Methods
Claude-reflect uses a hybrid detection approach:
