Skip to content
Back to search

claude-reflect-marketplace

MarketplaceWorks with Claude CodeGitHub

Official marketplace for claude-reflect, a self-learning plugin for Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bayramannakov--claude-reflect/badge.svg)](/listings/bayramannakov--claude-reflect)

HTML

<a href="/listings/bayramannakov--claude-reflect"><img src="/api/listings/bayramannakov--claude-reflect/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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](https://claude.ai/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](https://claude.dev/blog/getting-started-with-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`](mod/README.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "claude-reflect-marketplace",
  3. "description": "Official marketplace for claude-reflect, a self-learning plugin for Claude Code",
  4. "owner": {
  5. "name": "Bayram Annakov"
  6. },
  7. "plugins": [
  8. {
  9. "name": "claude-reflect",
  10. "source": "./",
  11. "description": "Self-learning system that captures corrections and updates CLAUDE.md"
  12. },
  13. {
  14. "name": "reflect-mod",
  15. "source": "./mod",
  16. "description": "claude-reflect as a Claude Code mod (early access): checks each short prompt with a model, saves rules from a band above the prompt"
  17. }
  18. ]
  19. }
README.md · README · 452 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # claude-reflect
  2. [![GitHub stars](https://img.shields.io/github/stars/BayramAnnakov/claude-reflect?style=flat-square)](https://github.com/BayramAnnakov/claude-reflect/stargazers)
  3. [![Version](https://img.shields.io/badge/version-3.3.1-blue?style=flat-square)](https://github.com/BayramAnnakov/claude-reflect/releases)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](https://opensource.org/licenses/MIT)
  5. [![Tests](https://img.shields.io/badge/tests-332%20passing-brightgreen?style=flat-square)](https://github.com/BayramAnnakov/claude-reflect/actions)
  6. [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square)](https://github.com/BayramAnnakov/claude-reflect#platform-support)
  7. A self-learning system for Claude Code that captures corrections and discovers workflow patterns — turning them into permanent memory and reusable skills.
  8. **Two ways to run it:**
  9. | | **Plugin** (Python) | **Mod** (`reflect-mod`, new in 3.3) |
  10. |---|---|---|
  11. | You correct Claude | a hook queues it | a model check sees it at once, in any language |
  12. | You review | later, with `/reflect` | right away, in a band above the prompt |
  13. | Runs on | Claude Code, plus Codex/Cursor via AGENTS.md | Claude Code 2.1.286+ with mods |
  14. ![reflect-mod: a correction becomes a rule you can save with one press](assets/reflect-mod-band.png)
  15. Pick one. [Install the plugin](#installation) or [the mod](#new-claude-reflect-as-a-mod-early-access).
  16. ## What it does
  17. ### 1. Learn from Corrections
  18. When you correct Claude ("no, use gpt-5.1 not gpt-5"), it remembers forever.
  19. ```
  20. ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
  21. │ You correct │ ──► │ Hook captures │ ──► │ /reflect adds │
  22. │ Claude Code │ │ to queue │ │ to CLAUDE.md │
  23. └─────────────────┘ └─────────────────┘ └─────────────────┘
  24. (automatic) (automatic) (manual review)
  25. ```
  26. ### 2. Discover Workflow Patterns (NEW in v2)
  27. Analyzes your session history to find repeating tasks that could become reusable commands.
  28. ```
  29. ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
  30. │ Your past │ ──► │ /reflect-skills │ ──► │ Generates │
  31. │ sessions │ │ finds patterns │ │ /commands │
  32. └─────────────────┘ └─────────────────┘ └─────────────────┘
  33. (68 sessions) (AI-powered) (you approve)
  34. ```
  35. Example: You've asked "review my productivity" 12 times → suggests creating `/daily-review`
  36. ## Key Features
  37. | Feature | What it does |
  38. |---------|--------------|
  39. | **Permanent Memory** | Corrections sync to CLAUDE.md — Claude remembers across sessions |
  40. | **Skill Discovery** | Finds repeating patterns in your history → generates commands |
  41. | **Multi-language** | AI understands corrections in any language |
  42. | **Skill Improvement** | Corrections during `/deploy` improve the deploy skill itself |
  43. ## Installation
  44. ```bash
  45. # Add the marketplace
  46. claude plugin marketplace add bayramannakov/claude-reflect
  47. # Install the plugin
  48. claude plugin install claude-reflect@claude-reflect-marketplace
  49. # IMPORTANT: Restart Claude Code to activate the plugin
  50. ```
  51. After installation, **restart Claude Code** (exit and reopen). Then hooks auto-configure and commands are ready.
  52. > **First run?** When you run `/reflect` for the first time, you'll be prompted to scan your past sessions for learnings.
  53. ### Prerequisites
  54. - [Claude Code](https://claude.ai/code) CLI installed
  55. - Python 3.6+ (included on most systems)
  56. ### Platform Support
  57. - **macOS**: Fully supported
  58. - **Linux**: Fully supported
  59. - **Windows**: Fully supported (native Python, no WSL required)
  60. ### New: claude-reflect as a mod (early access)
  61. Claude Code [mods](https://claude.dev/blog/getting-started-with-claude-code-mods/) run inside the session, so the
  62. same idea works without a queue you have to remember to review:
  63. - **Every short prompt** (500 characters or less, not "ok"/"continue", not a slash command) goes to a one-shot
  64. model check (`haiku` by default) that decides whether it holds a reusable rule. It reads intent, not keywords,
  65. so corrections in any language count ("нет, используй pnpm" works).
  66. - **A band above the prompt** shows each rule it finds, with **Save**, **Global/This repo instead**, **Edit** and
  67. **Skip**. You decide in the moment; repeats merge into one row with a count (`×3`).
  68. - **Save** adds a bullet inside a marked section of `~/.claude/CLAUDE.md` or `./CLAUDE.md`, and the rule applies
  69. in the current session at once. Nothing is written without a press.
  70. - `remember: <rule>` skips the model. `/reflect-queue` lists what it found; `/reflect-pause` turns it off.
  71. ```bash
  72. claude plugin marketplace add bayramannakov/claude-reflect
  73. claude plugin install reflect-mod@claude-reflect-marketplace
  74. ```
  75. Needs Claude Code **2.1.286 or newer** with mods enabled. Each checked prompt is one small model call on your
  76. own Claude account. Install **either** the mod **or** the Python plugin above, not both: with both, every
  77. correction is captured twice. The Python plugin stays the choice for `/reflect --scan-history`, `--dedupe`,
  78. `--organize`, `/reflect-skills`, and for Codex/Cursor users. Details: [`mod/README.md`](mod/README.md).
  79. ## Commands
  80. | Command | Description |
  81. |---------|-------------|
  82. | `/reflect` | Process queued learnings with human review |
  83. | `/reflect --scan-history` | Scan ALL past sessions for missed learnings |
  84. | `/reflect --dry-run` | Preview changes without applying |
  85. | `/reflect --targets` | Show detected config files (CLAUDE.md, AGENTS.md) |
  86. | `/reflect --review` | Show queue with confidence scores and decay status |
  87. | `/reflect --dedupe` | Find and consolidate similar entries in CLAUDE.md |
  88. | `/reflect --include-tool-errors` | Include tool execution errors in scan |
  89. | `/reflect-skills` | Discover skill candidates from repeating patterns |
  90. | `/reflect-skills --days N` | Analyze last N days (default: 14) |
  91. | `/reflect-skills --project <path>` | Analyze specific project |
  92. | `/reflect-skills --all-projects` | Scan all projects for cross-project patterns |
  93. | `/reflect-skills --dry-run` | Preview patterns without generating skill files |
  94. | `/skip-reflect` | Discard all queued learnings |
  95. | `/view-queue` | View pending learnings without processing |
  96. ## How It Works
  97. ![claude-reflect in action](assets/reflect-demo.jpg)
  98. ### Two-Stage Process
  99. **Stage 1: Capture (Automatic)**
  100. Hooks run automatically to detect and queue corrections:
  101. | Hook | Trigger | Purpose |
  102. |------|---------|---------|
  103. | `session_start_reminder.py` | Session start | Shows pending learnings reminder |
  104. | `capture_learning.py` | Every prompt | Detects correction patterns and queues them |
  105. | `check_learnings.py` | Before compaction | Backs up queue and informs user |
  106. | `post_commit_reminder.py` | After git commit | Reminds to run /reflect after completing work |
  107. **Stage 2: Process (Manual)**
  108. Run `/reflect` to review and apply queued learnings to CLAUDE.md.
  109. ### Detection Methods
  110. Claude-reflect uses a **hybrid detection approach**:
  111. **1. Regex patterns (real-time capture)**
  112. Fast pattern matching during sessions detects:
  113. - **Corrections**: `"no, use X"` / `"don't use Y"` / `"actually..."` / `"that's wrong"`
  114. - **Positive feedback**: `"Perfect!"` / `"Exactly right"` / `"Great approach"`
  115. - **Explicit markers**: `"remember:"` — highest confidence
  116. **2. Semantic AI validation (during /reflect)**
  117. When you run `/reflect`, an AI-powered semantic filter:
  118. - **Multi-language support** — understands corrections in any language
  119. - **Better accuracy** — filters out false positives from regex
  120. - **Cleaner learnings** — extracts concise, actionable statements
  121. Example: A Spanish correction like `"no, usa Python"` is correctly detected even though it doesn't match English patterns.
  122. Each captured learning has a **confidence score** (0.60-0.95). The final score is the higher of regex and semantic confidence.
  123. ### Human Review
  124. When you run `/reflect`, Claude presents a summary table with options:
  125. - **Apply** - Accept the learning and add to CLAUDE.md
  126. - **Edit before applying** - Modify the learning text first
  127. - **Skip** - Don't apply this learning
  128. ### Multi-Target Sync
  129. Approved learnings are synced to:
  130. - `~/.claude/CLAUDE.md` (global - applies to all projects)
  131. - `./CLAUDE.md` (project-specific)
  132. - `./**/CLAUDE.md` (subdirectories - auto-discovered)
  133. - `./.claude/commands/*.md` (skill files - when correction relates to a skill)
  134. - `AGENTS.md` (if exists - works with Codex, Cursor, Aider, Jules, Zed, Factory)
  135. - 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.
  136. Run `/reflect --targets` to see which files will be updated.
  137. ### Skill Discovery
  138. Run `/reflect-skills` to discover repeating patterns in your sessions that could become reusable skills:
  139. ```
  140. /reflect-skills # Analyze current project (last 14 days)
  141. /reflect-skills --days 30 # Analyze last 30 days
  142. /reflect-skills --all-projects # Analyze all projects (slower)
  143. /reflect-skills --dry-run # Preview patterns without generating files
  144. ```
  145. **Features:**
  146. - **AI-powered detection** — uses reasoning, not regex, to find patterns
  147. - **Semantic similarity** — detects same intent across different phrasings
  148. - **Project-aware** — groups patterns by project, suggests correct location
  149. - **Smart assignment** — asks where each skill should go (project vs global)
  150. - **Generates skill files** — creates draft skills in `.claude/commands/`
  151. **How it works:**
  152. The skill discovers patterns by analyzing your session history semantically. Different phrasings of the same intent are recognized:
  153. ```
  154. Session 1: "review my productivity for today"
  155. Session 2: "how was my focus this afternoon?"
  156. Session 3: "check my ActivityWatch data"
  157. Session 4: "evaluate my work hours"
  158. ```
  159. 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."*
  160. **Example output:**
  161. ```
  162. ════════════════════════════════════════════════════════════
  163. SKILL CANDIDATES DISCOVERED
  164. ════════════════════════════════════════════════════════════
  165. Found 2 potential skills from analyzing 68 sessions:
  166. 1. /daily-review (High) — from my-productivity-tools
  167. → Review productivity using time tracking data
  168. Evidence: 15 similar requests
  169. Corrections learned: "use local timezone", "chat apps can be work"
  170. 2. /deploy-app (High) — from my-webapp
  171. → Deploy application with pre-flight checks
  172. Evidence: 10 similar requests
  173. Corrections learned: "always run tests first"
  174. ════════════════════════════════════════════════════════════
  175. Which skills should I generate?
  176. > [1] /daily-review, [2] /deploy-app
  177. Where should each skill be created?
  178. ┌──────────────────────┬─────────────────────────┐
  179. │ /daily-review │ my-productivity-tools │
  180. │ /deploy-app │ my-webapp │
  181. └──────────────────────┴─────────────────────────┘
  182. Skills created:
  183. ~/projects/my-productivity-tools/.claude/commands/daily-review.md
  184. ~/projects/my-webapp/.claude/commands/deploy-app.md
  185. ```
  186. **Generated skill file example:**
  187. ```markdown
  188. ---
  189. description: Deploy application with pre-flight checks
  190. allowed-tools: Bash, Read, Write
  191. ---
  192. ## Context
  193. Deployment scripts in ./scripts/deploy/
  194. ## Your Task
  195. Deploy the application to the specified environment.
  196. ### Steps
  197. 1. Run test suite
  198. 2. Build production assets
  199. 3. Deploy to target environment
  200. 4. Verify deployment health
  201. ### Guardrails
  202. - Always run tests before deploying
  203. - Never deploy to production on Fridays
  204. - Check for pending migrations
  205. ---
  206. *Generated by /reflect-skills from 10 session patterns*
  207. ```
  208. ### Skill Improvement Routing
  209. When you correct Claude while using a skill (e.g., `/deploy`), the correction can be routed back to the skill file itself:
  210. ```
  211. User: /deploy
  212. Claude: [deploys without running tests]
  213. User: "no, always run tests before deploying"
  214. → /reflect detects this relates to /deploy
  215. → Offers to add learning to .claude/commands/deploy.md
  216. → Skill file updated with new step
  217. ```
  218. This makes skills smarter over time, not just CLAUDE.md.
  219. ## Upgrading
  220. ### From v2.0.x or earlier
  221. If you see errors like "Duplicate hooks file detected" or "No such file or directory" after updating, you need to clear the plugin cache. This is due to known Claude Code caching issues:
  222. - [#14061](https://github.com/anthropics/claude-code/issues/14061) - `/plugin update` doesn't invalidate cache
  223. - [#15369](https://github.com/anthropics/claude-code/issues/15369) - Uninstall doesn't clear cached files
  224. ```bash
  225. # 1. Uninstall the plugin
  226. claude plugin uninstall claude-reflect@claude-reflect-marketplace
  227. # 2. Clear both caches (required!)
  228. rm -rf ~/.claude/plugins/marketplaces/claude-reflect-marketplace
  229. rm -rf ~/.claude/plugins/cache/claude-reflect-marketplace
  230. # 3. Exit Claude Code completely (restart terminal or close app)
  231. # 4. Reinstall
  232. claude plugin install claude-reflect@claude-reflect-marketplace
  233. ```
  234. ### Standard Update
  235. For normal updates (when no cache issues):
  236. ```bash
  237. # Use the /plugin menu in Claude Code
  238. /plugin
  239. # Select "Update now" for claude-reflect
  240. ```
  241. ## Uninstall
  242. ```bash
  243. claude plugin uninstall claude-reflect@claude-reflect-marketplace
  244. ```
  245. ## File Structure
  246. ```
  247. claude-reflect/
  248. ├── .claude-plugin/
  249. │ └── plugin.json # Plugin manifest (auto-registers hooks)
  250. ├── commands/
  251. │ ├── reflect.md # Main command
  252. │ ├── reflect-skills.md # Skill discovery
  253. │ ├── skip-reflect.md # Discard queue
  254. │ └── view-queue.md # View queue
  255. ├── hooks/
  256. │ └── hooks.json # Auto-configured when plugin installed
  257. ├── scripts/
  258. │ ├── lib/
  259. │ │ ├── reflect_utils.py # Shared utilities
  260. │ │ └── semantic_detector.py # AI-powered semantic analysis
  261. │ ├── capture_learning.py # Hook: detect corrections
  262. │ ├── check_learnings.py # Hook: pre-compact check
  263. │ ├── post_commit_reminder.py # Hook: post-commit reminder
  264. │ ├── compare_detection.py # Compare regex vs semantic detection
  265. │ ├── extract_session_learnings.py
  266. │ ├── extract_tool_errors.py
  267. │ ├── extract_tool_rejections.py
  268. │ └── legacy/ # Bash scripts (deprecated)
  269. ├── mod/ # reflect-mod: the same idea as a Claude Code mod (TypeScript)
  270. │ ├── .claude-plugin/plugin.json
  271. │ ├── hooks/register.tsx # Hooks module: prompt check, band, save
  272. │ └── hooks/reflect.test.tsx
  273. ├── tests/ # Test suite
  274. └── SKILL.md # Skill context for Claude
  275. ```
  276. ## Features
  277. ### Historical Scan
  278. First time using claude-reflect? Run:
  279. ```bash
  280. /reflect --scan-history
  281. ```
  282. This scans all your past sessions for corrections you made, so you don't lose learnings from before installation.
  283. ### Smart Filtering
  284. Claude filters out:
  285. - Questions (not corrections)
  286. - One-time task instructions
  287. - Context-specific requests
  288. - Vague/non-actionable feedback
  289. Only reusable learnings are kept.
  290. ### Duplicate Detection
  291. Before adding a learning, existing CLAUDE.md content is checked. If similar content exists, you can:
  292. - Merge with existing entry
  293. - Replace the old entry
  294. - Skip the duplicate
  295. ### Semantic Deduplication
  296. Over time, CLAUDE.md can accumulate similar entries. Run `/reflect --dedupe` to:
  297. - Find semantically similar entries (even with different wording)
  298. - Propose consolidated versions
  299. - Clean up redundant learnings
  300. Example:
  301. ```
  302. Before:
  303. - Use gpt-5.1 for complex tasks
  304. - Prefer gpt-5.1 for reasoning
  305. - gpt-5.1 is better for hard problems
  306. After:
  307. - Use gpt-5.1 for complex reasoning tasks
  308. ```
  309. ## Tips
  310. 1. **Use explicit markers** for important learnings:
  311. ```
  312. remember: always use venv for Python projects
  313. ```
  314. 2. **Run /reflect after git commits** - The hook reminds you, but make it a habit
  315. 3. **Historical scan on new machines** - When setting up a new dev environment:
  316. ```
  317. /reflect --scan-history --days 90
  318. ```
  319. 4. **Project vs Global** - Model names and general patterns go global; project-specific conventions stay in project CLAUDE.md
  320. 5. **Discover skills monthly** - Run `/reflect-skills --days 30` monthly to find automation opportunities you might have missed
  321. 6. **Skills get smarter** - When you correct Claude during a skill, that correction can be routed back to the skill file itself via `/reflect`
  322. 7. **Extend session retention** - Claude Code deletes local sessions after 30 days by default. Since claude-reflect relies on session history for `/reflect --scan-history` and `/reflect-skills`, extend this in `~/.claude/settings.json`:
  323. ```json
  324. { "cleanupPeriodDays": 99999 }
  325. ```
  326. ## Contributing
  327. Pull requests welcome! Please read the contributing guidelines first.
  328. ## License
  329. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.