Claude watches how you work across every session, deletes the rules that don't do anything, drafts the ones you keep correcting manually, and quietly keeps your CLAUDE.md sharp. Without you lifting a finger.
Every correction adds a rule. Your file grows to 300+ lines. Nobody maintains it.
Research (AGENTIF, NeurIPS 2025) shows <30% instruction compliance as rules multiply.
Advisory rules fail invisibly. One Max user measured ~100% violation vs 0% with hooks.
CLAUDE.md accretes monotonically. The problem compounds until Claude feels broken.
Scans 60+ sessions, counts rule triggers, flags rules that never fired. LLM verification filters out silent-but-working advisory rules.
Detects repeated corrections (same complaint 3+ times) and drafts a rule in your own voice.
Compresses sections, replays past sessions against old and new, scores behavioral similarity. Keeps compression only if behavior is preserved.
Install once. Runs in the background. Claude surfaces insights mid-chat. You never open a terminal.
One command in Claude Code. The skill + hooks auto-register. Zero config files touched.
Do your work. The coach watches every session end, analyzes correction patterns, updates a local cache.
Claude surfaces suggestions mid-chat when it spots patterns. Weekly, a nudge shows pending insights. You approve what you want.
Deterministic audit. Dead rules, sprawl, cross-file duplicates, scope-move suggestions.
Interactive review: contradictions, correction-mined rule drafts, semantic-verified dead rules.
Compress sections with optional replay verification. Progressive mode iterates until behavior diverges.
Trends across scans over time. Watch rule effectiveness evolve.
One-line nudge surfaced by the SessionStart hook. Non-intrusive.
Ambient behavior: Claude pauses mid-chat when 3+ repeated corrections detected and offers a rule.
$ claude-md-coach scan Scanning workspace… Found 2 CLAUDE.md file(s). Parsing… Reading session history… Analyzed 57 sessions. claude-md-coach · scan report Found 2 CLAUDE.md files, analyzed 57 sessions. 1. ~/your-project/CLAUDE.md project (root), 84 lines, 45 rules, 19 sessions in scope ● HEALTHY Size is within the recommended range. ⚠ 3 dead rules · verified by LLM as never applied R3 Demand elegance on non-trivial changes R8 Never give up after 2 tries R14 Brainstorming skill on new project ⚠ 2 contradictions detected R4 + R11: concise vs always explain reasoning → Default to concise. Explain only when architectural decisions or on request. 💡 3 missing rules mined from your corrections "You corrected em-dash usage 7×. Never use em-dashes in output." "You corrected 'premature abstraction' 4×. Wait until 3rd use." "You corrected vague planning 5×. Always name files + line numbers." 2. ~/your-project/api/CLAUDE.md project (api), 42 lines, 18 rules ● HEALTHY All rules have strong trigger signal. Run claude-md-coach fix to review and apply.
No. It uses your existing Claude Code subscription. LLM features invoke `claude -p` subprocesses. Your auth, your rate limits.
No. Everything runs locally on your machine. Session JSONL files stay in `~/.claude/projects/`. No server, no telemetry, no analytics.
Any Claude Code surface: terminal CLI, VS Code extension, JetBrains, desktop app, web. The plugin format works identically everywhere.
The tool gracefully handles empty data. It skips analysis where there's nothing to learn from and waits for more sessions to accumulate.
Tiny. `scan` uses zero Claude calls. `fix` typically burns 3 to 10 Haiku calls per file. `distill` with replay verification is the most expensive (~9 calls per section). All cached aggressively.
Yes. Every edit saves a timestamped backup next to the file in `.claude-md-coach-history/`. One command restores any version.
No. Anthropic's plugin grades your file against generic criteria. This one learns from your specific session history. They're complementary. Anthropic's is a spell-check, this is a coach.
Not yet. Shared rule registries, PR checks, per-contributor attribution are on the V4 roadmap. Today it's single-user.
Install once. Forget it exists. Your rules stay sharp, every week, without you lifting a finger.