Why You Should Run claude doctor

You’ve been there. Claude Code starts acting strangely: a command isn’t found after an update, an MCP server won’t connect, or a settings change seems to be ignored. So you start guessing. You reinstall, you edit config files, you search forums.

Before any of that, run one command:

claude doctor

It takes seconds, changes nothing, and often points straight at the problem.

What is claude doctor?

claude doctor is Claude Code’s built-in diagnostic command. According to the official CLI reference, it prints read-only installation and settings diagnostics from your terminal without starting a session. That includes:

• Install health: is Claude Code installed correctly and reachable?
• Settings validation errors: is your settings file valid?
• Remote Control eligibility: can this setup use Remote Control?

Because it runs outside a session, it works even when Claude Code won’t start properly, which is exactly when you need a diagnostic tool most.

Two ways to run it

The in-session version is the more powerful one. Per the docs, /doctor is the “setup checkup that can also apply fixes”, so you can go from diagnosis to repair without leaving the session. Community write-ups also note that /checkup works as an alias, and that you should review each proposed fix before accepting it.

A good habit:

1. Something feels off? Run claude doctor in your terminal for a quick, safe report.
2. If it flags problems, open a session and run /doctor to work through the fixes.

5 reasons to run it

1. It’s the fastest first step in troubleshooting

Most “Claude Code is broken” moments fall into a few buckets: a broken install, a stale launcher, a bad config, or a connection issue. claude doctor checks the basics first, so you don’t spend an hour chasing something it would have flagged in seconds.

2. It works when Claude Code won’t start

If you can’t open a session, you can’t run slash commands. The terminal version needs no session, so it’s your lifeline when things are really broken.

3. It catches settings mistakes you’d never notice

A stray comma or a wrong key in a JSON settings file can quietly stop your configuration from applying. Settings-file validation errors are part of what claude doctor reports, so a typo shows up as a clear message instead of mysterious behavior.

4. It’s a great post-update sanity check

After running claude update or installing a new version, take ten seconds to run the doctor. Catching a problem right after a change is far easier than debugging it three days later.

5. It’s safe

The terminal command is explicitly read-only. It reports; it doesn’t modify. You can run it as often as you like with no risk, and the in-session fixes are applied only when you confirm them.

When should you run it?

• Right after installing or updating Claude Code
• When behavior suddenly changes for no obvious reason
• When MCP servers or other integrations stop connecting
• After editing your settings by hand
• Before you open a bug report, since the output is useful context to include
• Whenever you’re about to reinstall. Don’t, until you’ve run the doctor.

What it can’t do

claude doctor is a first responder, not a cure-all. A clean report doesn’t guarantee everything is fine. If it comes back healthy but something still misbehaves, reach for the next tools:

# Verbose logging to see what's happening under the hood
claude --debug

# Start with all customizations disabled (CLAUDE.md, hooks, plugins, MCP servers...)
# to find out whether one of them is the culprit
claude --safe-mode

# Check your version
claude --version

--safe-mode is especially handy: it keeps authentication, model selection and built-in tools working while turning off your customizations, so you can quickly tell whether the problem is Claude Code itself or something you’ve added.

Quick start

# 1. Health check from your terminal
claude doctor

# 2. Still not right? Start a session and run the full checkup
claude
> /doctor

That’s the whole routine.

Final thoughts

Good developers build the habit of checking the simple things first. claude doctor is that check for Claude Code: quick, read-only, and available even when nothing else works. Next time something feels off, run it before you reach for reinstalls and forum searches. It may save you an afternoon.

Have a favorite Claude Code troubleshooting trick? Share it in the comments.

References

• Claude Code CLI reference: official description of claude doctor, --safe-mode and --debug