Free script
Find out why Claude Code fails, in one run
ECONNRESET, "subscription disabled", a crash at launch, hooks that never fire: the cause is almost always one of a dozen things. claude-doctor.sh checks all of them and tells you which fix to try first. It reads; it changes nothing.
You also get my weekly notes on Claude Code and production AI. One click to unsubscribe.
Install
OK claude 2.1.296 at /opt/homebrew/bin/claude
WARN 2 different claude binaries on PATH
-> keep one install method
Authentication
WARN credential variables set: ANTHROPIC_API_KEY
-> these override your subscription login
Network
OK api.anthropic.com reachable (HTTP 403 in 0.21s)
OK TLS issuer: Google Trust Services
Hooks
FAIL PreToolUse: hook not executable: .claude/hooks/deny-rm.sh
-> chmod +x .claude/hooks/deny-rm.sh
1 failure(s), 2 warning(s).
What it checks
Install
Is claude on your PATH, and how many copies? Old npm installs shadow the Homebrew cask and the native installer. Node too old or too new, and the macOS quarantine flag.
Authentication
Credential variables (ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, Bedrock, Vertex, Foundry) that silently override your Pro, Max or Team subscription.
Network
Proxy and VPN variables, whether api.anthropic.com answers, and which certificate authority signs the connection: a corporate CA means a TLS-inspecting proxy, the usual cause of ECONNRESET.
Settings files
A malformed ~/.claude/settings.json, .claude.json, project settings or .mcp.json can crash every launch. Each one is parsed.
Hooks
Every command hook in your settings is checked: a missing or non-executable hook fails open, and the tool call goes ahead unguarded.
Then: claude doctor
The script ends by pointing you to Claude Code's own claude doctor for the checks only it can do. The two together cover the errors behind my most-read posts.
The fixes themselves are free on the blog: ECONNRESET, subscription disabled, broken Homebrew install, hooks that don't fire. The script just finds which one you have.
If you want the rest
Claude Code Guardrails Pack
The doctor script is one file from the pack. The pack adds four tested hooks with a one-command installer (no rm, no packages published yesterday, no commit before the tests pass, no writes outside the repo), settings presets for you and your team, a CLAUDE.md template and the troubleshooting playbook as a PDF.
See the pack · $19