Why is my Claude Code session slow / hung / not authenticating?

Pick the branch by what just happened, not by the surface symptom. Most “Claude is broken” reports resolve into one of five branches plus a /clear.

What just happened?

You typed claude and got an error. Install or login problem. Common shapes: command not found, EACCES on install, OAuth login loop, 403 Forbidden, “organization disabled”, Bedrock/Vertex/Foundry auth issues. The canonical page is Troubleshoot installation and login. Re-running the install rarely hurts; if the install itself is fine, the issue is auth scope (your account, your org, your provider).

You changed a setting and Claude is ignoring it. Settings not applying, hooks not firing, MCP server not loading. The canonical page is Debug your configuration, and the most common cause is precedence: a higher layer is overriding the file you edited. Run /status inside the session to see which settings sources loaded and which (if any) had parse errors. The file winning the precedence chain is the file the classifier or hook is actually reading.

A specific tool call is hanging. The model was fine until one tool call sat for 30+ seconds and never returned. Press Ctrl+C inside Claude to interrupt; the cancellation propagates to the running tool. After interrupting, ask: was the tool an MCP server, a long-running shell command, or a network read? MCP server hangs are usually the MCP process itself; check connection status in-session with /mcp and config details with claude mcp get <server>. Long-running shell hangs are usually the command running fine but buffering output instead of streaming it.

The session is slow or auto-compact is thrashing. Auto-compaction reports a thrashing error when the conversation cannot fit even after summarization. The canonical playbook: run /compact to force a deeper summary, delegate any further noisy reads to a subagent so the parent context stays small, or /clear and start fresh if the work is recoverable from a tighter prompt. Signs visible before the thrash: /context pinned at 95%+, every turn is sluggish, recent file reads or skill bodies dominate the budget. Catch it earlier next time by running /context after any large file read or research subagent return.

Search results are missing or wrong. “Find every reference to parseDate” returns three matches when you know there are ten. On WSL specifically, ripgrep pays a heavy cross-filesystem disk penalty when the repo lives on a Windows-mounted drive and Claude is reading it from the Linux side; the result is fewer matches in the time budget the tool allows. Defenses: scope the search (“in src/lib/”, “only *.ts”), break the question into smaller queries, move the repo onto the Linux filesystem (/home/...) instead of /mnt/c/..., or run rg in your shell and paste the result to Claude.

When the branch is not obvious: diagnostics order

1. /status: verify which settings sources loaded and surface any parse errors.

2. /context: see the budget breakdown by category. Over 80% and feeling off? /clear is faster than debugging.

3. claude --debug (or the /debug command in-session): record the startup trace, including which CLAUDE.md files loaded, which hooks registered, and which MCP servers connected. Use claude --debug hooks to watch hook evaluation live, or claude --debug mcp to see an MCP server’s stderr output. The debug log is written outside your transcript; Claude Code prints the path on session exit.

4. For MCP connection status during a session, run /mcp in the prompt. For server config details (auth status, configured URL, OAuth state), run from the shell:

   claude mcp get postgres

5. Error reference page: if Claude’s reply contains an API error code (5xx, 429, 529, 400), look it up. The page tells you whether to retry, change the prompt, or escalate.

Footguns

Auto-compact thrashing has a recovery ladder, but it does not climb itself. Run /compact to force a deeper summary, then keep further reads small (a single file at a time, no full-tree greps). If the next turn still thrashes, move noisy work into a subagent so it never touches the parent context, and as a last resort /clear and re-prime from a tighter prompt. The mistake to avoid is asking Claude to “summarize where we are” without /compact: that adds another full turn to a context that already does not fit.

claude --debug writes to the debug log, not the transcript. New users run --debug, see no extra output in their session, and conclude the flag did nothing. The flag enables verbose logging to disk; the terminal session looks identical. Tail the debug log from another terminal while reproducing the bug if you want live output.

WSL search degradation is silent. ripgrep returns whatever it found within the time budget, with no warning that the result is partial; reads of files on a Windows drive (/mnt/c/...) from inside WSL are dramatically slower than reads of files on the Linux filesystem. A “Claude cannot find the function” report on WSL with a 50K-file Windows-mounted repo is almost always this. Either move the repo onto /home/..., scope every search to a smaller directory, or run search on the host OS and feed Claude the result. Asking Claude to retry the same search hits the same disk-IO ceiling.

Hung tool calls are usually the tool, not Claude. A 60-second wait on mcp__postgres__query is the database, not the model. A 30-second wait on Bash(npm install) is npm doing actual work. Press Ctrl+C inside Claude to interrupt a hung tool call; the cancellation propagates to the running tool. After cancelling, fix the underlying tool (the slow query, the hanging server) before re-asking, otherwise the same tool will hang again.

“Settings not applying” is precedence nine times out of ten. The file you edited is fine. The file overriding it is the file you forgot existed. /status lists every settings source in load order with parse status. Read it before retyping the rule.

When NOT to debug

• The session has been wandering for an hour. /clear and rebuild from a tighter prompt. Long sessions accumulate failed approaches as context noise; debugging the noise loses to starting fresh.
• You hit a 5xx for the first time. Anthropic’s API has occasional blips. One 529 Overloaded is transient; retrying after 30 seconds usually works. Open a ticket on persistent failures, not on the first one.
• You did not read the error message. “Claude failed” with no detail is not a bug report; the message is in the transcript. Read it. The error reference page covers most of what you will see.
• The tool you blame works fine elsewhere. If prettier --write works in the terminal but the format-on-edit hook fails, the issue is in your hook config, not in prettier. Reproduce the failing piece directly before assuming the integration is broken.
• You are about to file a support ticket without claude --debug output. Anthropic support’s first ask will be the debug log. Capture it before opening the ticket; it is the difference between same-day and next-week resolution.