The claude doctor command is a Claude Code diagnostic check for local setup problems, including authentication, terminal configuration, permissions, network access, and tool availability. c-ai.chat is an independent guide, not Anthropic; for broader context, see our Claude features overview and Anthropic’s official documentation.
- The short answer
- How it works
- What you would actually do with it
- Vs. the alternatives
- FAQ
- The honest take
- Sources
The short answer
The claude doctor command is for developers and technical users who run Claude Code locally and need a first-pass health check. Use it when Claude Code will not start, cannot authenticate, cannot access expected files, behaves oddly in your terminal, or fails in a way that looks local rather than model-related.
- What it does: checks your Claude Code environment for common setup issues.
- Where it runs: in your local terminal or Claude Code session, depending on your installed version.
- What it costs: the diagnostic command has no separate fee; Claude usage depends on your plan.
- Who it is for: developers, power users, and teams debugging Claude Code.
Use it first when the failure is unclear. If the check reports a local issue, fix that before changing prompts, switching models, or blaming the repository.
Think of it as the first diagnostic stop, not a repair button. It can point to likely causes. It cannot fix every failed install, corporate proxy, expired login, blocked shell permission, or workspace-specific configuration problem.
If you use Claude in the browser, this command is usually not relevant. Browser users should check Claude status, account access, and the official product at claude.ai. If you use the developer platform directly, start with our Claude API docs guide.
How it works
Claude Code runs in your local development environment. Failures can come from your Claude account, Claude Code installation, shell, workspace permissions, network access, or local tools the agent needs to call. The doctor check gives you a structured way to inspect those layers instead of guessing.
The exact output can change as Anthropic updates Claude Code. Treat the command’s own output, claude --help, and Anthropic’s Claude documentation as the authority for your installed version. If your build exposes claude doctor as a terminal command, run it there. If your build exposes doctor as an in-session check, start Claude Code and run the supported command inside the session.
A good diagnostic workflow keeps model behavior separate from local setup. If the doctor check reports a local issue, fix that first. If it passes but Claude Code still performs poorly, review the prompt, project context, permissions, rate limits, and service status.
Confirm the command your version supports
Run
claude --helpfirst. This avoids stale instructions for a different Claude Code build.Run the doctor check
Use
claude doctorif your CLI exposes it. If not, open Claude Code and run the doctor check inside the active session if your version supports that form.Read the result by layer
Separate account, install, shell, workspace, network, and permission findings. Do not change everything at once.
Fix one item, then rerun
After each fix, rerun the check. This makes it easier to identify which change solved the issue.
Escalate with evidence
If you need help, capture the error category, exact command, operating system, terminal, and whether Claude status shows an incident.
What you would actually do with it
The claude doctor command is useful when the failure is ambiguous. It helps you decide whether the problem sits in your machine, account, project, or Claude’s service layer. These are common cases where running it early saves time.
Example 1: Claude Code starts, then fails before useful work
If Claude Code opens but fails before reading files, editing code, or answering in context, start with the local diagnostic check. The issue may be authentication, project permissions, shell access, or a missing dependency.
claude --help
claude doctorIf the command reports an authentication problem, refresh your login using the method shown by your installed CLI. If it reports file permission issues, move to the project root and check whether your terminal can read and write the files Claude Code needs to inspect.
Worked example
Separating an account issue from a project issue
claude doctorThis prevents you from rewriting prompts when the real issue is your local environment.
Example 2: You changed machines or terminals
Claude Code can behave differently across machines, shells, terminal apps, and managed company laptops. A command that worked in one environment may fail in another because the shell path, permissions, network rules, or login state changed.
cd path/to/your/project
claude doctorRun the check from the same project directory where you plan to use Claude Code. File access and local tool availability can depend on the current directory. If your company uses device management, VPN rules, or outbound network filtering, the doctor output may point to a local policy rather than a Claude issue.
Example 3: Claude Code cannot see expected project context
If Claude Code responds as if it cannot see files that exist, verify the working directory before assuming the model misunderstood. The diagnostic command can help confirm whether the tool is running where you think it is running.
pwd
ls
claude doctorThen ask Claude Code a narrow question that proves context access:
Which files in this repository define the main application entry point?
Do not edit anything yet. Show the file paths first.If the diagnostic check passes but Claude Code still misses obvious files, the issue may be prompt scope, ignored files, workspace structure, or permissions granted inside the session.
Example 4: You suspect a service problem
Not every failure is local. If the doctor check passes and Claude Code still cannot connect, verify the official Claude status page. This is useful when several teammates see the same failure at the same time.
If status is normal, collect a minimal reproduction: the command you ran, the folder you ran it from, the terminal used, and the exact error text. Do not paste secrets, private keys, customer data, or proprietary files into a support request.
Example 5: You are testing Claude Code on a team
For a team evaluation, the doctor check helps standardize setup before people judge the tool. Ask each tester to run the same diagnostic workflow, then capture differences across operating systems, shells, permissions, and network environments.
Cost is a separate decision. Claude Code access depends on your Claude plan and product setup. Compare our Claude pricing guide with the official Claude pricing page.
Free
$0
Pro
$20/mo or $17/mo annual
Max
From $100/mo
Team Standard
$25/seat or $20/seat annual
Team Premium
$125/seat or $100/seat annual
Enterprise
$20/seat base + API rates
Vs. the alternatives
The claude doctor command is not a replacement for an IDE assistant, code search tool, or general terminal troubleshooting. It is a Claude Code-specific diagnostic. The useful question is not which assistant is smarter. It is which tool gives you the clearest path from failure to fix.
| Tool or approach | Best fit | What it checks well | Main trade-off |
|---|---|---|---|
| Claude doctor command | Debugging Claude Code setup | Local Claude Code environment, auth clues, workspace issues, connection symptoms | Specific to Claude Code; it will not diagnose every OS, IDE, or network problem |
| Cursor diagnostics | Developers working mainly inside Cursor | Editor integration, extension behavior, model access inside the IDE | Less relevant if your workflow is terminal-first or centered on Claude Code |
| GitHub Copilot troubleshooting | Teams standardized on GitHub and VS Code or JetBrains | Extension login, IDE state, GitHub account access, editor policy | Focused on Copilot’s editor integration, not Claude Code workflows |
| Sourcegraph Cody troubleshooting | Codebase search and enterprise code intelligence workflows | Indexing, repository access, Sourcegraph configuration | Strong for code search context, but not a Claude Code local health check |
| Manual shell debugging | Experienced engineers diagnosing unknown local failures | PATH, permissions, network, package managers, logs, proxies | Flexible but slower; easy to chase the wrong layer first |
Claude Code’s advantage is that it works close to the repository and the terminal. That also means it inherits local complexity. A browser-based assistant has fewer local setup variables. A full IDE assistant may provide smoother editor integration. A terminal coding agent can be more direct for repo-wide work, but it needs a clean environment.
Use the doctor check when
- Claude Code fails before a task starts.
- You moved to a new machine, shell, or managed laptop.
- You need evidence before asking support or an admin for help.
- Your team wants a repeatable setup check.
Do not rely on it when
- You are comparing model reasoning quality.
- The issue is clearly inside your application code.
- You are using only the Claude web app.
- You need a full enterprise network audit.
If you are choosing between Claude Code and other Claude capabilities, start with the workflow. Our Claude features overview separates web app features, coding workflows, API use, and team controls. For model differences, see our Claude models guide.
FAQ
These questions usually come from the same search path: someone is trying to make Claude Code work locally and needs a direct answer.
The honest take
The claude doctor command is worth knowing if you use Claude Code. It gives you a faster first step than guessing through auth, shell, network, and workspace problems. It is especially useful for teams because it creates a shared diagnostic routine before people blame the model, the prompt, or the repository.
Its limits are clear. It will not replace system administration, IDE diagnostics, model evaluation, or Anthropic support. Use it to answer one practical question: “Is my local Claude Code setup healthy enough to trust the next result?” If the answer is no, fix the environment first.
Independent guide. Not affiliated with Anthropic. For the official Claude product, visit claude.ai.
Last updated: 2026-05-12
This article is part of the Claude Code hub on c-ai.chat.
