Claude Code Config Chaos? Run a Single ‘doctor’ Command to Diagnose and Fix

1. Two ways to run doctor, different capabilities

The terminal command claude doctor performs a read‑only health check, reporting installation and configuration problems without making changes. The in‑session command /doctor (alias /checkup) conducts a full check‑up and, after user confirmation, can apply fixes.

2. What a typical doctor report looks like

claude doctor
Running: native (2.1.205)
Commit: 4cf2699a1427
Platform: darwin-arm64
Path: /Users/xxx/.local/share/claude/versions/2.1.205
Config install method: native
Search: OK (bundled)
Auto-updates: disabled (set by env: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC)
Auto-update channel: latest
Last update attempt: failed (install_failed) — 2026-07-09

No installation issues found.

Key lines to notice are the running version/path, the auto‑update status (often disabled by the environment variable CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC), and the timestamped reason for the last update failure.

3. What /doctor can detect and fix

Installation health – same checks as the terminal version, plus automatic repair suggestions.

Unused extensions – identifies extensions that consume context but are never used, recommending they be disabled.

Duplicate memory files – spots local memory that duplicates already‑indexed content and suggests deduplication.

Guidance‑to‑lazy‑load conversion – moves always‑loaded explanatory content to lazy‑load mode.

Slow hooks – pinpoints hooks that degrade operation speed.

Version check – confirms you are not running an outdated version.

Permission polishing – advises setting auto mode as the default permission mode and pre‑approving read‑only commands that are repeatedly blocked.

Malformed settings.json – reports invalid JSON immediately.

Subagent name clash – warns about same‑directory subagents that would conflict.

Note that a typo in a configuration key (e.g., permisions) does not trigger an error; you must verify the effective configuration with /status or /config.

4. Configuration files and their priority

~/.claude/settings.json

– global user settings (theme, permissions, hooks, env). Low priority. .claude/settings.json (project‑level) – shared settings committed to Git. Medium priority. .claude/settings.local.json – personal overrides that are not version‑controlled. High priority. ~/.claude.json – not a settings file; stores runtime state such as login tokens, project caches, and input history.

The most common pitfall is editing ~/.claude.json as if it were a settings file; changes there have no effect and doctor will not flag them.

5. Commands that complement doctor

/config

– interactive UI to modify configuration values. /status – shows which configuration layer is currently active. /context – reports how much context is consumed by CLAUDE.md and skills. /mcp – displays MCP server status and allows re‑approval. /permissions – shows the merged permission rules. claude --safe-mode – runs Claude Code with all customizations disabled, useful for isolating problematic extensions or hooks. claude project purge – deletes all on‑disk state for a given project, freeing up space and removing stale transcripts.

6. My troubleshooting sequence

When behavior is odd, run claude doctor in the terminal for a quick report.

If the report shows issues or you want automatic fixes, run /doctor inside a Claude session and confirm each change.

If doctor reports no problems but the issue persists, run claude --safe-mode to compare a clean run against the current setup and pinpoint the offending customization.

For abandoned projects, execute claude project purge /path/to/old‑project to erase its state without touching other projects.

Because doctor can diagnose, suggest fixes, and back up the original settings.json before any change, reinstalling Claude Code (which only replaces the binary under ~/.claude) is unnecessary when the problem lies in configuration.