Why is my AI coding agent stuck in a loop?

An AI coding agent gets stuck in a loop when it cannot get the feedback it needs to make progress, when two of its constraints cannot both be satisfied, or when the check it is trying to pass gives different answers on different runs. In each case the agent keeps doing what usually works, edit and rerun, without any new information arriving, so the same edits come round again. A loop is different from a hard problem. On a hard problem each attempt fails in a new way and you learn something. In a loop the failures repeat, the diff swings back and forth, and the session grows longer and more expensive without moving. The fixes are to recognize the loop early, find which of the three causes is feeding it, set limits so the next one ends on its own, and know when to stop the session rather than nudge it. If the agent is making real progress but the tests still fail, see what to do when an agent can't pass the tests.

Signs you are in a loop

Loops are easy to miss while watching, because each step looks reasonable on its own. Look for these signals instead.

The same error text appears three or more times. Not a similar error: the same one, at the same line.

The diff oscillates. A change is made, reverted and made again. Comparing the working tree after each attempt shows it, and so does an agent announcing a different approach and then producing the first approach again.

The explanations get longer while the changes get smaller. The agent is reasoning in circles about a problem it cannot observe.

The edits spread. A one-file task touches a fifth file, each change compensating for the last one.

Time or usage rises with no change in the result. A session that has run twice as long as similar tasks without passing anything new is probably not about to succeed.

If you see two of these together, interrupt. Waiting rarely helps, and every extra round leaves more partial edits to unpick afterwards.

Three causes and how to tell them apart

Missing feedback. The agent is not seeing what you would see. The test output is truncated, the command it runs is not the one that fails, a build step serves a cached result, or the error happens in a process it cannot observe, such as a browser or a background worker. Check by running its exact command yourself and comparing the output with what it quoted. If they differ, fix the feedback before anything else.

Contradictory constraints. Two requirements cannot both hold: a type checker demands a field the tests forbid, a rule says never change the public API while the task needs a new parameter, or two instruction files disagree. The symptom is oscillation between two states, each satisfying one constraint. Read the two errors side by side; the contradiction is usually plain once they sit next to each other. A person has to choose which constraint gives way.

Flaky checks. The check passes and fails without code changes, so the agent learns from noise. Rerun it several times on an unchanged tree. If the result varies, stop treating it as a signal; flaky tests covers isolating it.

Retry, failure and time limits

The cheapest fix is a limit set before the session starts. Decide three numbers and write them into the task or the runner.

Attempt limit: how many times the same check may fail before the agent stops and reports. Two or three is usually enough for one failure point.

Time limit: a wall-clock ceiling for the task, set from how long similar work normally takes. A session past twice that is a candidate for stopping whatever it says about being close.

Usage limit: where your tool supports one, but be clear about what it promises. Claude Code documents a budget option for its print mode, but it works from a client-side cost estimate, can overshoot, and does not include totals from earlier sessions on resume. A soft limit still helps; just do not treat it as a hard ceiling. Spending limits for AI agents covers what a real ceiling needs.

When a limit is hit, the agent should stop and write down what it tried, not start a new approach. Limits are central to bounded agent runs, and they matter most when nobody is watching.

When to stop the session, and how to restart

Stop the session, not just the current attempt, when the context is full of failed tries. A long transcript of wrong approaches is itself part of the problem: the agent keeps rereading its earlier reasoning and is pulled back toward it. A fresh session with a short summary often solves in minutes what the long one could not.

Before restarting, do three things. Revert to a known state, usually the commit the task started from, unless a specific partial change is worth keeping. Write a short note: the goal, the exact failing command and its first error, the approaches that failed and why. Then fix whatever fed the loop: repair the feedback, resolve the contradiction, or quarantine the flaky check.

Start the new session with the note and a narrower task. If the same loop appears again with clean feedback and no contradiction, the problem is probably beyond what the task description gives the agent to work with. It needs a person to look at the design, not another round of retries, and the task should say so before anyone runs it again.

QUESTIONS

How do I tell a loop from an agent that is just slow?

Compare attempts, not elapsed time. A slow agent produces different errors or different diffs as it goes, and each failure narrows the problem. A looping agent produces the same error, or swaps between the same two versions of a change. If three consecutive attempts look alike, interrupt it, whatever the clock says.

Is a budget option in an agent CLI a hard spending cap?

Not necessarily. Claude Code's documented budget option for print mode works from a client-side cost estimate and can overshoot, and earlier sessions' totals are not included on resume. A real hard cap needs something that reserves the worst-case cost before each request is sent, such as a provider-side limit or a trusted gateway.

Should I restart the session or keep correcting the agent?

Restart when the transcript is mostly failed attempts. The agent rereads its own earlier reasoning and tends to return to it. Revert to a known state, write a short note with the goal, the failing command and what did not work, fix the cause of the loop, then start fresh with a narrower task.

RELATED GUIDES

• How to read BRAIN FLUID reports and provenance

RELATED HARNESS PAGES

• What to do when an AI agent can't get the tests to pass When an agent can't get tests passing: stop the retries, separate environment from code failures, check the test, shrink the task, record the blocker.
• Flaky tests and AI coding agents Flaky tests and AI coding agents: how nondeterministic checks cause false completions and false failures, and the retry and quarantine rules that help.
• Bounded autonomy: limits every unattended agent run needs Bounded autonomy: limits every unattended agent run needs, from an explicit task list to launch, retry, time, failure and spend limits.
• Can you put a hard spending cap on an AI coding agent? Client-side budget flags in agent CLIs are estimates that can overshoot. A hard cap needs a reservation before each request. Here are practical limits instead.
• When an autonomous agent run should stop and ask When an autonomous agent run should stop and ask: failed checks, missing approval, open blockers, impact obligations, out-of-scope writes or uncertain state.