All writing

Part 1 of AI Agents Explained

How AI Agents Actually Work: The Agent Loop, Explained

The model behind Claude Code never touches your files. Here's what does, step by step, and what it means when an agent gets something wrong.

I use Claude Code most days, and for a long time I had the wrong picture of what was going on when it worked. I'd watch it run my tests, open a file, change a line and run the tests again, and somewhere in my head the AI was doing all of that.

It isn't. The model behind Claude Code has never opened a file, and it can't. All it does is read text and write text back. Everything else is done by Claude Code itself, a fairly ordinary program sitting between you and the model.

Once you know which part does what, an agent that gets something wrong is a lot easier to figure out.

A model that can only write

Take a small job. Three tests are failing, and I type "The tests are failing. Fix it."

Claude Code doesn't just pass that sentence along. It sends the model a set of instructions first: its own, called the system prompt, and anything in my project's CLAUDE.md, a notes file it reads at the start of every session. Then comes my message, and with it a list of tools it's willing to use on the model's behalf: run a command, read a file, edit a file, and a few more. The model can't use any of them directly. What it can do is reply with a request, a small structured message that amounts to "please run npm test".

Claude Code runs the command and sends back what happened. Here's that first round, message by message:

The first round

The model reads the failures and asks for the next thing. It wants to see the code, then to change it. I've let Claude Code run my tests without asking, but edits still need my OK, so that's where I come in:

Reading the file, then asking me before the edit

Then it asks for the tests again. This time they pass, the model has nothing left to ask for, and it replies with plain text instead:

The tests pass, and the model answers

Fourteen messages for a one-line fix. That back and forth is what people mean by the agent loop, and the program running it, Claude Code here, is usually called the harness.

The harness

Most of what you think of as "the agent" lives in the harness. It decides which tools the model is offered, runs the ones it asks for and keeps the conversation. It's also the one asking you for permission. When Claude Code stops to ask whether it can edit a file, the model has already made its request. The harness is holding it until you answer, and the model can't skip that. The harness can also end a run early: you can stop it at any point (Escape, in Claude Code), and harnesses can be set to stop after a fixed number of rounds.

Codex and Cursor's agent mode are harnesses too. They offer different tools and handle permissions differently, but the loop underneath is the same, which is why the same habits work in all of them.

Every round starts from zero

The model keeps nothing between rounds. By the time Claude Code sends back the result of npm test, the model has no memory of asking for it, so Claude Code sends the entire conversation again: the instructions, my original message, every request and every result, from the top. On the next round it does the same, with one more exchange on the end. That's "The whole conversation so far" on every result in the pictures above.

Most of that repeated text is cached, so you aren't paying full price for it every time, but it still adds up. It's why long sessions get slower and more expensive, and once the conversation grows long enough, details buried in the middle get less attention, or older parts get summarised away.

It also means the model knows what's in that conversation and nothing else. If something about your project matters and it isn't in there, the model is guessing. That's what CLAUDE.md is for.

When a run goes wrong

Every round is the same three moves: the model asks for something, the harness carries it out, and the model reads what came back. A bad run nearly always went wrong at one of them, and the fix depends on which.

The model can ask for the wrong thing. It digs through the wrong files, or runs npm test in a project that uses pnpm vitest. The harness does exactly what it's told; the model is guessing, because what it needed isn't in the conversation. Sometimes that's a message vaguer than it felt when you typed it ("fix the bug" leaves it to guess which bug), and sometimes it's a fact about the project nobody wrote down.

Or the harness can fail to carry it out. A rule you've set blocks the command, the command times out, or the tool it wanted isn't switched on. The model gets an error back instead of a result and starts working around it, often badly. Here the fix is in the harness's settings, not in your wording.

Or the model can misread what came back. That's the one behind "Fixed!" followed by tests that still fail. The loop ends the moment the model replies with an answer instead of a request, and by default nothing checks that answer first. If it skims a long test output, or never runs the tests at all, it stops anyway. The same goes for a model that keeps changing one line back and forth: it's reading every result, but it doesn't know what passing is supposed to look like.

The quickest way to tell which is to scroll back through the run and find the first round that looks wrong. Everything after it is usually the agent building on that one mistake.

What I do differently now

Mostly, I tell it how to check its own work. "Fix it, then run the tests and make sure they pass" gets noticeably better results than "fix it", because now it has real evidence to stop on, and so do I. Anthropic recommends the same thing in its advice for Claude Code.

I keep a short CLAUDE.md in each project with the things it would otherwise guess: the test command, how to run the app, the folders it shouldn't touch. It's read at the start of every session, so I only have to write it down once.

I try to read permission prompts properly too, not just skim them. The prompt shows the exact command about to run, and that command is what will happen, whatever the model said it was trying to do.

And I start a fresh session for each new job. Every round drags the whole conversation along, so leftovers from the last task cost time and give the model more to get confused by.