aradotso/skills/claude-doctor-session-diagnostics

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

# 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:

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)

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:

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

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

Or source it in a hook script:

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

JSON Output for Scripting

# 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:

{
  "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

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

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

Project-specific rule generation

# 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

# 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

#!/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:

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);

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

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/

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

# Ensure you're on a compatible Node version
node --version  # requires Node 18+
pnpm build      # rebuild after pulling updates