claude-doctor

April 15, 2026 · View on GitHub

Analyzes your ~/.claude/ transcripts for behavioral anti-patterns and generates rules for CLAUDE.md / AGENTS.md from your history.

https://github.com/user-attachments/assets/cdeb6b05-f3e6-441b-8bc2-9fcce623d9fd

Install

npm i -g claude-doctor

Or run directly:

npx claude-doctor

Usage

claude-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

Signals

Structural

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

Behavioral

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

Lexical

AFINN-165 sentiment scoring with custom agent tokens (undo, revert, wrong, broken, etc).

`--rules`

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.

`--save`

Writes a model to .claude-doctor/:

model.json signal baselines and project profiles
guidance.md agent-readable rules for hooks or CLAUDE.md inclusion

Development

pnpm install
pnpm build
pnpm test

License

MIT