/ Directory / Playground / claude-reflect
← All servers ↗ GitHub
● Community BayramAnnakov ⚡ Instant

claude-reflect

by BayramAnnakov · BayramAnnakov/claude-reflect

Claude Code that quietly learns from how you correct it — capturing rules, preferences, and praise, then writing them into CLAUDE.md / AGENTS.md.

claude-reflect runs in the background of Claude Code sessions, watching for moments where you correct, praise, or restate preferences. It distills those into durable rules and updates CLAUDE.md and AGENTS.md so future sessions inherit them. Light-touch alternative to manually curating an instructions file.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

ready

Install

Author repository · Claude Skills documentation

Use Cases

Real-world ways to use claude-reflect

Evolve CLAUDE.md without manual curation

👤 Solo devs who hate maintaining doc files ⏱ ~5 min beginner

When to use: You want CLAUDE.md to keep up with your preferences without being a writing chore.

Flow
  1. Work normally
    Just code with Claude as usual. Correct it when wrong, praise it when right.✓ Copied
    → Skill silently captures — you don't notice it
  2. End-of-day review
    Use claude-reflect. Show me today's drafted rule additions. Approve or skip each.✓ Copied
    → 5–10 candidate rules with provenance (which session, what prompt)
  3. Commit the diff
    Apply approved rules and commit CLAUDE.md.✓ Copied
    → Clean git diff; rules now in effect

Outcome: CLAUDE.md that grows with you, no manual upkeep tax.

Pitfalls
  • Skill captures one-off context as durable rules — Always review the daily candidates; reject anything situational
Combine with: filesystem

Build team-wide AI conventions from collective corrections

👤 Tech leads standardizing AI workflows ⏱ ~60 min intermediate

When to use: Multiple devs all correct Claude on similar things; you want a shared rule set.

Flow
  1. Collect per-developer drafts
    Each dev runs claude-reflect daily and pushes their candidate rules to a shared review branch.✓ Copied
    → Branch with N drafts pending
  2. Merge sessions
    Use claude-reflect consolidate. Find rules captured by ≥2 people; promote those to AGENTS.md.✓ Copied
    → Common-ground rule set
  3. Roll out
    Merge to main. New AGENTS.md applies to everyone.✓ Copied
    → Team uses same baseline; per-dev local rules remain

Outcome: Bottom-up standardization without a process committee.

Pitfalls
  • Loud devs dominate; quiet ones' patterns missed — Ensure everyone runs the skill; weight by reflection events, not file edits
Combine with: github

Audit and prune stale rules in CLAUDE.md

👤 Long-time CLAUDE.md users ⏱ ~25 min intermediate

When to use: Your CLAUDE.md is now 600 lines and Claude's context is bloated.

Flow
  1. Score relevance
    Use claude-reflect. Score each rule by recency-of-last-application and current-codebase-fit.✓ Copied
    → Per-rule score
  2. Propose deletions
    Suggest 30 rules to remove (stale or obsolete).✓ Copied
    → Removal list with rationale
  3. Diff + commit
    Apply approved removals; commit with message 'reflect: prune stale rules'.✓ Copied
    → Slimmer CLAUDE.md

Outcome: CLAUDE.md that's actually read, not skimmed.

Pitfalls
  • Prune a rule that wasn't applied because Claude was respecting it — When in doubt, keep — but mark with 'last verified' so you re-check next quarter

Combinations

Pair with other MCPs for X10 leverage

claude-reflect-skill + pro-workflow-skill

pro-workflow for explicit capture, claude-reflect for passive — two-channel learning

Use pro-workflow when you say 'remember this'; let claude-reflect catch the rest in the background.✓ Copied
claude-reflect-skill + github

Reviewable rule changes via PR

Each Friday, claude-reflect opens a PR with proposed CLAUDE.md edits for human review.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
watch_session — Always-on background process 0
review_candidates since? Daily / weekly approve loop 0
consolidate scope? Periodic dedupe / contradiction resolution 0
score_rules — Pre-prune audit 0
apply_to_files approved_ids[], files[] Land approved candidates into CLAUDE.md / AGENTS.md 0

Cost & Limits

What this costs to run

API quota
None — local
Tokens per call
Background capture is free; review/consolidate uses local LLM if configured
Monetary
Free
Tip
Approve candidates conservatively — quality > quantity

Security

Permissions, secrets, blast radius

Minimum scopes: filesystem-write
Credential storage: Skill state in .claude/reflect/; commit to repo if you want shared
Data egress: None by default

Troubleshooting

Common errors and fixes

No candidates captured

Verify skill is invoked in CLAUDE.md preamble; check .claude/reflect/log for entries

Candidates are noise

Tighten the trigger sensitivity; only capture from explicit corrections, not generic chat

AGENTS.md drifts from CLAUDE.md

Run consolidate periodically; the tool is designed to keep them in sync but manual edits diverge them

Approval prompt overwhelming

Run review with --limit 5 daily; build a habit instead of doing 50 at once

Alternatives

claude-reflect vs others

AlternativeWhen to use it insteadTradeoff
pro-workflow-skillYou prefer explicit capture and worktree orchestrationMore manual; more powerful for parallel work
Manual CLAUDE.md curationYou're disciplined enough to write rules yourselfFrequently neglected; relies on willpower

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills

Continue exploring

Related tools and workflows

Choose another guide for your workflow, or explore a collection.

Browse all topic collections → · See 29 new official additions →