The Problem
Claude Code sessions are ephemeral by default. Corrections made in one session are lost when Claude restarts, forcing repetitive corrections across sessions. Users also lack visibility into recurring workflow patterns that could be abstracted into reusable commands, wasting time on tasks performed regularly but never systematized.
What This Does
claude-reflect implements a self-learning loop for Claude Code. The scripts/capturelearning.py hook automatically captures corrections entered during a session and adds them to a queue. scripts/checklearnings.py then processes this queue, syncing validated corrections to CLAUDE.md so Claude retains them across sessions. A separate pipeline runs scripts/reflect-skills.md pattern detection against past session history to identify repeating tasks; approved patterns generate new /commands that users can invoke directly.
The codebase organizes around scripts/ (17 files handling capture, extraction, and comparison logic), commands/ (4 markdown files defining CLI behavior), and hooks/hooks.json (hook registration). Legacy scripts exist in scripts/legacy/ but appear to be superseded by the Python equivalents.
How To Use It
Setup: Install via the Claude Code plugin marketplace as documented in the README: claude plugin marketplace add bayramannakov/claude-reflect followed by claude plugin install claude-reflect@claude-reflect-marketplace. Restart Claude Code to activate hooks.
Configuration: No environment variables or API keys are required. The system hooks into Claude Code's existing event pipeline through .claude-plugin/plugin.json and .claude-plugin/marketplace.json.
Running it: Invoke /reflect within Claude Code to process the queued learnings with human review. Additional flags target specific operations: --scan-history reanalyzes all past sessions, --dry-run previews changes without applying, and --review displays the queue with confidence scores. The /reflect-skills command discovers skill candidates from repeating patterns across sessions.
Real-World Use
A user corrects Claude during a session: "use black not autoformat for Python files." The hooks/hooks.json capture records this correction. On the next session start, scripts/capture_learning.py adds it to the queue. When /reflect runs, the correction syncs to CLAUDE.md, and Claude applies black formatting automatically henceforth. After 12 similar corrections about code review workflows, /reflect-skills detects the pattern and suggests generating a /daily-review command.
Code Health & Issues
Tests & CI: 7 test files exist with 160 passing tests, and GitHub Actions CI is configured in .github/workflows/test.yml. Coverage appears comprehensive for the core learning capture and detection pipelines. Legacy debt: scripts/legacy/ contains shell-based counterparts (capture-learning.sh, check-learnings.sh, etc.) that appear to be in maintenance mode; the Python equivalents in scripts/ are the active implementation. Dependency hygiene: No package manager lockfile or pyproject.toml is visible in the structure, making exact dependency versions unclear. Entry point clarity: The CLI commands (/reflect, /reflect-skills) are defined in commands/reflect.md and commands/reflect-skills.md, but the exact mapping from command to script execution path would benefit from tracing the hook → script invocation flow.
The Bottom Line
claude-reflect delivers a functional self-learning layer for Claude Code with minimal setup—corrections persist across sessions, and pattern detection can surface reusable commands. It's well-suited for power users or teams who spend significant time correcting Claude's behavior and want to systematize recurring workflows. The main trade-off is that it requires staying within the Claude Code ecosystem and resting on the assumption that session history contains enough repetition to yield useful patterns.