Try free

Last updated 13 October 2026

What to do when Claude Code gets stuck

Detecting a frozen terminal session

Your terminal might stop responding when the agent is deep in a complex task. You see a blinking cursor but no new text appears. This often happens when the agent uses the Bash tool to run a command that does not terminate, such as a local server or a file watcher. The agent waits for the process to finish before it continues the conversation. Because the agent expects a clear exit code to proceed, it remains in a state where it cannot accept new input or show progress.

A hang can also occur during heavy file operations. If the agent runs a Glob or Grep command on a very large directory without proper exclusions, the process might take minutes to return results. During this time, the interface feels dead. You might suspect a network error, but usually, the agent is simply waiting for the underlying shell to provide the data it requested. You need to distinguish between a slow tool execution and a complete crash of the command line interface.

Immediate recovery with key commands

The first step to resolve a stuck session is the Escape key. Pressing Escape once sends an interrupt signal to the agent. This tells it to stop the current tool execution and return control to you. If the agent was caught in a loop or waiting for a long process, this usually breaks the cycle. You should see a message indicating the task was interrupted. From there, you can ask the agent to try a different approach or check the status of the files it was modifying.

If a single Escape does not work, press Escape twice in rapid succession. This command offers you a list of earlier messages to go back to. It is a powerful way to rewind the session state to a point before the hang occurred. If the entire terminal remains unresponsive to any keyboard input, use Ctrl+C to quit the process entirely. After quitting, you can run claude --continue to pick up the conversation. The agent stores the session history, so you rarely lose work by restarting the process from your shell.

Verifying the environment and installation

When hangs become frequent, you must check if the tool itself is healthy. Run the command claude doctor in your terminal. This built-in diagnostic tool checks your network connection, API access, and local environment. It identifies issues with your shell configuration or permission settings that might cause the agent to stall. If the doctor command reports issues with the version, run claude update to ensure you have the latest fixes for known stability problems.

Sometimes the problem lies in how your terminal handles the interactive UI. If you see garbled text or the cursor jumps to the wrong place, run /terminal-setup inside a session. This command helps reconfigure the display settings for your specific terminal emulator. If you suspect the project configuration is causing the lag, check the root of your repository for the CLAUDE.md file. If this file is too large or contains conflicting instructions, the agent might struggle to process the initial context, leading to delays every time it starts a new tool call.

Managing context and memory limits

A session that has gone on too long becomes heavy. Every message adds to the context window. As the window fills up, the agent takes longer to process your prompts and generate answers. Use the /compact command to summarize the session history. This reduces the amount of data the agent must track while keeping the important details of your progress. Reducing context size often restores the snappiness of the interface and prevents timeouts during code generation.

If a specific session is beyond saving, use /clear to start over in the same folder. This wipes the current conversation context but keeps your files intact. You can also monitor your resource usage with /cost and /usage. These commands show you how much data you have processed. High cost often correlates with large context windows that slow down the response time. Keeping sessions short and focused on one specific task is the best way to avoid the lag that leads to a frozen state.

Fixing tool and permission loops

The agent often stops because it is waiting for your permission to run a tool. If you are in the default permission mode, the agent asks for approval before it uses Bash or Write. If you do not see the prompt because of a scroll issue, the session looks stuck. You can cycle through permission modes using Shift+Tab. Moving to bypassPermissions mode allows the agent to run tools without asking, which can smooth out the workflow for complex multi-step refactoring tasks.

You can also control these behaviors in your settings files. Check .claude/settings.json in your project or ~/.claude/settings.json for your user-wide defaults. You can specify which tools are allowed to run automatically under the permissions key. If a tool like WebFetch or WebSearch is hanging, it might be due to a proxy or firewall issue. Verify your internet settings if the agent stalls specifically when it tries to access external websites or search the web for documentation.

Handling Model and MCP server delays

If you use Model Context Protocol servers, they can be a source of instability. Use the command claude mcp to manage your active servers. If a server is poorly configured or unresponsive, any tool call directed to it will cause the terminal to hang. You can check your .mcp.json file to see which servers are active. If one is causing trouble, remove it or fix its configuration to restore performance. You can also use /mcp inside a session to check the status of connected servers.

The /model command allows you to see which model is currently driving the agent. Some models are faster than others, and switching can sometimes resolve persistent generation failures. If the agent is stuck in a loop of failed edits, use /review to see what it has done so far. This gives you a chance to spot mistakes in the logic that might be causing the agent to repeat the same failing Bash command over and over. Breaking the loop manually is faster than waiting for a timeout.

Monitoring multiple sessions with adhdTerminal

When you work on multiple parts of a project, you might have several sessions running. Tracking which one is stuck becomes difficult in a standard terminal. This is where adhdTerminal helps. It organizes your sessions into a wall of tiles. Each tile shows a status indicator like working, waiting, or idle. If a session in one folder hangs, you can see at a glance that it is still in the working state while other tiles remain ready for input. This visual feedback prevents you from waiting on a process that has actually failed.

The app allows you to run these sessions side by side on macOS or Windows. If a complex task in one tile is taking a long time to output code, you can move to another tile and continue working on a different subagent or project. Each tile keeps its own name and color, making it easy to remember the context of each session. If you need to step away, the iPhone app mirrors this wall, letting you see if a long-running generation finished or if it is still waiting for a prompt from you.

Recovering lost work and session state

If the terminal crashes and you lose the interface, your work is usually safe. The agent saves sessions automatically. Use claude --resume to see a list of previous sessions and pick the one you were working on. This command is a lifesaver when a system update or a terminal crash interrupts a long coding task. If you want to carry on exactly where you left off in the current directory, claude --continue is the fastest path back to a working state.

For critical tasks, you can use /export to save the current session history to a file. This is useful if you suspect the environment is becoming unstable and you want a backup of the conversation. If you find yourself repeatedly stuck on the same type of task, consider creating a subagent. You can define these in .claude/agents as markdown files. Subagents can handle specific parts of your workflow with their own instructions, which keeps the main session context cleaner and less prone to the bloat that causes hangs.

Questions people ask

What should I do if the agent keeps trying the same failing command?

Interrupt the agent by pressing Escape. Use /clear to reset the context if it is stuck in a logic loop, or manually edit the file it is struggling with to give it a better starting point. You can also use /review to see the history and point out exactly where the agent is making the mistake.

Why does the interface freeze when I use the Edit tool on large files?

The agent must read and process the entire file to apply changes accurately. For very large files, this can exceed the context window or cause a timeout. Try breaking the file into smaller modules or use /compact to free up context space before running the Edit tool.

How can I prevent the Bash tool from hanging on long-running processes?

Ensure you are not running commands that stay open, like servers or continuous tests, without backgrounding them. If a process does hang, kill it from a separate terminal window using standard system commands. The agent will usually detect the process has ended and return to the prompt.

Read next

More on claude code basics·All posts