Claude Code agent loop: 3 causes and the fix

Claude Code loops on the same change for one of three reasons, and each has a different fix. Auto-compact wiped the details, so the agent re-reads and re-edits the same files. A command keeps failing and the agent reruns it without changing anything. Or the task is too vague to ever finish. The fixes, in order, are /clear or a manual /compact, an interrupt that forces a rethink, and a smaller scoped instruction.

You need nothing installed beyond Claude Code itself. Most of this is reading the screen, then typing one command. The whole reset takes about five minutes once you know which cause you are looking at.

How to tell you are in a loop

A loop is the same file edited or the same command run more than twice with no new information between attempts. The agent is not making progress, it is repeating itself.

Watch for the agent re-reading a file it already read, then proposing an edit that looks like the last one. Watch for the same shell command running again with identical output. If two attempts in a row add nothing new, you are in a loop, not in slow progress.

Cause one: auto-compact erased the state the agent needs

Auto-compact fires near 95 percent of the 200K context window. After the system prompt, MCP tool schemas, and your CLAUDE.md, that leaves roughly 100K to 140K usable tokens for the actual work. When the window fills, Claude Code summarizes the conversation and starts fresh from that summary.

The summary is lossy. It drops line numbers, exact function names, and the precise diffs the agent was working from. So the agent re-reads the files to recover what it lost, which refills the window, which triggers another compaction. One compaction often leads to three to five more in a row. The agent keeps re-editing the same files because it keeps forgetting it already did.

The fix is to give the agent a clean window. Run /clear to wipe the conversation and start over, then re-state the task in one message with the file paths and the current failure. If you want to keep some history, run a manual /compact with explicit preserve instructions, naming the files and the test that is failing. Your CLAUDE.md reloads from disk after every compact, so put the durable preserve instructions there rather than retyping them.

Run /context to see the usage breakdown before auto-compact fires. Acting at 80 percent beats reacting at 95. While you are there, disable any MCP servers you are not using in this session. Tool search now defers most MCP schemas until the agent needs them, so only the tool names load up front, but unused servers still cost context and their tool outputs add up once the agent calls them.

Cause two: a command keeps failing and the agent reruns it unchanged

Claude Code can rerun an identical failing command seven or more times without changing it. The agent does not always register the error output before it retries, so it fires the same broken command again, reads the same failure, and fires it once more. This was reported on CLI 2.1.12 and closed as not planned, so the workaround is manual.

The fix is to interrupt. Press Escape to stop the agent mid-run. Then tell it plainly: stop, read the last error in full, and propose a different command before running anything. The point is to break the retry reflex and force a read of the error it skipped.

Be specific about what changed. "The last command failed with ENOENT, the path is wrong, find the correct one first" gives the agent something to act on. "Try again" sends it straight back into the loop.

Cause three: the task is too vague to ever finish

A loop with no error at all usually means the task is underspecified. The agent has no clear definition of done, so it keeps reworking the same code looking for a finish line that was never drawn.

The fix is to shrink the scope. Replace "make the auth flow work" with one concrete step: "add a redirect to /login when session is null in middleware.ts." A task the agent can verify as done is a task it can stop working on.

When you cannot tell why it is stuck, force a decomposition. Tell the agent to list what it has already tried, then propose three different approaches and wait for you to pick one. This pulls it out of the rework loop and back into planning, where the real problem usually surfaces.

The five-minute reset when you cannot tell which cause it is

When the cause is not obvious, run the reset in order and stop as soon as the loop breaks.

1. Press Escape to halt the current run.
2. Run /context. If usage is near the top, the cause is compaction. Run /clear.
3. Re-state the task in one message: the file paths, the goal, and the current failure if there is one.
4. If a command was failing, name the exact error and tell the agent to read it before retrying.
5. If there was no error, cut the task to one verifiable step and run only that.

Most loops break at step 2 or step 3. The window was full or the agent had lost the thread, and a clean restart with the paths spelled out is enough. If it loops again on the same step after a clean window, the task is the problem, not the context. Cut it smaller and run the one step.