Try free

Last updated 13 October 2026

Break a linter error loop in Claude

The agent enters a circular edit pattern

You are watching the terminal window as Claude Code works through a task. It uses the Edit tool to modify a source file in your repository. Immediately after the edit, it uses the Bash tool to run your project's linting command. The linter returns a specific error. The agent reads this error, apologizes for the mistake, and uses the Edit tool again to resolve it. However, this second fix undoes the logic of the first fix or introduces a new violation that the previous version had solved. This is a circular set of edits. It is a common frustration when using an agent that has a narrow focus on the immediate tool output rather than the broader project state. You see the same lines of code changing back and forth while your session history grows longer and more complex.

This loop often happens because the agent is trying to satisfy two conflicting rules. One rule might be enforced by the linter, such as a preference for certain import styles, while another rule might be an implicit coding standard the agent is trying to follow based on the surrounding code. Because the agent processes each tool output as a new prompt, it can lose sight of the fact that it just tried the exact same change two minutes ago. If you do not intervene, the agent will continue this cycle until it hits a tool use limit or you manually stop the process. This behavior wastes time and increases the cost of your session without making any progress on the actual task.

Interrupt the execution and roll back history

The moment you recognize a repeating pattern of edits and linting failures, you must stop the agent. Press the Escape key once to interrupt whatever tool the agent is currently running. This halts the loop and prevents further automated edits. If the agent has already performed several rounds of the same mistake, you need to clean up the conversation history. Pressing the Escape key twice will open a menu that allows you to see earlier messages in the session. You can scroll back through the exchange to a point before the loop began. Selecting an earlier message effectively rewinds the state of the conversation, preventing the agent from being influenced by its recent failed attempts.

Rolling back is better than simply telling the agent to stop looping. When the agent sees its own failures in the context window, it often tries to reason about why those failures happened, which can lead to even more convoluted logic. By using the double Escape shortcut, you remove those failures from the active context. If the situation is particularly messy, you can use the /clear command to wipe the session entirely while staying in the same directory. This is useful if the loop has filled the context window to the point where the agent is becoming slow or confused. You can then start fresh with a more specific prompt that mentions the linting conflict.

Transition to plan mode for better reasoning

Claude Code operates in different permission modes that change how it interacts with your files. If you are stuck in a loop, you should move away from the acceptEdits or bypassPermissions modes. Press Shift+Tab to cycle through the modes until you reach the plan mode. In this mode, the agent cannot execute tools like Edit or Write without your explicit approval for each step. Instead, it must describe the plan it intends to follow. This forces the agent to think through the entire set of changes before it touches a single line of code. You can read the proposed plan to see if it is about to repeat the same circular logic that caused the loop.

While in plan mode, you can provide feedback on the proposed steps. If the agent says it will change a line to satisfy a linting rule, you can remind it that doing so will break another rule it encountered previously. This interactive feedback loop is much more efficient than letting the agent trial-and-error its way through your codebase. Once you and the agent have agreed on a logical path that satisfies all constraints, you can switch back to default or acceptEdits mode to let it carry out the work. This shift in permission level moves the problem from the execution phase back to the planning phase, where it belongs.

Codify linting rules in the project instructions

The most effective way to prevent future loops is to update the project instructions in the CLAUDE.md file. This file sits in the root of your repository and acts as a persistent guide for the agent. Open this file and add a specific section for linting and code style. Describe the exact rules that are causing the conflict. For example, if your project uses a specific configuration for a tool like ESLint or Prettier that the agent keeps trying to override, document it here. You should include the actual Bash commands the agent should use to verify its work. When the agent starts a session, it reads this file and uses the instructions to guide its tool use.

If the linting problem is specific to only one part of your project, you can create a CLAUDE.md file in a subdirectory. The instructions in a subdirectory apply specifically to that part of the file tree. This is helpful for large repositories where different modules might have different build systems or linting requirements. You can also use ~/.claude/CLAUDE.md for global instructions that you want the agent to follow across every project on your machine. By putting the rules in writing, you reduce the chances of the agent guessing incorrectly and falling into a loop of trial-and-error edits. This turns a recurring problem into a one-time configuration task.

Reduce context noise with compaction and clearing

A long session filled with linter errors and failed edits creates a lot of noise in the context window. As the context fills up, the agent may lose track of the original goal or become fixated on the most recent errors. You can use the /compact command to handle this. This command summarizes the conversation so far, keeping the essential information while removing the repetitive tool outputs and error messages. This frees up space in the context window and allows the agent to focus on the current state of the code rather than its previous mistakes. It is a good practice to run /compact after you have successfully broken a loop but want to continue with the same task.

Sometimes, the /compact command is not enough to clear the confusion. If the agent continues to struggle, use /clear to start the session over. This does not delete your files, but it does wipe the conversation history. You can then use the /memory command to see if there are any persistent notes you want the agent to keep in mind, or simply provide a new, clearer prompt. Starting over with a clean slate often leads to a faster solution than trying to fix a corrupted session. You can also use /cost to see how much has been spent on the current session, which can help you decide if it is worth continuing or if you should start fresh to save tokens.

Monitor multiple sessions via the terminal wall

When you are managing several complex tasks at once, a linter loop in one terminal can go unnoticed while you work in another. This is where adhdTerminal provides a significant advantage. It organizes your Claude Code sessions into a wall of tiles on your macOS or Windows desktop. Each tile represents a separate session with its own name and color. You can see the status of every session at a glance. If a tile shows that it is consistently working without moving to a waiting or idle state, it might be stuck in a loop. You can quickly check the last few exchanges of the conversation directly on the tile without having to switch your entire focus to that terminal.

The wall also syncs to a free iPhone app over an end to end encrypted link. This allows you to monitor the progress of long-running tasks even when you step away from your computer. If you see a session enter a loop while you are away, you can use the app to send a prompt to the agent or tell it what the next task should be. This level of visibility ensures that you do not leave an agent spinning in a circular edit pattern for hours. By seeing all your active sessions side by side, you can identify patterns across different projects and intervene before a simple linting error becomes an expensive distraction.

Use search tools to find conflicting configurations

Loops often occur because the agent is unaware of a configuration file hidden elsewhere in the project. You can guide the agent to find these files using the Glob and Grep tools. Ask the agent to use Glob to find any files that might contain linting rules, such as those ending in .json, .yaml, or .rc. Once the files are identified, use the Grep tool to search for specific rules that match the linter error the agent is seeing. This manual investigation helps the agent understand why the linter is rejecting its changes. Instead of guessing how to fix the code, the agent can see the actual rule it is violating.

After finding the relevant configuration files, have the agent use the Read tool to examine their contents. If the linting rule itself is incorrect or outdated, the agent can use the Edit tool to update the configuration file instead of the source code. This is often the correct way to break a loop. If the agent is trying to fix code that is actually correct according to your team's standards, but the linter is misconfigured, changing the linter settings is the only logical solution. By directing the agent to look at the project's meta-files, you give it the context it needs to make an informed decision rather than a reactive one.

Delegate the fix to a specialized subagent

If a specific linting issue is proving too difficult for the main session, you can delegate it to a subagent. Subagents are defined as markdown files in the .claude/agents directory. You can create a specialized agent with a prompt that focuses entirely on code quality and linting. Use the /agents command to see your available subagents and start a new subagent session. By moving the problematic file and the linter error to a subagent, you give the task a fresh perspective. The subagent does not have the baggage of the main session's history, which makes it less likely to fall into the same circular reasoning.

When the subagent has found a valid fix that satisfies the linter, it can pass that information back to the main session. This modular approach to coding allows you to isolate difficult problems and solve them in a controlled environment. You can even create subagents for specific languages or frameworks within your project. For example, a subagent dedicated to TypeScript configuration could handle complex type-related linting loops that a general-purpose agent might struggle with. This keeps your main session focused on the high-level logic while specialized tools handle the tedious details of syntax and style enforcement.

Questions people ask

How can I see how much money a linter loop has cost me?

You can use the /cost command inside any active session to see the total spend for that specific conversation. If you want a broader view of your usage across all sessions, the /usage command provides detailed information about your token consumption. This is helpful for determining if a specific agent behavior is becoming too expensive to justify.

Can I prevent the agent from automatically running the linter after every edit?

Yes, you can control tool permissions in the .claude/settings.json file. Under the permissions key, you can specify which tools require manual approval. If you find the agent is triggering a loop by running a specific Bash command too often, you can set that command to require your permission before it executes.

What should I do if the Escape key does not stop the loop?

If the interactive interface is unresponsive, you can use Ctrl+C to force the Claude Code process to quit entirely. After quitting, you can restart the session using the 'claude --continue' command to pick up where you left off, or 'claude --resume' to choose a specific point in your history. This is a reliable way to regain control when the agent is stuck in an intensive processing cycle.

Read next

More on when it goes wrong·All posts