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

claude-reflect in action

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:

*1. Regex patterns (real-time capture)

...

bayramannakov/claude-reflect

README