Claude Code /doctor: How to Diagnose and Fix Setup Problems

Quick answer: Type /doctor inside an active Claude Code session to run a setup checkup that diagnoses installation and configuration problems. You can also use its /checkup alias. If Claude Code cannot start a session at all, run claude doctor from your regular terminal instead; the terminal command provides read-only installation and settings diagnostics.

The important distinction is simple: /doctor is the in-session checkup, while claude doctor is the terminal diagnostic command. The in-session command can send its diagnostic report to Claude for fixes, while the terminal version is designed to work without starting a Claude Code session.

What Is Claude Code /doctor?

/doctor is Claude Code's built-in diagnostic command for finding installation and configuration problems.

It is particularly useful when you are seeing symptoms such as:

• Claude Code behaving differently after an update
• MCP servers failing to load
• configuration files producing errors
• hooks not working as expected
• search or file discovery problems
• excessive context usage
• installation or PATH problems
• plugins, skills, or other extensions not loading correctly

Anthropic's current troubleshooting documentation recommends /doctor when you're unsure which configuration or installation issue is responsible. If Claude itself will not start, the same documentation points you to claude doctor from the shell.

In other words, instead of manually checking several configuration files and environment settings one by one, /doctor gives you a centralized place to start.

What Changed in /doctor?

One important detail when reading older Claude Code tutorials is that /doctor has changed over time.

In Claude Code v2.1.205, /doctor was expanded into a full setup checkup that can diagnose and fix issues, and /checkup became its alias.

That means older articles describing /doctor as strictly read-only may be outdated.

A later release, v2.1.206, added a /doctor check that can propose trimming checked-in CLAUDE.md files by removing information Claude can derive from the codebase.

So if your /doctor screen looks different from a screenshot published several months ago, your Claude Code version may be the reason.

The simple timeline

• Older versions: /doctor primarily reported diagnostic findings.
• v2.1.205: /doctor became a broader setup checkup that can diagnose and fix issues; /checkup was added as an alias.
• v2.1.206: checked-in CLAUDE.md trimming became another diagnostic area.

Claude Code releases frequently, so always verify version-specific behavior against the current documentation before treating an old screenshot or tutorial as authoritative.

Two Ways to Run Claude Code Doctor

There are two different entry points:

Option 1: Run /doctor inside Claude Code

Start a Claude Code session and enter:

/doctor

You can also use:

/checkup

The current commands reference describes /doctor as the command for diagnosing and verifying Claude Code installation and settings. Its diagnostic interface can show status icons, and the F action can send the report to Claude to fix reported issues.

Option 2: Run claude doctor from your terminal

If Claude Code won't start a session, open your normal terminal and run:

claude doctor

This command is specifically useful when the interactive session cannot launch. Current CLI documentation describes it as a read-only diagnostic command that checks installation/settings information without starting a session.

This makes it particularly useful for problems such as:

• command not found
• broken installation
• PATH problems
• invalid settings
• update-related installation issues

What Does /doctor Check?

The exact checks can vary by Claude Code version, platform, and installation method, but current documentation and recent troubleshooting material point to several important diagnostic areas.

1. Installation Health

Installation problems are one of the first things worth checking.

Claude Code can be installed through different methods, and leftover or conflicting installations can make troubleshooting confusing. For example, switching installation methods can leave multiple Claude binaries or paths on the machine.

Check your current version with:

claude --version

If Claude Code reports an installation problem, check which executable your shell is actually using.

On Unix-like systems:

which claude

On Windows:

where.exe claude

This can help identify situations where your shell is launching a different installation than the one you expected.

2. Settings and Configuration Files

Configuration errors can prevent features from working even when Claude Code itself launches normally.

The configuration debugging documentation specifically recommends /doctor for surfacing invalid configuration keys and schema errors.

If settings appear to be ignored, also run:

/status

/status shows which settings sources are active, including whether managed settings are in effect. This is useful because settings can come from different scopes, and a higher-priority setting may override the value you changed.

3. MCP Server Configuration

MCP problems are another major reason to investigate your Claude Code configuration.

/doctor can identify configuration problems, but /mcp is the more focused command for inspecting MCP server status.

Run:

/mcp

It can show configured servers, connection status, and whether a project-scoped server has been approved.

If an MCP server is defined correctly but still fails, check:

• whether the project-scoped server was approved
• whether its command exists
• whether relative paths resolve from the directory where Claude Code was launched
• whether the server actually returns tools

For a connected server showing zero tools, the official configuration guide recommends reconnecting it from /mcp; if that does not help, use:

claude --debug mcp

to inspect server-side diagnostic output.

4. Hooks

Hooks can introduce configuration and runtime problems of their own.

If a hook isn't appearing, first check:

/hooks

If it appears but does not execute, the matcher configuration may be the problem.

For deeper investigation, Claude Code's debugging documentation recommends starting with hook-specific debug logging:

claude --debug hooks

This can show which events and matchers were evaluated and what the hook returned.

/doctor is therefore useful for detecting configuration-level problems, while /hooks and debug logging are better for investigating the hook itself.

5. Context Usage

Claude Code problems are not always caused by installation errors.

Large memory files, MCP tool descriptions, skills, and other configuration can consume significant context.

Use:

/context

to see what is occupying the current context window.

The configuration documentation breaks this down into categories such as:

• system prompt
• memory files
• skills
• MCP tools
• conversation messages

This is particularly important in large projects where many MCP servers, plugins, skills, or long CLAUDE.md files are loaded.

/doctor can flag certain context-related configuration problems, while /context gives you a more direct view of what is consuming the current window.

6. CLAUDE.md Files

CLAUDE.md files provide project instructions and memory, but overly large or repetitive files can become a problem.

Recent versions of Claude Code expanded /doctor to identify opportunities to reduce unnecessary CLAUDE.md content. In v2.1.206, the command gained a check that proposes trimming checked-in CLAUDE.md files by removing information that Claude can derive from the codebase.

The important principle is not to delete useful project knowledge simply to make the file smaller.

Project-specific conventions, important gotchas, rationale, and rules that Claude cannot reliably infer should remain.

7. Search and Ripgrep

If Claude Code's search, @file mentions, custom agents, or custom skills aren't finding files correctly, ripgrep is worth checking.

Claude Code's troubleshooting documentation explains that search can be affected when the bundled ripgrep binary cannot run correctly. In that situation, you can install system ripgrep and configure Claude Code to use it instead.

For example, on macOS:

brew install ripgrep

On Windows:

winget install BurntSushi.ripgrep.MSVC

On Ubuntu/Debian:

sudo apt install ripgrep

Then configure:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

After changing this setting, verify the search configuration with:

claude doctor

The diagnostic should show the system ripgrep path rather than the bundled version.

8. WSL Environment

Windows users running Claude Code through WSL have another layer to consider.

WSL filesystem performance can affect search behavior, particularly when a project is stored on the Windows-mounted filesystem instead of the Linux filesystem.

For example:

/mnt/c/

can behave differently from:

/home/

The official troubleshooting guide notes that cross-filesystem access in WSL can lead to slower or incomplete search results even though claude doctor may still report Search as OK.

If search feels unusually slow or incomplete, check where your project lives before assuming Claude Code itself is broken.

Step-by-Step: How to Run /doctor

Step 1: Start Claude Code

Open your project directory and start a Claude Code session.

If Claude Code starts normally, use the in-session command.

If it doesn't start, skip to the terminal method.

Step 2: Run the checkup

Inside Claude Code:

/doctor

Or:

/checkup

From your normal terminal:

claude doctor

Step 3: Let the diagnostics finish

Some information can depend on configuration or external connections, so don't immediately assume the first screen contains every possible finding.

Pay attention to warnings and errors rather than trying to match your output against an old screenshot from another Claude Code version.

Step 4: Review the findings

Look for the actual category of the problem:

• installation
• settings
• MCP
• hooks
• search
• context
• permissions
• version/update information

Not every warning means Claude Code is unusable. Some findings are optimization recommendations rather than blocking errors.

Step 5: Apply fixes when available

In the /doctor diagnostics screen, the F action sends the diagnostic report to Claude so it can work on the reported issues. The current keybinding documentation says this action is only active when issues are found.

Review what Claude proposes before accepting changes, especially when configuration or project files are involved.

Step 6: Re-run the diagnostics

After making changes, run:

/doctor

again.

This confirms whether the original problem disappeared and can reveal another issue that was hidden behind the first one.

What If /doctor Can't Fix the Problem?

/doctor is a diagnostic starting point, not a guarantee that every failure can be repaired automatically.

For example, it may identify a malformed configuration or unhealthy MCP server without being able to repair an external service that is offline.

When that happens, move from diagnosis to targeted investigation.

For MCP problems

Run:

/mcp

Then inspect the affected server.

For deeper MCP debugging:

claude --debug mcp

For hooks

Use:

/hooks

and, when necessary:

claude --debug hooks

For configuration

Use:

/context

to see what loaded into the current session, and:

/status

to see active settings sources.

For plugin-related problems

Try starting Claude Code with:

claude --safe-mode

The official troubleshooting guide says safe mode disables customizations for the session, making it useful for determining whether a plugin, MCP server, or hook is responsible for the problem.

If the problem disappears in safe mode, investigate your customizations instead of immediately reinstalling Claude Code.

Check Claude's Status Before Reinstalling

Not every Claude Code error is caused by your computer.

If requests suddenly start failing, authentication becomes unreliable, or multiple users are reporting the same behavior, check Anthropic's service status before changing your local configuration.

This prevents the classic troubleshooting loop:

Error
↓
Reinstall Claude
↓
Change configuration
↓
Delete files
↓
Restart everything
↓
Problem still exists

If the service itself is experiencing an incident, local configuration changes may accomplish nothing.

A better troubleshooting order is:

Check service status
        ↓
Run /doctor
        ↓
Check /mcp, /hooks, /context or /status
        ↓
Use targeted debug logging
        ↓
Escalate if still reproducible

Recent Claude Code troubleshooting guidance similarly recommends checking platform health, running /doctor, collecting evidence, and escalating persistent problems rather than repeatedly guessing at local fixes.

/doctor vs /debug vs /status vs /mcp vs /feedback

These commands are related, but they are not interchangeable.

Anthropic's current command reference describes /doctor as the setup diagnostic, /debug as the runtime diagnostic, and /feedback as the bug-reporting path with session context attached.

For configuration-specific investigation, Anthropic also recommends /mcp, /hooks, /context, and /status depending on which part of the environment you need to inspect.

A simple rule

Something is wrong but you don't know why?

Run:

/doctor

Claude won't start?

Run:

claude doctor

MCP is broken?

Run:

/mcp

A hook isn't working?

Run:

/hooks

Context seems unusually large?

Run:

/context

A setting seems to be ignored?

Run:

/status

Claude is behaving incorrectly during a running session?

Use:

/debug

You've confirmed a genuine bug?

Use:

/feedback

Common /doctor Mistakes and Version Gotchas

Mistake 1: Assuming claude doctor can fix problems

It can't apply the same in-session fixes because it is designed as a read-only terminal diagnostic. If you need the interactive setup checkup, start a session and use /doctor.

Mistake 2: Assuming old tutorials are still accurate

This is especially important with /doctor.

The command changed substantially in v2.1.205, when it became a full setup checkup capable of diagnosing and fixing issues and gained the /checkup alias.

Mistake 3: Ignoring /mcp

If your problem is specifically an MCP server, don't stop after reading the /doctor result.

Run:

/mcp

The MCP panel provides server-specific status and approval information.

Mistake 4: Reinstalling too quickly

A broken configuration, plugin, hook, MCP server, or PATH entry does not necessarily require a clean reinstall.

Use diagnostics first so you know what you're actually replacing.

Mistake 5: Sharing sensitive diagnostic files publicly

Some troubleshooting tools can generate files containing sensitive information. For example, Claude Code's /heapdump can produce a heap snapshot containing conversation content and credentials, so it should not be publicly attached to an issue.

When reporting a problem, inspect diagnostic files before uploading them anywhere.

Mistake 6: Forgetting your Claude Code version

Check:

claude --version

If a check described in an older article is missing from your installation, first verify whether your version supports it.

Frequently Asked Questions

claude doctor

claude --debug mcp

Conclusion

Claude Code's /doctor command is a practical first step when your installation or configuration isn't behaving as expected. Run /doctor inside an active session when possible, or use claude doctor from the terminal when Claude Code cannot start.

For a more targeted investigation, combine it with the commands that match the problem: /mcp for MCP servers, /hooks for hooks, /context for context usage, /status for active settings, and /debug for runtime behavior. If the problem remains reproducible after local diagnostics, /feedback provides a path to report it with session context.

The biggest takeaway is simple:

Don't guess first.

Check status
    ↓
Run /doctor
    ↓
Identify the failing component
    ↓
Use the targeted command
    ↓
Apply the fix
    ↓
Run /doctor again
    ↓
Escalate if the problem remains

That workflow turns Claude Code troubleshooting from trial-and-error into a repeatable diagnostic process.