claude-doctor-session-diagnostics

What this skill does

```markdown
---
name: claude-doctor-session-diagnostics
description: Diagnose Claude Code sessions for behavioral anti-patterns and auto-generate CLAUDE.md rules from transcript history
triggers:
  - analyze my claude sessions
  - diagnose claude code behavior
  - generate CLAUDE.md rules from history
  - check for edit thrashing in my sessions
  - why does claude keep making the same mistakes
  - audit my claude transcript history
  - find anti-patterns in my AI coding sessions
  - create rules from my claude session history
---

# claude-doctor Session Diagnostics

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

`claude-doctor` reads your `~/.claude/` JSONL transcripts, scores them for structural and behavioral anti-patterns, and generates ready-to-paste rules for `CLAUDE.md` or `AGENTS.md`.

## Install

```bash
# Global install
npm i -g claude-doctor

# Or run without installing
npx claude-doctor
```

## Key Commands

```bash
# Analyze all sessions (default)
claude-doctor

# Analyze a specific session by ID
claude-doctor <session-id>

# Analyze a specific JSONL file directly
claude-doctor path/to/session.jsonl

# Filter to a named project
claude-doctor -p myproject

# Generate rules for CLAUDE.md / AGENTS.md
claude-doctor --rules

# Save model and guidance to .claude-doctor/
claude-doctor --save

# Output results as JSON (for piping/scripting)
claude-doctor --json

# Combine flags
claude-doctor -p myproject --rules --json
```

## What It Detects

### Structural Signals

| Signal | Meaning |
|---|---|
| `edit-thrashing` | Same file edited 5+ times in one session |
| `error-loop` | 3+ consecutive tool failures without approach change |
| `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 Signals

| Signal | Meaning |
|---|---|
| `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 scoring uses AFINN-165 sentiment with custom agent tokens (`undo`, `revert`, `wrong`, `broken`, etc.).

## Generating Rules (`--rules`)

The most actionable feature — scans your full history and outputs rules tuned to your actual patterns:

```bash
claude-doctor --rules
```

Example output:

```
## 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.
```

Paste the output directly into your project's `CLAUDE.md` or `AGENTS.md`.

## Saving a Persistent Model (`--save`)

```bash
claude-doctor --save
```

Creates `.claude-doctor/` in the current directory with:

- `model.json` — signal baselines and project profiles
- `guidance.md` — agent-readable rules suitable for CLAUDE.md inclusion or hook injection

You can reference `guidance.md` from your `CLAUDE.md`:

```markdown
<!-- CLAUDE.md -->
# Project Rules

<!-- Auto-generated diagnostics -->
{{include .claude-doctor/guidance.md}}
```

Or source it in a hook script:

```bash
#!/bin/bash
# .claude/hooks/pre-session.sh
cat .claude-doctor/guidance.md
```

## JSON Output for Scripting

```bash
# Pipe into jq for signal filtering
claude-doctor --json | jq '.signals[] | select(.severity == "high")'

# Save report
claude-doctor --json > session-report.json

# Check a specific project's signals
claude-doctor -p myproject --json | jq '.signals[].name'
```

Example JSON shape:

```json
{
  "sessions": 838,
  "project": "myproject",
  "signals": [
    {
      "name": "edit-thrashing",
      "severity": "high",
      "count": 14,
      "description": "Same file edited 5+ times in one session"
    },
    {
      "name": "correction-heavy",
      "severity": "medium",
      "count": 23,
      "description": "20%+ of user messages are corrections"
    }
  ],
  "sentiment": {
    "score": -0.42,
    "label": "negative"
  }
}
```

## Common Workflows

### Weekly session audit

```bash
# Full audit with saved model
claude-doctor --save

# Review guidance
cat .claude-doctor/guidance.md
```

### Project-specific rule generation

```bash
# Generate rules scoped to one project
claude-doctor -p myproject --rules > /tmp/new-rules.md

# Append to existing CLAUDE.md
echo "" >> CLAUDE.md
cat /tmp/new-rules.md >> CLAUDE.md
```

### Diagnose a single bad session

```bash
# Find recent session IDs in ~/.claude/
ls ~/.claude/

# Analyze one session
claude-doctor abc123-session-id

# Or point at the file directly
claude-doctor ~/.claude/projects/myproject/abc123.jsonl
```

### CI integration — fail on high-severity signals

```bash
#!/bin/bash
# scripts/check-sessions.sh
SIGNALS=$(claude-doctor --json | jq '[.signals[] | select(.severity == "high")] | length')
if [ "$SIGNALS" -gt 0 ]; then
  echo "High-severity session signals detected:"
  claude-doctor --json | jq '.signals[] | select(.severity == "high")'
  exit 1
fi
```

## TypeScript API (programmatic use)

The package exposes internal modules if you want to integrate diagnostics into your own tooling:

```typescript
import { analyzeSessions, generateRules } from 'claude-doctor';

// Analyze all sessions
const report = await analyzeSessions({
  project: 'myproject',   // optional filter
  jsonl: undefined,       // optional path to specific file
});

console.log(report.signals);
console.log(report.sentiment);

// Generate CLAUDE.md rules from report
const rules = generateRules(report);
console.log(rules);
```

```typescript
import { analyzeFile } from 'claude-doctor';

// Analyze a single JSONL transcript
const result = await analyzeFile('~/.claude/projects/myproject/session.jsonl');

for (const signal of result.signals) {
  console.log(`${signal.name} (${signal.severity}): ${signal.description}`);
}
```

## Development

```bash
git clone https://github.com/millionco/claude-doctor
cd claude-doctor
pnpm install
pnpm build
pnpm test

# Run locally against your own sessions
node dist/cli.js --rules
```

## Troubleshooting

**No sessions found**
- Transcripts must exist at `~/.claude/`. Run at least one Claude Code session first.
- Check `ls ~/.claude/projects/` to confirm transcript directories exist.

**`--rules` produces generic output**
- More sessions = better rules. Aim for 50+ sessions before generating rules.
- Use `-p myproject` to scope rules to a specific project's patterns.

**Permission errors reading `~/.claude/`**
```bash
chmod -R u+r ~/.claude/
```

**JSON output is empty signals array**
- Your sessions may be too short (fewer than 3 turns). High-abandonment sessions still count in the `high-abandonment-rate` signal.

**TypeScript errors when importing**
```bash
# Ensure you're on a compatible Node version
node --version  # requires Node 18+
pnpm build      # rebuild after pulling updates
```
```