Claude Code Is A State Machine
Claude Code is a machine that loops through model calls and tool results. It stops at one of a fixed list of endings. It reads what came back rather than the label on it. Hold that picture and the rest gets simpler.
Claude Code is a state machine wrapped around a model. The model call is one move inside it.
State-machine model
The model at the middle of this has one strange problem. The moment it looks away, it forgets everything. Every name, every file, every thing you agreed on.
So you keep a notebook. Before each step you read the whole notebook back to it. It does one small thing. You write down what happened, and you start over.
That loop, the notebook read out loud every turn, is the machine. It is a patient ritual that turns a forgetful model into something that finishes a job.
That swap changed how I build. The chatbot picture sends you hunting for better wording. The machine picture sends you auditing the parts around the model call. Those parts are where the failures live.
I drew this as a straight line at first: type, prompt, model, tools, answer, repeat. Watch the token below after a tool runs. It carries the result back into the model call and stays inside.
ways a pass says "go again"
ways a turn ends
01Two loops, not one
The outer loop runs the whole session. It keeps the running list of messages, what you allowed, and what you blocked. It saves all of that to disk and carries it into the next turn. This is the part that remembers.
The inner loop runs one go with the model. It writes the request, calls the model, and reads the words as they arrive. It runs any tools the model asked for and attaches the results. Then it reaches one verdict: go again, or stop.
So the unit of work is move, result, move, result, until the job is done. That is a small operating system built around one conversation. Toggle the picture below to see where the work moved.
02A conversation carries state
The notebook is never blank. It holds the running list of messages and the cost spent so far. It holds a timestamp for every file read, and a record of everything you refused. Someone chose each of those, and the rest gets thrown away.
Each note changes a decision. A tool result changes what the next step can assume. A refusal steers what the agent tries next. The file timestamp decides whether the agent edits that file at all.
One habit is easy to miss. Your message lands in the notebook before the model is ever called. If the power cuts out mid-answer, the session resumes from a clean spot. This state outlives the model call, which is what makes a long session survivable.
03Your input is routed before the model sees it
What you type does not go straight to the model. A router sorts it first, and each kind of input takes a different path.
- A rule you set blocks the line, or adds context, before it becomes a prompt.
- Slash commands run and answer without waking the model.
- A line that starts with an exclamation mark runs in your terminal and feeds the output back.
- Naming an agent hands the whole job to that agent.
- Pasted images and attached files each take their own path.
Send each input through the router below and watch it land. Everything else stops short, and plain text is the one path that reaches the model.
The front door
You type to Claude. The router reads the line first and decides what kind of thing it is. That decision happens before any prompt exists.
04One pass of the inner loop
One pass runs the same chores every time. Write the request. Trim the prompt if the window is too full. Call the model. Read the answer as it streams in. Run any tools it asked for and attach the results.
The loop keeps a small scratchpad while it works. It tracks how many times it retried, whether it already trimmed a long prompt, and how deep it is. The last move of every pass is the verdict.
05The done signal is a claim, not a verdict
When the model finishes, it reports whether it meant to call a tool. The loop reads the stream itself and decides from what arrived. That check produces the verdict.
You add that check after reality bites you once. Trust the stream over the label. That instinct is most of the distance between a working agent and a demo.
06Tool results are moves, not answers
When the model asks for tools, the loop runs them and attaches the results as a new turn. A tool request and its result must stay paired. Wedge any other message between them and the conversation stops being valid, so the model refuses it.
So anything you type while a tool runs waits in a queue. It gets added after the results land. The pairing is one more piece of state that outlives the model call. The loop keeps it.
07Recovery is part of the loop, not an afterthought
Each repair in the loop is named after the break it fixes. Inject each break below and watch the turn survive it.
- When the stream breaks after a tool request, the loop discards the half-finished result and repairs the conversation.
- If the model hits its output limit, the loop retries, raises the limit, then gives up after a few tries.
- If the prompt grew too long mid-turn, the loop trims it and tries again.
- A blocked stop forces another pass.
- Old tool output gets trimmed before the loop continues.
- A hard turn limit stops a runaway.
Every pass ends in one verdict, and the list of verdicts is fixed. A tool request, a needed retry, a trimmed prompt, or a blocked stop all say go again. A finished answer, the turn limit, or an oversized prompt ends the turn. So does a refused stop, a model error, or your interruption.
The cost
This machine costs you something to reason about. From the outside, a model error, a blocked stop, and a retry look the same. So the system pays by naming every ending and recording why it stopped. In a loop this wide, that bookkeeping is what makes a strange result debuggable.
08Why this picture earns its keep
This is the picture I reach for when I build an agent or size one up. Start below the model choice, and run these six tests.
- Name what survives between your messages.
- Name which inputs never reach the model.
- Find the moment it saves your turn.
- Check how it keeps a tool request and its result paired.
- Break the answer mid-stream and see what the agent salvages.
- Make it show you every way a turn ends.
Those tests tell you more about an agent than any screenshot of a clever prompt. The agents I trust answer them with plain defensive machinery. That machinery earns the trust, and it never makes the demo.
Decision
Take any idea in the rest of this guide and check it against one thread: the named ending. Every piece ahead names the endings its part allows. Start with the next one. It names what fills the prompt before the model reads a word: the agent's worldview.