Analyzes your ~/.claude/ transcripts for behavioral anti-patterns and generates rules for CLAUDE.md / AGENTS.md from your history.
claude-doctor.mp4
npm i -g claude-doctorOr run directly:
npx claude-doctorclaude-doctor # analyze all sessions (default)
claude-doctor <session-id> # check a specific session
claude-doctor <path/to.jsonl> # check a specific session file
claude-doctor -p myproject # filter to a project
claude-doctor --rules # generate rules for CLAUDE.md / AGENTS.md
claude-doctor --save # save model to .claude-doctor/
claude-doctor --json # output as JSON| Signal | Detection |
|---|---|
edit-thrashing |
Same file edited 5+ times in one session |
error-loop |
3+ consecutive tool failures without changing approach |
excessive-exploration |
Read-to-edit ratio above 10:1 |
restart-cluster |
Multiple sessions started within 30 minutes |
high-abandonment-rate |
Most sessions have fewer than 3 user messages |
| Signal | Detection |
|---|---|
correction-heavy |
20%+ of user messages start with "no", "wrong", "wait" |
keep-going-loop |
User repeatedly says "keep going" / "continue" |
repeated-instructions |
Same instruction rephrased within 5 turns (Jaccard >60%) |
negative-drift |
Messages get shorter and more corrective over time |
rapid-corrections |
User responds within 10s of agent output |
high-turn-ratio |
User sends 1.5x+ messages per agent response |
AFINN-165 sentiment scoring with custom agent tokens (undo, revert, wrong, broken, etc).
Generates ready-to-paste rules from your session history:
## Rules (auto-generated by claude-doctor)
Based on analysis of 838 sessions. Paste into your CLAUDE.md or AGENTS.md.
- Read the full file before editing. Plan all changes, then make ONE complete edit.
- After 2 consecutive tool failures, stop and change your approach entirely.
- When the user corrects you, stop and re-read their message.
- Complete the FULL task before stopping.
- Every few turns, re-read the original request to make sure you haven't drifted.
Writes a model to .claude-doctor/:
model.jsonsignal baselines and project profilesguidance.mdagent-readable rules for hooks or CLAUDE.md inclusion
pnpm install
pnpm build
pnpm testMIT
