The Codex Loop: How the Agent Thinks

What Makes Codex Different

Most AI coding tools are autocomplete at scale — smarter, faster, better context, but fundamentally still a single input-output exchange. You type something, the model responds, you decide what to do with the response.

OpenAI Codex is structured differently. It is an agent — a system that takes a task description, then independently plans, executes, and evaluates its own work across multiple steps until it decides the task is complete.

That distinction is not a marketing claim. It changes what you can ask it to do, how you write the task, and how you reason about what it will touch in your codebase.

The Four-Phase Loop

Every Codex run, from the simplest function fix to a full feature implementation, passes through the same four phases repeatedly:

Perceive. The agent reads the repository. It does not read everything — it reads what is relevant to the current state of the task. After the first iteration this includes files it has already modified, test output from the last run, and any error messages from the previous action. The Perceive phase is how the agent knows where it is in the task.

Reason. The model plans what to do next. This is the "thinking" step — it takes the perceived state and produces a plan for the next action. In practice this is often implicit: the model encodes its reasoning in the action it produces rather than narrating it explicitly. But when you enable verbose output or reasoning traces, this step becomes visible as the model's internal chain of thought.

Act. The agent executes the plan. In Codex, an action is one of: editing a file, creating a file, running a shell command (like a test suite or a build), reading additional files it identifies as relevant, or calling a tool. The action changes the state of the repository. That changed state is what gets fed back into the loop.

Observe. The agent reads the result of its action. A file edit produces a diff. A test run produces pass/fail output and failure messages. A shell command produces stdout and an exit code. The agent processes these observations and uses them as the primary input to the next Perceive phase.

Then it repeats. Perceive the updated state. Reason about what remains. Act on the next piece of work. Observe the result. Back to Perceive.

The loop runs until one of two things happens: the model determines the task is complete and emits a done signal, or the run hits its maximum iteration ceiling and terminates with whatever partial state it has reached.

Single-Turn vs Agentic: The Core Divide

A single-turn LLM call is appropriate when you know exactly what input to send and you need exactly one response. Summarize this document. Answer this question. Generate a function signature. These are fixed-shape tasks: one input, one output, done.

An agentic run is appropriate when the task requires the model to make decisions that depend on what it discovers along the way. Fix all the failing tests in this module. Implement the user authentication feature from this spec. Add error handling to the endpoints that are missing it.

The divide is not about complexity alone. It is about whether the model needs to observe its own outputs to make the next decision. A simple task can be agentic; a complex task can be single-turn. The question is: does the next step depend on the result of the last?

How State Accumulates

One of the least-discussed properties of the agent loop is that state accumulates across iterations. By the fourth iteration, the model's Perceive phase is reading a repository that is meaningfully different from what it saw in iteration one. Files have been modified. Tests have passed. The error messages from the previous run give it new information about what went wrong.

This is why the loop produces results that feel qualitatively different from a long single prompt. A single prompt asks the model to reason about a hypothetical sequence of changes. The loop asks it to reason about what just happened. The difference in grounding is significant for reliability on complex tasks.

Production knowledge systems use this same pattern. A memory system that maintains a knowledge base perceives new content, reasons about how it relates to existing chunks, acts to index it, and then observes the embedding distances before deciding whether it needs to refine the chunking strategy. The loop runs until the new content is indexed with high retrieval confidence. If you want to see a real production agent loop in use, the detailed architecture is documented at jeremyknox.ai.

The Max-Iterations Safety Ceiling

Every agent loop needs a maximum iteration count — a hard ceiling that terminates the run even if the model has not emitted a done signal. Without this ceiling, a malformed task or an unexpected file structure can produce an infinite loop.

This is a conceptual property of any agent loop, not necessarily a single --max-iterations CLI flag — so do not go hunting for one. In the Codex CLI the ceiling is managed for you as part of the session; when you build an agent loop directly against the API (the Responses API lessons later in this track), the iteration ceiling is a counter you write into your own loop. The principle is the same at both levels: an autonomous loop must have a bound.

In practice, most tasks complete in three to twelve iterations. If a run is approaching its iteration ceiling without completing, it typically means one of three things: the task was underspecified (the agent does not know when it is done), the task requires changes the agent cannot make with the tools it has available, or there is a bug in the environment (a test that always fails, a file that cannot be written).

When the ceiling is hit, you get back the partial state — whatever changes the agent made up to that point. Inspect it. The partial result usually tells you which of the three failure modes you hit.

When to Use Each Pattern

Use a single-turn call when:

• You need a fast response and the task is unambiguous
• The task has a single correct action (generate this function, explain this error)
• Latency is a constraint (agentic runs are 3-20x slower on wall-clock time)

Use an agentic Codex run when:

• The task spans multiple files or requires multiple edits
• The right next step depends on test output or error messages
• You want the agent to verify its own work (run the tests, check if they pass)
• The task is too long to fully specify in a single prompt

The practical heuristic: if you would describe the task as "go fix the thing" rather than "generate this specific output," you want the agentic loop.