| name | claude-doctor-debugger |
| description | Use when diagnosing Claude Code install/update/auth/config/runtime health, broken customizations, safe mode, bare mode, debug logs, auto-mode classifier, settings validation, keychain or API-key auth boundaries, IDE/Chrome integration, doctor warnings, or update/install/setup-token issues. |
Claude Doctor And Debugger
Bundled commands use $PLUGIN_ROOT ($env:PLUGIN_ROOT in PowerShell; same path suffix) for the plugin root. Set it once: use the host's plugin-root variable when defined (Claude Code: PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"), otherwise the absolute path of this plugin's root directory.
Use this skill when Claude Code itself is failing or unclear: install/update
state, auth, settings, hooks, plugins, MCP startup, keychain/API-key boundaries,
safe-mode or bare-mode isolation, debug logs, auto-mode classifier behavior,
IDE/Chrome integration, or native build installation.
For broader safety contracts, read
$PLUGIN_ROOT/references/cli-operation-contracts.md.
Inspect First
Use the inspector and help output before running health checks:
python3 "$PLUGIN_ROOT/scripts/claude_code_inspector.py" --commands doctor auto-mode install auth --json
claude doctor --help
Avoid running claude doctor automatically in untrusted repositories because
its help warns that it skips the workspace trust dialog and may spawn stdio
servers from project MCP config.
Isolation Lanes
Use --safe-mode when customizations may be broken:
claude --safe-mode
claude --safe-mode --print "Check whether startup works."
Use --bare when the task needs minimal startup behavior, no keychain reads, no
hooks, no plugin sync, no auto-memory, and no CLAUDE.md auto-discovery:
claude --bare --print --settings /path/to/settings.json --add-dir /path/to/project "Inspect explicit context only."
In bare mode, auth is explicit: ANTHROPIC_API_KEY or an apiKeyHelper from
settings. Do not print or store key values.
Debug Logs
Use debug only for targeted failures:
claude --debug api,hooks
claude --debug-file /tmp/claude-debug.log --print "Reproduce the issue."
Debug output may contain local paths, prompt fragments, tool inputs, hook output,
or environment-derived details. Summarize issue names, timestamps, and error
classes rather than pasting raw logs.
Auto Mode
Read classifier state before changing settings:
claude auto-mode defaults
claude auto-mode config
claude auto-mode critique
Use this evidence when --permission-mode auto, tool denials, or custom
auto-mode rules behave unexpectedly.
Update, Install, Auth
Treat these as explicit user-request operations:
claude install stable
claude install latest --force
claude update
claude setup-token
claude auth
Do not run them speculatively. Report the intended target, version, and
credential boundary before changing anything.
Safety Boundaries
- Do not weaken permissions, hooks, MCP config, managed policy, or settings just to make startup pass.
- Do not expose keychain contents, API keys, long-lived tokens, OAuth secrets, bearer headers, debug logs, or settings secrets.
- Do not run
doctor in an untrusted directory unless the user selected that directory.
- Do not delete settings, transcripts, plugins, MCP entries, caches, or project state without explicit approval.
Completion Standard
Report the diagnostic lane, commands run, exact issue names or error text,
version/help facts used, any config/auth/update/daemon state changed, and the
smallest next repair or verified healthy state.
