Claude Code /doctor Explained: One-Click Diagnostics for Your Dev Environment

Why You Need /doctor

When developing with Claude Code, you’ll inevitably run into puzzling issues:

• Commands suddenly stop responding — is the API down or are you out of tokens?
• MCP server won’t connect — is the config wrong or is the port taken?
• Search stopped working — is ripgrep even installed?
• After upgrading from npm to native install, will leftover versions cause conflicts?

Troubleshooting these one by one is tedious. You have to check environment variables, inspect config files, test network connections, verify permissions — it feels like detective work every time.

You need a one-click diagnostic tool.

That’s /doctor.

What Is /doctor

/doctor is Claude Code’s environment diagnostic command. It automatically checks your installation status, configuration, connections, permissions, and more, then tells you what’s fine, what’s broken, and how to fix it.

In interactive mode, type:

/doctor

Or run it directly from your terminal:

claude doctor

Within seconds, you’ll see a complete diagnostic report with each check marked by status: green for passing, yellow for warnings, red for errors.

What /doctor Checks

1. Installation Diagnostics

This is the most fundamental set of checks. /doctor detects:

Installation type: Are you using an npm global install, local install, or native install? Different methods affect upgrade paths and permission management.

Installation type: npm-global
Installation path: /usr/local/lib/node_modules/@anthropic-ai/claude-code
Version: 2.1.88

Multiple installations: If you have multiple installations simultaneously (e.g., npm global, ~/.claude/local, and Homebrew), /doctor lists them all and warns you.

This is a very common issue — forgetting to uninstall the old version after upgrading, leading to version conflicts or running the wrong binary.

Auto-update status: Are auto-updates enabled? For npm global installs, do you have permission to update (some systems require sudo)?

Configuration consistency: Does your actual installation method match what’s recorded in config? For example, if you’ve switched to native installation but config still says npm-local, /doctor will remind you to correct it.

2. Ripgrep Status

Claude Code’s search feature (Grep tool) relies on ripgrep. /doctor checks its status:

Ripgrep: working (mode: builtin)

Three modes:

• system: Using system-installed ripgrep
• builtin: Using Claude Code’s bundled ripgrep (npm installations)
• embedded: Ripgrep compiled into the binary (native installations)

If ripgrep is unavailable, search will completely fail. /doctor tells you the exact reason and how to fix it.

3. Context Usage Warnings

These checks help you discover unexpected context consumption:

CLAUDE.md file size: If your CLAUDE.md exceeds 40,000 characters, /doctor warns you. Oversized CLAUDE.md files load on every conversation, wasting context window space.

Warning: Large CLAUDE.md files detected
  └ .claude/memory.md - 52,341 characters
  └ CLAUDE.md - 41,209 characters

Too many Agent descriptions: Custom Agent descriptions consume system prompt space. If your custom Agent descriptions total over 15,000 tokens, /doctor lists the heaviest ones and suggests trimming.

Too many MCP tools: The more tools MCP servers register, the longer the system prompt. The threshold is 25,000 tokens. If you’ve connected several MCP servers each registering dozens of tools, context gets eaten up by tool descriptions.

Permission rule conflicts: Checks for shadowed permission rules. For example, if you set an allow rule for npm test but a broader deny rule above it covers it, your allow rule will never take effect.

4. Sandbox Status

Claude Code uses a sandbox to isolate tool execution. /doctor checks:

• Whether the current platform supports sandboxing
• Whether sandbox is enabled
• Whether sandbox dependencies are ready

If the sandbox is unavailable but you think it’s protecting you, that’s a security risk. /doctor clearly tells you the actual status.

5. MCP Server Configuration

If you’ve configured MCP servers, /doctor validates:

• Whether the config file’s JSON format is correct
• Whether server connections are healthy
• Whether there are parsing errors or startup failures

MCP config errors are common — a missing comma, wrong path, nonexistent command — /doctor catches them all.

6. Keybinding Configuration

Checks whether ~/.claude/keybindings.json is valid:

• Format correctness
• Conflicting key bindings
• References to nonexistent actions

7. Environment Variable Validation

/doctor checks several key environment variables for reasonable values:

• BASH_MAX_OUTPUT_LENGTH: Output limit for the Bash tool. Setting it too large may cause context overflow
• TASK_MAX_OUTPUT_LENGTH: Output limit for background tasks
• CLAUDE_CODE_MAX_OUTPUT_TOKENS: Maximum output tokens for the model. Warns if it exceeds the model’s supported limit

8. Update Information

/doctor also asynchronously checks for new versions, showing your current version and the latest available, along with the update channel (stable, latest, etc.).

When to Use /doctor

After setting up your environment: Run it after a fresh install or upgrade to confirm everything works.

When mysterious issues appear: Search isn’t working, MCP won’t connect, responses are slow — run /doctor first to check for red errors.

After switching installation methods: Upgrading from npm to native install (or vice versa), run it to check for leftover conflicts.

When helping teammates troubleshoot: Have them run /doctor and send the output. It’s much faster than asking them to describe the problem.

A Real Troubleshooting Scenario

After upgrading to a native installation, you notice Claude Code starts slower and some searches return empty results.

Run /doctor and find:

Warning: Multiple installations detected:
  └ native: ~/.local/bin/claude
  └ npm-global: /usr/local/lib/node_modules/@anthropic-ai/claude-code

Warning: Configuration mismatch:
  └ Running: native
  └ Configured: npm-local
  └ Fix: Update your install method in settings

Ripgrep: not working (mode: system)
  └ System ripgrep not found at expected path

The issues are clear:

1. Old npm global install wasn’t removed — npm uninstall -g @anthropic-ai/claude-code
2. Config file still has the old install method — update settings
3. System ripgrep is missing — reinstall or let Claude Code use its built-in version

Three problems, three fixes, no guessing.

Usage Notes

Trust Your Directory

/doctor skips workspace trust dialogs and spawns MCP servers for health checks. So only run claude doctor in directories you trust. Running it in an unfamiliar project directory may trigger untrusted MCP configurations.

Async Loading

Some checks complete asynchronously. For example, MCP tool token counts may need to wait for MCP connections to be established, and version checks require network requests. Initial results may be incomplete — wait a few seconds for data to fill in.

Final Thoughts

/doctor is one of the most overlooked commands in Claude Code.

When issues arise, most people’s first instinct is to search online, ask AI, or dig through documentation. But for most environment problems, /doctor gives you the answer in seconds — not just telling you “what’s wrong” but also “how to fix it.”

Make it a habit: when something seems off, run /doctor first.