claude-reflect

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:

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

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

How It Works

Two-Stage Process

Stage 1: Capture (Automatic)

Hooks run automatically to detect and queue corrections:

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)

Fast pattern matching during sessions detects:

• Corrections: "no, use X" / "don't use Y" / "actually..." / "that's wrong"
• Positive feedback: "Perfect!" / "Exactly right" / "Great approach"
• Explicit markers: "remember:" — highest confidence

2. Semantic AI validation (during /reflect)

When you run /reflect, an AI-powered semantic filter:

• Multi-language support — understands corrections in any language
• Better accuracy — filters out false positives from regex
• Cleaner learnings — extracts concise, actionable statements

Example: A Spanish correction like "no, usa Python" is correctly detected even though it doesn't match English patterns.

Each captured learning has a confidence score (0.60-0.95). The final score is the higher of regex and semantic confidence.

Human Review

When you run /reflect, Claude presents a summary table with options:

• Apply - Accept the learning and add to CLAUDE.md
• Edit before applying - Modify the learning text first
• Skip - Don't apply this learning

Multi-Target Sync

Approved learnings are synced to:

• ~/.claude/CLAUDE.md (global - applies to all projects)
• ./CLAUDE.md (project-specific)
• ./**/CLAUDE.md (subdirectories - auto-discovered)
• ./.claude/commands/*.md (skill files - when correction relates to a skill)
• AGENTS.md (if exists - works with Codex, Cursor, Aider, Jules, Zed, Factory)
• Docs reachable from the above via @filename includes or markdown links (bounded depth, cycles handled, code blocks/external URLs skipped) — useful when CLAUDE.md delegates guidance to standards.md, architecture.md, etc.

Run /reflect --targets to see which files will be updated.

Skill Discovery

Run /reflect-skills to discover repeating patterns in your sessions that could become reusable skills:

/reflect-skills                 # Analyze current project (last 14 days)
/reflect-skills --days 30       # Analyze last 30 days
/reflect-skills --all-projects  # Analyze all projects (slower)
/reflect-skills --dry-run       # Preview patterns without generating files

Features:

• AI-powered detection — uses reasoning, not regex, to find patterns
• Semantic similarity — detects same intent across different phrasings
• Project-aware — groups patterns by project, suggests correct location
• Smart assignment — asks where each skill should go (project vs global)
• Generates skill files — creates draft skills in .claude/commands/

How it works:

The skill discovers patterns by analyzing your session history semantically. Different phrasings of the same intent are recognized:

Session 1: "review my productivity for today"
Session 2: "how was my focus this afternoon?"
Session 3: "check my ActivityWatch data"
Session 4: "evaluate my work hours"

Claude reasons: "These 4 requests have the same intent - reviewing productivity data. The workflow is: fetch time tracking data → categorize activities → calculate focus score. This is a strong candidate for /daily-review."

Example output:

════════════════════════════════════════════════════════════
SKILL CANDIDATES DISCOVERED
════════════════════════════════════════════════════════════

Found 2 potential skills from analyzing 68 sessions:

1. /daily-review (High) — from my-productivity-tools
   → Review productivity using time tracking data
   Evidence: 15 similar requests
   Corrections learned: "use local timezone", "chat apps can be work"

2. /deploy-app (High) — from my-webapp
   → Deploy application with pre-flight checks
   Evidence: 10 similar requests
   Corrections learned: "always run tests first"

════════════════════════════════════════════════════════════

Which skills should I generate?
> [1] /daily-review, [2] /deploy-app

Where should each skill be created?
┌──────────────────────┬─────────────────────────┐
│ /daily-review        │ my-productivity-tools   │
│ /deploy-app          │ my-webapp               │
└──────────────────────┴─────────────────────────┘

Skills created:
  ~/projects/my-productivity-tools/.claude/commands/daily-review.md
  ~/projects/my-webapp/.claude/commands/deploy-app.md

Generated skill file example:

---
description: Deploy application with pre-flight checks
allowed-tools: Bash, Read, Write
---

## Context
Deployment scripts in ./scripts/deploy/

## Your Task
Deploy the application to the specified environment.

### Steps
1. Run test suite
2. Build production assets
3. Deploy to target environment
4. Verify deployment health

### Guardrails
- Always run tests before deploying
- Never deploy to production on Fridays
- Check for pending migrations

---
*Generated by /reflect-skills from 10 session patterns*

Skill Improvement Routing