Try free

Last updated 13 October 2026

Stop Claude Code from looping commands

The recursive loop problem

Your terminal window is scrolling too fast to read. Claude Code has entered a cycle where it runs a Bash command, sees an error, and tries the exact same Bash command again. This often happens when the agent believes its previous attempt failed due to a transient error or when it misunderstands the output of a Read tool. It might be stuck trying to install a dependency that does not exist or searching for a file that is hidden by your .gitignore settings.

The loop consumes your context window and your budget. Every repeated exchange adds more tokens to the conversation. If you do not stop it, the agent will continue until it hits a rate limit or exhausts its internal reasoning steps. This behavior typically stems from a mismatch between the agent's internal model of the file system and the reality of your current directory structure. Identifying the loop early is the best way to save time and money.

Interrupting the tool execution

Immediate intervention is the first step. Press the Escape key once to interrupt the current process. This signals to the agent that it should stop the current tool execution. If the Bash tool is running a long process, Escape tells Claude Code to kill that process and wait for your input. This is the fastest way to save your budget when you see the agent repeating a mistake.

If a single Escape press does not work because the agent immediately starts a new loop, press Ctrl+C. This exits the claude session entirely and returns you to your system shell. When you use Ctrl+C, the session state is saved. You can return later by typing claude --continue or use the -c flag to pick up where you left off, though you will likely be at the same point where the loop started. Use this pause to think about why the agent is failing before you restart the process.

Clearing the mental state

Loops often fill the context window with redundant information. When you resume a session that was looping, use the /compact command. This summarizes the conversation so far and removes the redundant logs of failing Bash commands. It frees up space in the context window so the agent can think more clearly about why it was failing. Reducing the noise in the conversation history often helps the agent realize its previous strategy was flawed.

If the session is beyond saving, use the /clear command. This wipes the current conversation history in that folder but keeps the agent in the same environment. You can then start a fresh prompt with more specific constraints. Sometimes the agent gets stuck on a specific approach because the history is full of that approach. Starting fresh removes that bias and allows for a different technical path. Use /cost or /usage after a loop to see how much of your daily limit was consumed by the recursion.

Rewriting instructions in CLAUDE.md

The CLAUDE.md file is your primary tool for preventing loops before they start. If you notice the agent frequently fails on a specific type of task, like running tests or building a specific module, add explicit instructions to CLAUDE.md in your project root. Write down the exact Bash commands it should use and what it should do if those commands fail. For example, tell it to stop and ask for help if a specific error message appears twice.

You can also use a CLAUDE.md file in a subdirectory to provide more localized instructions. If the agent is looping while working on a frontend component, a CLAUDE.md file in the src/components folder can guide it with specific build instructions. The agent reads these files to understand the project's standards. Clearly defined error handling instructions in these files serve as a guardrail against recursive tool use. This is better than repeating yourself in every prompt.

Using planning modes to stop loops

Changing the permission mode can stop a loop from executing code without your oversight. Press Shift+Tab to cycle through the modes until you reach the plan mode. In plan mode, the agent describes what it wants to do instead of actually running the tools. This allows you to see if it intends to repeat a failing Bash command before it spends any money. You can then provide feedback to correct its course.

You can also manage specific tool permissions in your settings.json or settings.local.json files. Under the permissions key, you can set Bash or Write tools to require explicit approval. While this makes the agent less autonomous, it is a useful debugging step when you are working on a fragile part of the codebase where loops are likely. You can revert these settings once the logic is stable and the agent understands the environment.

Managing multiple agents with adhdTerminal

Monitoring multiple coding tasks makes it easy to miss when one agent has gone rogue. If you have several terminal windows open, a looping process in one can run for a long time before you notice the CPU usage or the mounting costs. This is where adhdTerminal becomes useful. It displays all your active Claude Code sessions as tiles on a single wall. Each tile shows whether the agent is working, waiting, or idle.

By looking at the wall, you can instantly see if a specific session has been working for an unusually long time. The tile shows the last few exchanges of the conversation, so you can spot a repeating Bash command without switching focus to that specific terminal window. If you see a tile flashing with repeated errors, you can jump in and press Escape to stop the loop. This high level view prevents a single recursive agent from wasting your resources while you are focused on a different part of the project.

Backtracking with history

If you need to go back to a point before the loop started, press the Escape key twice in rapid succession. This opens a history browser within the session that allows you to select a previous message. By selecting a point in time before the agent entered the recursive loop, you can effectively rewind the conversation. This is cleaner than /clear because you keep the useful parts of the work done earlier in the session.

You can also use the /resume command to pick a different starting point from your session history. If the current session is too cluttered with loop data, exit and run claude --resume to see a list of previous interactions. Picking a session from ten minutes ago might be more efficient than trying to fix a broken one. This approach allows you to abandon a hallucination loop and restart from a known good state. It is the most surgical way to handle recursion.

Questions people ask

How do I know if Claude Code is in a loop?

Look for the same Bash or Read command appearing multiple times with the same error output. The agent will usually offer a brief explanation of why it is trying again, but if the command is identical, it is likely stuck. You will also see your session cost in /cost rising quickly without any changes to your files.

Does the agent learn from loops automatically?

The agent tries to learn within the context of a single session, but its internal reasoning can sometimes get trapped. Using /compact helps it summarize the failure so it can try a different strategy. To ensure it learns for future sessions, you must record the correct behavior in your project CLAUDE.md file.

Can I limit the number of tool calls to prevent loops?

There is no specific setting to limit tool calls by number, but you can use the plan mode via Shift+Tab to manually approve every action. You can also use the bypassPermissions mode sparingly when you trust the logic, but for debugging loops, the plan or default modes are safer. Reviewing the agent's intent before it executes Bash commands is the best way to prevent recursion.

Read next

More on when it goes wrong·All posts