Try free

Last updated 13 October 2026

How to use the doctor command to fix Claude Code

Diagnose your environment with the doctor command

You run the command to start a session and a wall of stack traces appears instead of a prompt. This usually happens when your environment variables are missing or the binary cannot find its supporting files. The command line coding agent relies on a specific setup to execute tools like Bash and Read safely. When these tools fail without an obvious reason, you need an automated check of your local setup.

The first step is to run the standalone diagnostic tool by typing "claude doctor" in your terminal. This command checks if your system meets the requirements and validates your authentication status. It looks for the necessary configuration files and ensures the agent has the right level of access to your file system. If the doctor finds an issue, it prints a specific error message that tells you exactly what is missing or misconfigured in your environment.

Running this command is the fastest way to see if your node environment or path variables are interfering with the agent. It checks the integrity of the installation and ensures that the command line interface can communicate with the backend services. If you have recently changed your shell or moved your project folders, the doctor will identify where the links are broken. It provides a clear report on the status of your connection and the availability of the core tools the agent needs to function.

Fix issues inside an active session

Sometimes the agent starts correctly but begins to behave erratically once you are inside a project. You might notice that the agent cannot read files it should see or it fails to execute simple shell commands. In these cases, you do not have to exit the session to run diagnostics. You can use the internal "/doctor" command directly from the prompt to check the health of the current interactive session.

This internal check focuses on the context of your specific project. It verifies that the agent can access the project root and any local configuration like the CLAUDE.md file or custom slash commands. If the agent is stuck in a loop or cannot use its tools, the doctor report will show if there is a problem with the process or the underlying shell integration. This allows you to fix the environment without losing the history of your current work or closing your active subagents.

The internal diagnostic also checks the state of your MCP servers. If you use external tools through the "claude mcp" management system, the doctor command will report if those servers are responsive. This is vital when your agent claims it cannot find a database or a specific API that you have configured in your .mcp.json file. Instead of guessing which part of the stack is broken, you get a direct status update on every connected service.

Repairing permissions and configuration files

Claude Code stores your preferences and tool permissions in specific JSON files. If you accidentally corrupt settings.json or settings.local.json, the agent might refuse to start or it might block every tool execution. The doctor command identifies syntax errors in these files and warns you if the permissions are too restrictive. You should check the .claude directory in your home folder and your project root to ensure these files are readable by your user account and follow the correct format.

The agent uses different permission modes like default and plan to determine when it needs to ask for your consent. If you find that the agent is asking for permission on every single edit even when you want it to work autonomously, the doctor command helps verify your current mode. You can cycle through these modes using Shift plus Tab, but the doctor report confirms if a hardcoded setting in settings.json is overriding your manual changes.

If you manage your settings across multiple projects, you might have conflicting rules in the home directory settings and the local project settings. The doctor command clarifies which settings are currently active and which files the agent is ignoring. This is particularly helpful when you are trying to debug why the agent is ignoring certain directories or why it refuses to use the WebSearch tool in a specific environment.

Organize multiple sessions across different projects

When you work on several repositories at once, keeping track of different Claude Code sessions becomes difficult. Each session has its own state and its own set of challenges that might require a doctor check. If you find yourself constantly running "claude --resume" to find the right thread, you might benefit from a more visual way to manage these agents. This is where adhdTerminal provides a native solution for macOS and Windows.

adhdTerminal runs many Claude Code sessions side by side as tiles on a wall. Each tile shows you whether the agent is working, waiting for you, or idle. If one session starts failing because of a local configuration issue, you can see the diagnostic output right there on the tile. This prevents the confusion of having many different terminal tabs open where you cannot remember which one needs a doctor fix or an update.

The app allows you to keep each project in its own space while maintaining a high level view of all your active agents. Because tiles reopen in the same place after a restart and resume the same session, you do not have to worry about the overhead of re-running diagnostic commands every time you switch tasks. If a tile shows an error state, you can quickly jump in, run "/doctor", and fix the problem without affecting your other active work streams.

Resolve tool execution and shell errors

The effectiveness of the agent comes from its ability to use tools like Bash, Edit, and Glob. If "claude doctor" reports that these tools are failing, the issue is often related to your shell configuration. The agent needs a clean environment to run commands and read the output. You might need to check your terminal setup or run the "/terminal-setup" command inside the session to ensure the agent integrates correctly with your system shell and path variables.

If the agent can search for files using Glob but fails to modify them with Edit, the problem is likely a file lock or a permission issue in the project directory. The doctor command will flag if the agent lacks Write permissions for the target folder. You should also verify that your .gitignore file is not accidentally hiding files the agent needs to see. The agent respects these rules by default, so a misconfigured ignore file can make the agent appear blind to your source code.

Sometimes the issue is with the temporary files the agent creates during a task. If your disk is full or your temporary directory has restricted permissions, tools like NotebookEdit or TodoWrite might fail. The doctor command checks for basic disk availability and write access to these system areas. By following the suggestions in the doctor report, you can resolve these environment blocks that would otherwise be very difficult to track down manually.

Update the agent and clear the context

If the doctor command shows that your installation is healthy but the agent still makes repetitive mistakes, the issue might be a full context window. As a session grows, the conversation and the files the agent has read fill up the available space. You can use "/compact" to summarize the session or "/clear" to start over in the same folder with a fresh slate. This often resolves performance issues that look like technical bugs but are actually just limits of the current session context.

When all else fails, you should ensure you are running the most recent version of the software. Run "claude update" to pull the latest improvements and bug fixes from Anthropic. After an update, it is a good practice to run "claude doctor" one more time to confirm that the new version is correctly configured for your specific machine. Keeping the agent updated ensures that you have the latest tool definitions and the most stable shell integration.

You can also use "claude --resume" to pick an earlier, stable session if a current one has become corrupted or unmanageable. The doctor command can help you identify if the issue is persistent across all sessions or isolated to one specific project history. By combining these maintenance commands, you can keep your development environment fast and reliable. Regular checks with the doctor tool prevent small configuration drifts from turning into major workflow interruptions.

Questions people ask

What should I do if the doctor command says I am not logged in?

You need to run the "/login" command to authenticate your session with Anthropic. This will open a browser window where you can complete the sign in process. Once you are logged in, the agent will have the necessary credentials to reach the models and execute your prompts.

Why does the doctor report a failure with the Bash tool?

This usually happens if your default shell has a complex startup script that interferes with non-interactive sessions. You can try to simplify your shell profile or use the "/terminal-setup" command to fix the integration. Ensure that your shell does not print extra text or require manual input during the agent initialization.

Can I run the doctor command if I am offline?

The doctor command can check your local configuration and file permissions while you are offline. However, it will report a failure when it tries to verify your authentication status and connection to the Anthropic servers. You should use it to fix local path and tool issues, then run it again once you have a stable internet connection to finish the diagnostic.

Read next

More on claude code basics·All posts