mcpField
C
claude-reflect

claude-reflect

github.com/bayramannakovAgent workflows1.9k423 installsUpdated 4w ago
Repository

About claude-reflect

claude-reflect is a Claude Code skill that captures user corrections and lets users review them before adding learnings to instruction files.

Key features

  1. 01Automatic correction capture
  2. 02Human-reviewed learning queue
  3. 03Scan past sessions
  4. 04Preview changes with dry run
  5. 05Suggest skills from repeated patterns

Use cases

  1. 01Preserve corrections for future sessions
  2. 02Separate global and project guidance
  3. 03Review missed learnings from session history

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bayramannakov/claude-reflect --skill claude-reflect

After installing, type/claude-reflectin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

.gitignore
BACKLOG.md
LICENSE
CHANGELOG.md
RELEASING.md
CLAUDE.md
DISTRIBUTION.md
README.md
.claude-plugin/
marketplace.json
plugin.json
.github/
FUNDING.yml
.github/workflows/
test.yml
commands/
skip-reflect.md
view-queue.md
reflect-skills.md
reflect.md
hooks/
hooks.json
mod/
README.md
mod/.claude-plugin/
plugin.json
mod/hooks/
hooks.json
reflect.test.tsx
register.tsx
mod/types/
index.d.ts
scripts/
check_learnings.py
clear_queue.py
compare_detection.py
capture_learning.py
extract_session_learnings.py
extract_tool_errors.py
scripts/legacy/
capture-learning.sh

Details

From the project README

Claude Reflect - Self-Learning System

A two-stage system that helps Claude Code learn from user corrections.

How It Works

Stage 1: Capture (Automatic) Hooks detect correction patterns ("no, use X", "actually...", "use X not Y") and queue them to ~/.claude/learnings-queue.json.

Stage 2: Process (Manual) User runs /reflect to review and apply queued learnings to CLAUDE.md files.

Available Commands

CommandPurpose
/reflectProcess queued learnings with human review
/reflect --scan-historyScan past sessions for missed learnings
/reflect --dry-runPreview changes without applying
/reflect-skillsDiscover skill candidates from repeating patterns
/skip-reflectDiscard all queued learnings
/view-queueView pending learnings without processing

When to Remind Users

Remind users about /reflect when:

  • They complete a feature or meaningful work unit
  • They make corrections you should remember for future sessions
  • They explicitly say "remember this" or similar
  • Context is about to compact and queue has items

Correction Detection Patterns

High-confidence corrections:

  • Tool rejections (user stops an action with guidance)
  • "no, use X" / "don't use Y"
  • "actually..." / "I meant..."
  • "use X not Y" / "X instead of Y"
  • "remember:" (explicit marker)

Learning Destinations

  • ~/.claude/CLAUDE.md - Global learnings (model names, general patterns)
  • ./CLAUDE.md - Project-specific learnings (conventions, tools, structure)
  • ./CLAUDE.local.md - Personal learnings (machine-specific, gitignored)
  • ./.claude/rules/*.md - Modular rules with optional path-scoping
  • ~/.claude/rules/*.md - Global modular rules
  • ~/.claude/projects/<project>/memory/*.md - Auto memory (low-confidence, exploratory)
  • commands/*.md - Skill improvements (corrections during skill execution)

Example Interaction

User: no, use gpt-5.1 not gpt-5 for reasoning tasks
Claude: Got it, I'll use gpt-5.1 for reasoning tasks.

[Hook captures this correction to queue]

User: /reflect
Claude: Found 1 learning queued. "Use gpt-5.1 for reasoning tasks"
        Scope: global
        Apply to ~/.claude/CLAUDE.md? [y/n]

Comments

Markdown supported