claude-reflect

A self-learning system for Claude Code that captures corrections and discovers workflow patterns — turning them into permanent memory and reusable skills.

Two ways to run it:

	Plugin (Python)	Mod (reflect-mod, new in 3.3)
You correct Claude	a hook queues it	a model check sees it at once, in any language
You review	later, with /reflect	right away, in a band above the prompt
Runs on	Claude Code, plus Codex/Cursor via AGENTS.md	Claude Code 2.1.286+ with mods

Pick one. Install the plugin or the mod.

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)

New: claude-reflect as a mod (early access)

Claude Code mods run inside the session, so the same idea works without a queue you have to remember to review:

• Every short prompt (500 characters or less, not "ok"/"continue", not a slash command) goes to a one-shot model check (haiku by default) that decides whether it holds a reusable rule. It reads intent, not keywords, so corrections in any language count ("нет, используй pnpm" works).
• A band above the prompt shows each rule it finds, with Save, Global/This repo instead, Edit and Skip. You decide in the moment; repeats merge into one row with a count (×3).
• Save adds a bullet inside a marked section of ~/.claude/CLAUDE.md or ./CLAUDE.md, and the rule applies in the current session at once. Nothing is written without a press.
• remember: <rule> skips the model. /reflect-queue lists what it found; /reflect-pause turns it off.

claude plugin marketplace add bayramannakov/claude-reflect
claude plugin install reflect-mod@claude-reflect-marketplace

Needs Claude Code 2.1.286 or newer with mods enabled. Each checked prompt is one small model call on your own Claude account. Install either the mod or the Python plugin above, not both: with both, every correction is captured twice. The Python plugin stays the choice for /reflect --scan-history, --dedupe, --organize, /reflect-skills, and for Codex/Cursor users. Details: mod/README.md.

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	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