How Claude Code Works: Inside Its Simple Agent Loop

A recent academic study walked through the publicly available TypeScript source for Claude Code and described its architecture as 'a simple while-loop that calls the model, runs tools, and repeats.' That description is accurate, and it is also a useful starting point if you are trying to understand what AI coding agents actually do.

Most AI agent demos in 2026 are doing exactly that: looping over a model call, parsing tool requests out of the response, running them, and feeding the results back into the next turn. The interesting design choices sit on top of that loop - which tools you expose, how you manage context as the conversation grows, when you spawn parallel sub-agents, and where you stop to ask the user before doing something irreversible.

Strip away the UX and the integrations and you get something like this:

1. Send the conversation so far - system prompt, user message, prior tool calls and results - to the model.
2. Receive a response. The response either talks to the user directly or asks to use one or more tools.
3. If tools were requested, run them. Tools here mean things like 'read this file', 'run this shell command', 'edit this file', 'search the codebase'.
4. Take the tool results, append them to the conversation, and go back to step 1.

That's it. The loop terminates when the model stops asking for tools - usually because it has answered the user's question or completed the task. There is no separate planner module, no explicit goal tracker, no state machine. The state of the work lives entirely in the conversation transcript.

It sounds primitive, and in a sense it is. But this design has held up across an enormous range of coding tasks - bug fixes, refactors, new feature work, debugging across multi-file codebases - and the simplicity is doing real work. Every additional layer you add (a planner, a memory module, a re-ranker) is a new place for mistakes to compound. The loop wins because the model is doing most of the lifting and a small surrounding scaffold is enough.

The same study compared Claude Code to OpenClaw, a different agent built on the same underlying loop but deployed in a different context. The two implementations end up making different choices on the same recurring design questions. That comparison is what makes the loop interesting: it is a shape, not a recipe.

Some of the design questions every agent builder ends up answering:

• Tool surface area. Should the agent have one general 'run a shell command' tool, or many narrow tools like 'read file', 'edit file', 'list files'? Narrow tools are easier for the model to use correctly but the surface grows quickly.
• Context management. Conversations grow. At some point the prompt exceeds the model's context window. Do you summarise old turns, drop them, or push them into an external memory the model can search?
• Sub-agents. When a task gets large, you can spawn a fresh sub-agent with its own context and have it report back. This trades coordination overhead for cleaner context, and the decision depends a lot on how chatty the parent loop needs to be.
• Human checkpoints. Some actions are reversible (a file edit you can roll back) and some are not (a git push, an API call that charges money, a DELETE statement). The agent has to know which is which, and the design has to make pausing for human input the default for the irreversible ones.

Two agents using the same loop can answer these questions differently and end up feeling like completely different products.

The study identified six places where today's agent architectures still feel like research questions rather than settled engineering. They are worth knowing about whether you are building an agent or evaluating one as a user:

1. Bounding memory. Long-running agents accumulate context faster than the model can carry. There is no settled answer for what to keep, what to summarise, and what to throw away.
2. Spawning sub-agents. When to fan out work to parallel agents is largely a judgement call today. Agents tend to either spawn too little (and run out of context) or too much (and lose coherence).
3. Pausing for human input. Knowing when to interrupt the user for confirmation is hard. Too many confirmations and the agent is useless; too few and it does irreversible things you did not authorise.
4. Validating tool output. Tools can fail in subtle ways - a shell command 'succeeds' with empty output, an API returns a 200 with an error in the body. The agent has to spot these and react.
5. Handling long-running tasks. Some tasks take minutes; some take hours. The loop needs to checkpoint progress, survive crashes, and resume cleanly.
6. Staying honest. Models can hallucinate that they ran a tool, or claim to have finished work they have not done. The architecture has to keep the loop grounded in what actually happened.

None of these have clean answers in 2026, which is a hopeful sign for anyone working in the space. The interesting work is still ahead.

If you are choosing an AI coding agent today, the questions worth asking are less about whether it has a 'planner' or a 'memory system' and more about how it handles the six open directions above. Specifically:

• Does it ask before doing irreversible things? Look for explicit confirmation steps before commits, pushes, deletions, and any kind of external API call that touches a real resource.
• Does it manage context well over long tasks, or does it get confused and start contradicting itself after 30 minutes?
• When it claims to have done something, can you trust the claim? Does it show you the tool calls it ran and the results it got back?
• If you stop it half-way, can you resume sensibly later?

Agents that handle these well feel reliable. Agents that don't feel impressive for the first ten minutes and infuriating after a week.

Claude Code's architecture is a useful case study because the loop is so simple. There is no magic - just a tight feedback cycle between the model and a small set of well-designed tools, with the scaffolding handling the things models still struggle with. The interesting differences between agents live in how they answer the same recurring questions about context, sub-agents, human approval, and honesty.

If you are building in this space, the takeaway is that the loop is not the hard part. The hard part is everything that sits around it.