Skip to content
Datfx Labs Claude Guide

Doctor: Installation Health Check

/doctor runs a diagnostic sweep of your Claude Code installation. It checks everything from binary integrity and authentication to MCP server connectivity and configuration validity — and reports exactly what is healthy, what needs attention, and what is broken.

Run it after installing Claude Code, after changing configuration, after adding MCPs, or whenever something feels wrong and you are not sure where to start.

Syntax

Terminal window
# Run full diagnostic
/doctor


# Run from CLI (before starting a session)
claude doctor


# Specific check categories
/doctor --auth          # Authentication and account status only
/doctor --mcp           # MCP server connections only
/doctor --config        # Configuration file validity only
/doctor --install       # Binary and installation integrity only


# Verbose output — shows passing checks too, not just failures
/doctor --verbose


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

What /doctor Checks

Installation Integrity

  • Claude Code binary version and integrity hash
  • Node.js version compatibility
  • Required dependencies present and at correct versions
  • PATH configuration (is claude accessible from any terminal?)
  • File permissions on the Claude Code data directory

Authentication

  • Active session validity (is your auth token current?)
  • Account tier (free vs Pro — affects available features)
  • Token expiration date
  • API key configuration (if using API key auth instead of OAuth)

Configuration Validity

  • ~/.claude/config.json — valid JSON, no unknown keys, required fields present
  • Project-level CLAUDE.md — readable, not excessively large
  • Memory files — accessible and not corrupted
  • Custom slash command definitions — valid syntax

MCP Connections

For each configured MCP server:

  • Server process starts successfully
  • Protocol handshake completes
  • Tools list is accessible
  • Response time within acceptable range (>5s flagged as warning)

Environment

  • Internet connectivity (for API calls)
  • DNS resolution for api.anthropic.com
  • Proxy configuration (if applicable)
  • Environment variable conflicts (ANTHROPIC_API_KEY, CLAUDE_CONFIG_DIR, etc.)

Reading the Output

/doctor uses a three-level output system:

✓  PASS     Everything is working correctly
⚠  WARN     Works but something needs attention
✗  FAIL     Broken — requires action

Example output:

Claude Code Doctor v1.4.2
─────────────────────────


Installation
  ✓  Binary integrity        claude 1.4.2 (verified)
  ✓  Node.js compatibility   v20.11.0 (required: >=18)
  ✓  PATH configuration      /usr/local/bin/claude


Authentication
  ✓  Session valid           expires in 28 days
  ✓  Account tier            Pro
  ✗  API key                 ANTHROPIC_API_KEY set but invalid (401)


Configuration
  ✓  ~/.claude/config.json   valid
  ⚠  CLAUDE.md               18,432 tokens (recommended: <10,000)
  ✓  Memory files            3 files, all readable


MCP Connections
  ✓  filesystem              connected (tools: 8)
  ✓  github                  connected (tools: 23)
  ⚠  slack                   slow response (8.2s, threshold: 5s)
  ✗  postgres                failed to start (exit code 1)


Environment
  ✓  Internet connectivity   api.anthropic.com reachable
  ✓  DNS resolution          OK


Summary: 10 passed, 2 warnings, 2 failures
Run `/doctor --fix postgres` to attempt automatic repair.

Understanding Each Level

PASS — no action needed.

WARN — Claude Code works, but performance or reliability may be affected. Common warnings:

  • CLAUDE.md too large (slows context assembly)
  • MCP server response time high (network or process issue)
  • Auth token expiring soon (re-authenticate before it expires)
  • Config has deprecated keys (still works, but update before next major version)

FAIL — something is broken and needs fixing before that feature works. Common failures:

  • Invalid API key (set or correct ANTHROPIC_API_KEY)
  • MCP server process crash (check the MCP server’s own logs)
  • Config file invalid JSON (fix the syntax error)
  • Binary checksum mismatch (reinstall Claude Code)

Automatic Repair

For some failures, /doctor can attempt a fix automatically:

Terminal window
# Attempt automatic repair for a specific check
/doctor --fix <check-name>


# Examples
/doctor --fix postgres        # restart the postgres MCP server
/doctor --fix config          # reset config to defaults (with confirmation)
/doctor --fix auth            # open the re-authentication flow

Automatic repair always asks for confirmation before making changes. It never deletes data without explicit approval.

When to Run /doctor

After Initial Installation

Terminal window
claude doctor

Confirm the binary, auth, and environment are all working before your first session. Catches setup issues before they become debugging sessions.

After Configuration Changes

Any time you edit ~/.claude/config.json, add an MCP server, or change environment variables — run /doctor --config and /doctor --mcp to verify the changes took effect correctly.

After MCP Setup

MCP server configuration is the most common source of subtle failures. Run /doctor --mcp after adding any new server to confirm it connects and exposes the expected tools.

When Something Breaks

If Claude Code is behaving unexpectedly — tools not working, auth errors, slow responses — /doctor gives you a structured starting point instead of guessing.

Terminal window
/doctor --verbose    # see everything, including passing checks

The verbose output often reveals warnings that explain unexpected behavior even when there are no outright failures.

Gotchas

False Positives

Some checks produce false warnings in specific setups:

  • CLAUDE.md size warning — if your project intentionally has a large CLAUDE.md (detailed instructions, extensive context), the size warning is informational, not actionable.
  • MCP response time warning — remote MCP servers (not running locally) will naturally have higher latency. A 6-second response from a cloud MCP is not necessarily a problem.
  • API key “not set” warning — if you use OAuth authentication (the default for claude.ai accounts), the absence of ANTHROPIC_API_KEY is expected and correct.

What /doctor Does Not Check

  • The correctness of your task prompts or CLAUDE.md instructions (it checks format, not semantics)
  • Whether your MCP servers are doing what you intend (it checks connectivity, not behavior)
  • Git repository state
  • Project-specific dependencies (node_modules, virtual environments, etc.)
  • Third-party service credentials stored in MCP configs (it checks connectivity, not auth)