Claude Doctor

claude-doctor

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         # check a specific session
claude-doctor      # 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