Last updated 13 October 2026
What to do when Claude Code keeps looping
Recognize when the agent is stuck in a cycle
Claude Code can sometimes enter a repetitive cycle where it runs the same failing command over and over. You might see the Bash tool attempt a build or a test and fail with a specific error. Instead of trying a new approach, the agent might perform a slight variation of the same task or even the exact same task again. This behavior wastes your tokens and clutters your session history with redundant logs. It often happens because the agent believes a minor environmental change or a second attempt will yield a different result.
The loop usually begins when the agent lacks the specific context needed to solve a complex error. It sees a stack trace and tries a superficial fix. When that fix does not work, it might use the Read tool to look at the same file again and then use the Write tool to apply the same incorrect patch. Recognizing this early is vital. If you see the same terminal output appearing multiple times in a row, you must intervene. Waiting for the agent to figure it out on its own often leads to an exhausted budget or a corrupted state in your local files.
Use the Escape key to interrupt execution
The fastest way to stop a loop is to press the Escape key once. This immediately interrupts whatever tool the agent is currently using. If the agent is in the middle of a long Bash script or a WebSearch, this stops the process and gives you back the prompt. You can then provide a direct instruction to the agent. Tell it exactly why the previous approach failed or point it toward a different part of the codebase that it has not yet explored. This manual correction breaks the cycle and resets the logic of the session.
If the loop has already generated a long chain of messages, you can press the Escape key twice in rapid succession. This opens a menu that allows you to go back to an earlier message in the conversation history. You can select a point in time before the loop started and resume from there. This effectively rewrites the history of the session and removes the confusing, repetitive failures from the context window. It is a powerful way to restart a task without losing all the progress you made before the agent got stuck.
Reset the session context with compact and clear
A looping session fills the context window with junk data. Every repeated error message and failing test log consumes space and makes it harder for the agent to reason accurately. You can use the /compact command to summarize the conversation so far. This keeps the essential progress but removes the noise of the repeated failures. It helps the agent focus on the ultimate goal rather than getting distracted by its own recent mistakes. Keeping the context clean is one of the best ways to prevent future loops.
If a session is too cluttered to save, use the /clear command. This wipes the conversation history within the current terminal instance but leaves your actual project files untouched. You can then start fresh with a more specific prompt that avoids the pitfalls of the previous attempt. If you need to see what the agent did in an earlier session to avoid repeating it, you can run claude --resume or use the -r flag to list your recent work. This allows you to learn from the failed loop without being trapped by its history.
Enforce project rules in CLAUDE.md
The CLAUDE.md file is your primary tool for setting boundaries for the agent. If you notice that Claude Code always tries to run a specific test command that fails in your local environment, write a rule in CLAUDE.md to forbid it. You should use this file to specify the exact build commands, test runners, and linting tools that the agent should use. This prevents the agent from guessing and entering a trial and error loop. Clear instructions in this file reduce the ambiguity that leads to repetitive behavior.
You can place a CLAUDE.md file in the root of your repository for project-wide rules. If a specific subdirectory has unique requirements, you can place another CLAUDE.md file there to override the root settings for that part of the tree. For rules that you want to apply to every project you work on, use ~/.claude/CLAUDE.md in your home directory. These files are the first thing the agent reads when it starts. By defining your environment clearly, you ensure the agent uses the Bash and Edit tools in a way that aligns with your actual workflow.
Control autonomy with permission modes
Claude Code offers several permission modes that change how much the agent can do without your approval. You can cycle through these modes by pressing Shift+Tab while inside a session. The default mode will ask for permission for certain sensitive actions. If the agent is looping through commands that are safe but expensive, switch it to plan mode. In plan mode, the agent will describe its intended actions but will not execute any tools. This gives you a chance to review its logic and stop a loop before it even starts.
You can also fine-tune these behaviors in your .claude/settings.json file. You can set specific tools like Bash or Write to always require permission. This forces the agent to stop and wait for your input after every step. While this is slower, it is the most reliable way to prevent an automated loop from running away with your budget. If you are working on a particularly difficult bug, using plan mode allows you to act as a navigator while the agent acts as the driver, ensuring every move is deliberate and correct.
Monitor multiple sessions with tiles
If you are managing a large project, you might have several Claude Code sessions running at once in different directories. It is easy to lose track of one terminal window while you are focused on another. This is where adhdTerminal can help. It organizes your sessions into a wall of tiles on your screen. Each tile shows the color, number, and name of the session, along with the most recent exchanges. You can see at a glance if an agent is working, waiting for your input, or stuck in a repetitive loop without having to click through multiple terminal tabs.
The visual nature of the tile wall makes it obvious when an agent is repeating the same error message. You can see the status of all your tasks simultaneously. If you need to step away from your desk, the free iPhone app mirrors your wall over an encrypted link. You can check your phone to see if a long-running task has entered a loop and send a quick prompt or a next task to get it back on track. This keeps your development moving forward and ensures you never waste tokens on an agent that has stopped making progress.
Extend capabilities with MCP and custom commands
Sometimes a loop happens because the agent does not have the right tools to solve the problem. You can use the claude mcp command to manage Model Context Protocol servers. These servers can give the agent access to external data or specialized tools that are not part of the standard set. If the agent is looping because it cannot find documentation or specific API details, an MCP server can provide that missing information. Adding the right context through MCP can turn a failing loop into a successful task.
You can also create your own custom slash commands. These are markdown files stored in the .claude/commands directory. A custom command can provide a hard-coded sequence of instructions for a complex task that the agent often struggles with. By giving the agent a predefined path to follow, you remove the need for it to guess. You can also use hook events like PreToolUse to run scripts that check the state of your project before the agent proceeds. These customizations allow you to build a more resilient environment that is less prone to AI errors.
Debug the installation and use shell history
If loops continue to happen despite clear instructions, there might be an issue with your setup. Use the /doctor command inside a session or claude doctor in your terminal to check your installation. This command looks for common configuration errors that might be confusing the agent. You should also ensure you are running the latest version by using the claude update command. Keeping the software updated ensures you have the latest improvements in how the agent handles errors and avoids repetitive logic.
When the agent is failing to find a command that you know works, use Ctrl+R to search your own shell history in the terminal. You can copy the exact command that worked for you and paste it into the prompt for the agent. This bridges the gap between your knowledge of your local environment and the agent's general knowledge. If you find a bug in how the agent is behaving, use the /bug command to report it. Providing feedback helps the developers improve the tool and reduce the frequency of loops for everyone in the community.
Delegate tasks to subagents
For very large problems, the agent can become overwhelmed, which often leads to looping. You can break a big job into smaller, more manageable parts by using subagents. These are defined in markdown files within the .claude/agents directory. A subagent has a specific role and a limited scope. When the main agent encounters a difficult part of the project, it can delegate that task to a subagent. This keeps the main conversation context clean and focused on the high-level architecture.
A subagent with a narrow focus is much less likely to get stuck in a loop because it has fewer distractions. It only looks at the files and tools it needs for its specific job. You can manage these subagents using the /agents command. If a subagent starts to loop, you can terminate it without losing the progress made by the main agent. This modular approach to AI coding makes your workflow more robust and easier to debug when things go wrong. It is a more professional way to handle complex software engineering tasks.
Questions people ask
How do I stop a session without losing my work?
You can press Ctrl+C to quit the terminal or use the Escape key to stop a running tool. Any changes the agent made to your files using the Write or Edit tools stay on your disk. You can resume exactly where you left off by typing claude --continue in your terminal.
Can I limit how much money a looping agent spends?
Use the /cost and /usage commands to see how much you have spent in a session. To prevent high costs, press Shift+Tab to enter plan mode, which stops the agent from running tools without your approval. You can also use /compact to keep the context window small and cheaper to process.
Why does the agent keep repeating the same wrong file path?
This happens when the agent makes a wrong assumption about your repository structure. You should correct it by providing the right path in your prompt or by updating the CLAUDE.md file with the correct directory layout. You can also use the /add-dir command to make sure the agent has indexed the specific folders it needs to see.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.