Why your coding agent freezes and how to fix it
Your coding agent isn't thinking. It's stuck. Here are the 6 root causes of agent freezes and what to do about each one.
TL;DR: Your coding agent isn’t thinking when the spinner sits for two minutes. It’s stuck. There are exactly 6 root causes for agent freezes in tools like Claude Code. Most of them have simple fixes once you know what to look for. The most common cause isn’t the model. It’s the HTTP client not having a read timeout.
Key takeaways:
- The spinner is not a reliable indicator of agent activity. It can stay active even after the response is complete
- Silent API streaming interruption is the #1 cause of agent freezes: the client has no read timeout
- Auto-compact thrashing happens when the context window fills and empties repeatedly in a loop
- Tool calls that generate massive output (>100K lines) trigger connection resets after 5 minutes
- Sending a “are you still there” message works because it forces a fresh HTTP request with the full session history
- Status line residue is the most deceptive freeze: the agent is done but the UI hasn’t updated
The freeze that isn’t the model
A developer posts on Reddit: “Claude Code just sat there for 30 minutes doing nothing. I asked it what was wrong and it said ‘I’m thinking.’ It wasn’t thinking.”
Another dev replies: “Press Enter. It wakes up instantly.”
Pressing Enter doesn’t fix the agent. It resets the HTTP connection. The agent wasn’t stuck in a reasoning loop. It was stuck in a network stack waiting for packets the API stopped sending.
This is the most common failure mode in coding agents, and it’s not about the model at all. It’s about the infrastructure between the model and the agent.
The 6 root causes
The 6 root causes. I collected these from the Claude Code GitHub issue tracker, Reddit threads, and my own builds. Root cause 1 accounts for about 40% of all reported freezes. Root causes 2 through 6 cover another 50%. The remaining 10% are environmental quirks.
Root Cause 1: Silent API streaming interruption
The HTTP client that connects your agent to the model API has no read timeout. This is a design choice that keeps the connection alive for long responses, but it means that when the upstream stops sending packets mid-stream, the agent has no way to detect the interruption.
The process stays stuck in epoll_wait waiting for data. The spinner keeps spinning. The token count doesn’t move. The agent looks like it’s thinking but it’s just waiting for a packet that will never arrive.
Common triggers: cross-border network jitter, tmux multiplexing, SSH long-lived connections that drop intermediate packets, load balancers that terminate idle connections.
The fix: Set an application-level timeout on the API call. If no data arrives for 60 seconds, close the connection and retry. Most coding agents don’t expose this as a configurable parameter yet, so the workaround is to run the agent on a stable connection, avoid tmux for long sessions, and monitor the token count manually.
Root Cause 2: Tool call payload too large
The agent executes a tool call that generates massive output. Writing a file with 100,000 lines. Listing a directory with 50,000 files. Running a test suite that outputs 10MB of logs.
The operating system resets the HTTP connection if no valid data is transmitted for 5 minutes. The agent does not catch this error. The tool call times out silently. The spinner stays active. This type of freeze lasts exactly 5 minutes before something unblocks. A Claude Code changelog documents known issues with tool call payload limits.
The fix: Split large writes across multiple smaller tool calls. If you’re generating a large file, generate it in chunks. If you’re running a test suite, run individual test files instead of the entire suite at once. Some agents support streaming output, which avoids the buffer entirely.
Root Cause 3: Auto-compact thrashing
When the agent’s context window approaches full, it triggers auto-compaction: it compresses the context to free up space. This works fine most of the time. But if a massive file or tool output is read back into context immediately after compression, the agent triggers another compaction. And another. And another.
The system eventually stops and throws an “Autocompact is thrashing” error. Before the error appears, the UI looks frozen for several minutes while the compaction loop runs in the background.
The fix: Monitor context usage percent. Most agents display it somewhere in the UI. The thrashing loop starts when context usage is consistently above 80% and large outputs are still being processed. The workaround is to start a new session when context gets high, or split the task across multiple subagent sessions instead of keeping everything in one long-running agent.
Root Cause 4: Context usage exceeds 80%
The official documentation for most coding agents states that response times degrade significantly once context usage exceeds 80%. “Degrade significantly” means response times go from seconds to minutes.
This looks like a freeze. The token counter is still slowly ticking up, but to a developer watching the spinner, it looks like the agent has stopped working.
The fix: Context usage is a preventable problem. The session should have been split into smaller tasks before it hit 80%. But once you’re in this state, the only effective option is to send a message that forces the agent to summarize and discard old context. Start your message with “Ignore the previous context and focus on this specific task:” to trigger context pruning.
Root Cause 5: Settings configuration deadlock
Some freezes happen before the agent even starts working. The agent hangs during startup because of a configuration conflict.
Common causes: enableAllProjectMcpServers: true combined with 10+ local MCP servers that all try to initialize simultaneously. Invalid path prefixes in additionalDirectories (most common on Windows: //C:/). Circular dependencies in MCP server configurations.
The fix is incremental configuration changes. Change one setting at a time, restart the agent, verify it works before making the next change. The MCP server configuration is the most common culprit. Start with a minimal set of servers and add them one at a time.
Root Cause 6: Status line residue
The agent has finished its response. The API returned 200 OK. The model output is complete. The tool calls are done. But the terminal UI’s spinner hasn’t cleared.
To the developer, it looks like the agent is still working. The spinner is spinning. The elapsed time is ticking. But the agent is idle, waiting for input it didn’t know it should provide.
Proof: Send a new message or press Enter. If the agent immediately processes the new input, it was never frozen. The UI was lying to you. The Claude Code GitHub issue tracker has multiple reports of this exact pattern.
The fix is a UI bug workaround. Check the token count. If it’s not moving and the elapsed time has been static for more than 10 seconds, the agent is probably done waiting for your input. Send a message.
When the fix is just pressing Enter
The reason pressing Enter or asking “are you still there?” works is specific to each root cause:
| Root cause | Why Enter fixes it |
|---|---|
| Status line residue (6) | The response was already complete. Your Enter is the next prompt. |
| Streaming interruption (1) | New input triggers the client to close the hanging connection and start a fresh HTTP request with the full session history. |
| Context thrashing (3) | New input breaks the compaction loop by giving the agent a new directive to focus on. |
| Context > 80% (4) | New input triggers context pruning as a side effect of the summarization process. |
For root causes 2 and 5, pressing Enter doesn’t fix anything. If the tool call is stuck in a 5-minute timeout window, Enter just queues up behind it. If the configuration is deadlocked, Enter can’t start the agent.
The three-sentence pattern for recovery:
- Check if the token count is increasing. If yes, wait. If no, proceed.
- If the agent was writing a large file or running a long command, wait the full 5-minute timeout window before intervening.
- If the token count has been frozen for more than 60 seconds, send a brief message. “Continue.” or “What are you working on?” is enough to trigger the connection reset.
Prevention over recovery
Six root causes sounds like a lot. The patterns reduce to two categories:
Network failures (1, 2, 6): The model completed its work but the connection between the model and the agent degraded. Fix: stable connections, short timeouts, and UI improvements.
Context management failures (3, 4, 5): The agent’s context window management is overwhelmed by the scope of the task. Fix: smaller sessions, subagent spawning, and earlier intervention.
The prevention strategy is the same for both categories: don’t let the session get long. An agent that’s been running for 30 minutes in the same session has accumulated too much context, too many pending tool calls, and too much opportunity for the network connection to degrade. Start fresh sessions for new tasks. Use subagents for parallel work. And if the spinner has been still for two minutes, check the token count before you assume the agent is thinking.
FAQ
How do I know if my agent is thinking or stuck? Check the token count or streaming indicator. If it’s incrementing, the model is producing output. If it’s static for more than 60 seconds, the agent is likely stuck in one of the 6 failure modes. The UI spinner is not a reliable indicator.
Will coding agents eventually fix these freezes? Most of these are known issues with open GitHub issues and active discussions. The status line residue (root cause 6) has a straightforward fix that hasn’t been prioritized. The read timeout issue (root cause 1) is a more fundamental design decision in the HTTP client. Expect incremental improvements rather than a single fix.
Does switching to a different coding agent solve these issues? Partially. The network-level issues (root causes 1, 2) are common across agents that use the same API protocols. The context management issues (3, 4) are mitigated by agents that implement better context pruning. Try a different agent for the same task and compare freeze frequency.
What should I do if my agent freezes mid-operation on a critical task? Save your work first. If the agent was editing files or running commands, check whether the changes were applied before the freeze. Then send a brief message like “Continue” or “Summarize what you’ve done so far.” This triggers the connection reset described above without adding confusing new instructions.
Is there a way to run agents that prevents freezes entirely? Not entirely, but you can significantly reduce freeze frequency: run agents on stable local connections (avoid tmux/SSH for long sessions), split large tasks into 10-15 minute sessions, use subagent spawning for parallel work, keep MCP server configurations minimal, and monitor context usage manually.
Related Posts
- Why agents break in production and stay broken. The five failure modes that cause silent degradation in deployed agents. Includes drift detection and context staleness.
- AI agent error handling patterns. Recovery patterns for production agent failures, including retry strategies and graceful degradation.
- AI agent context window management. Practical strategies for staying within context limits without losing session state.
This article was published on Agentic Up (https://agenticup.dev): practical guides for developers and founders building with AI agents. Reach me at [email protected]
