🩺 Claude Code Doctor

Diagnose, lint, and auto-fix your Claude Code setup. Now with AI-powered security scanning, dependency intelligence, and context optimization.

The missing health-check tool for Claude Code — built with custom ML engines, zero external dependencies.

Quick Start · ML Engines · Commands · Checks · CI/CD · Contributing

---

Why?

Claude Code is powerful, but misconfigured setups waste context window tokens, break MCP servers, leak secrets, and silently cause suboptimal results. Worse — your codebase could contain prompt injection attacks hiding in comments, configs, or encoded strings.

claude-code-doctor fixes all of this. One command gives you a health score, finds issues, scans for threats, and fixes problems. Built with 9 custom ML engines — all zero-dependency, from-scratch implementations.

npx claude-code-doctor

  ╔═══════════════════════════════════════════════╗
  ║   🩺  Claude Code Doctor                       ║
  ║   Diagnose · Scan · Optimize · Auto-Fix        ║
  ╚═══════════════════════════════════════════════╝

  Overall Health Score

  ███████████████████████████████░░░░ 89%
  Grade: A-

  22 passed · 4 warnings · 1 errors · 2 skipped
  💡 2 issue(s) can be auto-fixed with --fix

  ─────────────────────────────────────────────────

  🖥️  Environment  100%        ⚙️  Configuration  83%
  📦  Installation  50%         📝  CLAUDE.md Lint  88%
  🔌  MCP Servers  100%         🪝  Hooks  100%
  🔐  Permissions  100%         🧠  Context  100%
  🛡️  Security Audit  100%      🧠  AI Intelligence  92%

---

🧠 ML-Powered Engines

What makes claude-code-doctor unique: 9 custom ML engines built from scratch with zero external ML dependencies.

🛡️ Prompt Injection Scanner

The first tool in the Claude ecosystem to scan codebases for AI-targeted attacks.

claude-doctor scan-injections

  🛡️  Claude Code Doctor — Prompt Injection Scanner

  ✅ CLEAN — No prompt injection threats detected!
  87 files scanned.

Detects:

• 20+ direct injection patterns ("ignore previous instructions", system prompt overrides)
• Role-play/jailbreak attacks (DAN, "you are now", identity hijacking)
• Unicode manipulation (zero-width chars, bidi overrides — Trojan Source)
• Encoded payloads (Base64/hex-encoded hidden instructions)
• Social engineering (false authorization, urgency-based overrides)
• CLAUDE.md poisoning (malicious instructions targeting AI agents)
• Config poisoning (wildcard permissions, suspicious hooks)
• Comment-based injections (instructions hidden in code comments)

5 severity levels with confidence scoring. Supports TS/JS, Python, Go, Rust, Java, C/C++, Ruby, PHP, markdown, and config files.

📝 CLAUDE.md Auto-Generator

Auto-generate a high-quality CLAUDE.md from codebase analysis:

claude-doctor generate-claudemd

  ✔ Detected: TypeScript, JavaScript
  ✔ Frameworks: Next.js, Tailwind CSS, Prisma
  ✔ Architecture: full-stack
  ✔ 7 sections generated
  ✔ ~420 tokens

  ✨ CLAUDE.md generated!

Analyzes: tech stack (15+ languages, 40+ frameworks), architecture patterns (monorepo, MVC, API, CLI, library), coding conventions (indentation, quotes, naming), build/test/lint commands, and project structure.

🔗 Dependency Graph Intelligence

claude-doctor analyze

Builds a full import graph and identifies:

• Circular dependencies via Tarjan's Strongly Connected Components
• God files via PageRank-inspired importance scoring
• Orphan files (dead code wasting AI context)
• Blast radius prediction (which files break if you edit X)
• Optimal context loading order via topological sort
• Module clusters for project organization

💰 Session Cost Predictor

claude-doctor token-cost

  💰 Claude Code Doctor — Token Cost Analyzer

  Total Project: 45,203 tokens
  Context Usage: 23% of 200K window

  📊 Top 10 Costliest Files:

    high        5,102 tokens (11%)  src/core/engine.ts
    moderate    2,891 tokens (6%)   src/utils/parser.ts
    ...

  🎭 Scenario Estimates:

    Bug Fix             12,450 tokens  (6% window)
    Refactor            28,100 tokens  (14% window)
    New Feature         31,200 tokens  (16% window)
    Code Review         38,400 tokens  (19% window)

Features a BPE-approximation tokenizer (~90% accuracy vs Claude's actual tokenizer), per-file cost analysis, 5 scenario simulations, and optimization recommendations.

🚫 Smart .claudeignore Generator

claude-doctor generate-claudeignore

Automatically identifies files wasting AI context tokens: lock files, build artifacts, minified code, generated files (via entropy analysis), binary assets, test fixtures, and large data files. Generates a ready-to-use .claudeignore with per-pattern token savings estimates.

📐 Context Budget Optimizer

Uses Shannon entropy and TF-IDF information density scoring to analyze each section of your CLAUDE.md and recommend what to keep, condense, or remove:

claude-doctor analyze

🔬 Codebase AI-Readability Profiler

Scores every source file on how easy it is for AI coding agents to work with:

• Cyclomatic complexity (deep nesting confuses AI)
• Implicit state (global vars, singletons, side effects)
• Dynamic patterns (eval, metaprogramming, Proxy)
• Type ambiguity (any types, assertions, suppressions)
• Coupling (import density, circular dependency risk)

📝 CLAUDE.md Intelligence Analyzer

Parses your CLAUDE.md into discrete instructions and scores each for:

• Clarity (vague words, action verbs, specificity)
• Contradictions (pattern matching + semantic negation detection)
• Redundancies (TF-IDF cosine similarity)
• Readability (Flesch-Kincaid adapted for AI)
• Overall AI Comprehension Score

---

⚡ Quick Start

# Run instantly with npx (no install needed)
npx claude-code-doctor

# Or install globally
npm install -g claude-code-doctor

# Then run anywhere
claude-doctor
# or
ccd

📋 All Commands

Command	Description
claude-doctor	Full diagnostic health check
claude-doctor init	Generate optimal Claude Code setup for your project
claude-doctor analyze	Deep ML-powered analysis (all 7 engines)
claude-doctor scan-injections	Prompt injection security scan
claude-doctor generate-claudemd	Auto-generate CLAUDE.md from codebase
claude-doctor generate-claudeignore	Smart .claudeignore with token savings
claude-doctor token-cost	Token cost analysis and scenario prediction

Common Flags

# All commands support these
--path <path>          # Target project (defaults to cwd)
--format json          # Machine-readable JSON output
--dry-run              # Preview without writing files
--force                # Overwrite existing files

Diagnostic Flags

claude-doctor --fix                # Auto-fix all issues
claude-doctor --fix-interactive    # Step-by-step fix mode
claude-doctor --watch              # Watch mode (re-run on changes)
claude-doctor --badge              # Generate health badge SVG
claude-doctor --verbose            # Show detailed output
claude-doctor --only claudemd security  # Run specific checks only
claude-doctor --skip environment        # Skip specific checks
claude-doctor --format markdown > report.md  # Markdown report

✨ Smart Init

Auto-detect your project type and generate best-practice Claude Code configuration:

claude-doctor init

Supports: React, Next.js, Vue, Angular, Express, Python, Rust, Go, monorepos, and more.

🔍 What It Checks

Category	Checks	What It Validates
🖥️ Environment	5	Node.js, npm, git, OS, memory
📦 Installation	3	Claude Code binary, version, auth
⚙️ Configuration	4	.claude/ dir, settings, gitignore, commands
📝 CLAUDE.md Lint	4	Exists, size/tokens, sections, anti-patterns
🔌 MCP Servers	dynamic	.mcp.json validity, server accessibility, env vars
🪝 Hooks	dynamic	Event names, commands, scripts
🔐 Permissions	4	Write access, git init, node_modules
🧠 Context	3	Token overhead, large files, .claudeignore
🛡️ Security	12+	API keys, tokens, passwords, connection strings
🧠 AI Intelligence	10+	Injection scan, comprehension score, contradictions, graph health, token cost

45+ individual checks across 10 categories.

🛡️ Secret Detection

Deep scans for leaked secrets: AWS keys, Anthropic/OpenAI API keys, GitHub tokens, private keys, database URIs, JWT tokens, Slack/Stripe/SendGrid keys, and generic passwords.

🔧 Auto-Fix

# Quick fix (automatic)
claude-doctor --fix

# Interactive fix (step-by-step)
claude-doctor --fix-interactive

👀 Watch Mode

claude-doctor --watch

🏷️ Health Badge

claude-doctor --badge

Add to your README: ![Claude Code Health](.claude/health-badge.svg)

🔄 CI/CD Integration

GitHub Actions

name: Claude Code Health
on: [push, pull_request]

jobs:
  doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx claude-code-doctor --format json
      - run: npx claude-code-doctor scan-injections  # Security scan

Pre-commit Hook

# .husky/pre-commit
npx claude-code-doctor --only claudemd configuration security ai-insights --quiet

Exit Codes

Code	Meaning
0	All checks passed (or only warnings)
1	One or more errors found
2	Doctor itself failed to run

📦 Programmatic API

import { diagnose } from 'claude-code-doctor';
import { scanForInjections } from 'claude-code-doctor/ml';
import { generateClaudeMd } from 'claude-code-doctor/ml';
import { predictSessionCost } from 'claude-code-doctor/ml';
import { analyzeDependencyGraph } from 'claude-code-doctor/ml';
import { recommendClaudeignore } from 'claude-code-doctor/ml';

// Full diagnostic
const report = await diagnose({ path: './my-project' });
console.log(`Score: ${report.overallScore}% (${report.grade})`);

// Prompt injection scan
const threats = await scanForInjections('./my-project');
console.log(`Risk: ${threats.riskLevel} (${threats.findings.length} threats)`);

// Auto-generate CLAUDE.md
const claudemd = await generateClaudeMd('./my-project');
console.log(claudemd.content);

// Token cost analysis
const cost = await predictSessionCost('./my-project');
console.log(`${cost.totalProjectTokens} tokens (${cost.contextWindow.utilizationPercent}% of context)`);

// Dependency graph
const graph = await analyzeDependencyGraph('./my-project');
console.log(`${graph.circularDependencies.length} circular deps found`);

🏗️ Architecture

src/
├── ml/                           # 9 Custom ML Engines (zero dependencies)
│   ├── prompt-injection-scanner.ts   # 🛡️ Security scan (20+ patterns)
│   ├── dependency-graph.ts           # 🔗 Graph intelligence (Tarjan, PageRank)
│   ├── claudemd-generator.ts         # 📝 Auto-generate CLAUDE.md
│   ├── claudeignore-recommender.ts   # 🚫 Smart .claudeignore
│   ├── session-cost-predictor.ts     # 💰 Token cost & BPE tokenizer
│   ├── instruction-analyzer.ts       # 📊 CLAUDE.md intelligence
│   ├── codebase-profiler.ts          # 🔬 AI-readability scoring
│   ├── context-optimizer.ts          # 📐 Context budget optimizer
│   └── text-analyzer.ts             # 🔠 NLP primitives (TF-IDF, cosine sim)
├── checks/                       # 10 Diagnostic Check Categories
├── commands/                     # CLI Commands (init, analyze, watch)
├── reporters/                    # Output Formatters (terminal, JSON, markdown, badge)
├── fixes/                        # Auto-Fix Engine
├── utils/                        # Helpers
├── doctor.ts                     # Core Orchestrator
└── types.ts                      # Type Definitions

🤝 Contributing

We welcome new checks and ML engines! See CONTRIBUTING.md.

📄 License

MIT — see LICENSE.

---

Built by Mishit18 · ⭐ Star us if this helped!

9 ML engines · 45+ checks · 10 categories · Zero external ML dependencies