Skip to content
TilloTech Docs

OpenAI: Codex agent loop

Source: Unrolling the Codex agent loop

Published: 23 January 2026.

Evidence type: implementation walkthrough of prompt construction, tool iteration, streaming, caching, and compaction.

Loop mechanics

The harness converts user input into a prompt, samples the model, executes any requested tool, appends the call and result, and samples again. This repeats until an assistant message returns control to the user. The real output may be filesystem changes; the final message is the termination signal, not the whole result.

A turn can contain hundreds of calls. Every call and result can enlarge the next request, making context management a harness responsibility.

Initial prompt assembly

The documented initial order is:

  1. model instructions, either configured by model_instructions_file or bundled for the model;
  2. tool schemas from Codex, the Responses API, and configured MCP servers;
  3. a developer message describing shell sandbox and approval policy;
  4. optional configured developer instructions;
  5. user-level and repository AGENTS.override.md/AGENTS.md instructions, plus skill discovery metadata, within a default 32 KiB project-document budget;
  6. a user message describing current working directory and shell; and
  7. the actual user request.

The Responses request separates:

  • model instructions;
  • available tool schemas;
  • input items including text, images, and files.

Codex then adds sandbox and approval instructions, optional developer configuration, layered user/repository instructions, skill discovery metadata, environment context such as working directory and shell, and finally the user message. Repository instructions are aggregated from global through root and working-directory scopes subject to a size limit, with more specific material later.

The shell sandbox described in the prompt applies only to the Codex-provided shell. MCP and other tools must enforce their own guardrails. This is a critical boundary: “the agent is sandboxed” is meaningless unless every tool’s boundary is specified.

Streaming and state growth

The article shows reasoning-summary, output-item, output-text, and completed SSE events. Completed reasoning and function-call items are appended to the next request with a function_call_output carrying the same call_id. That identifier—not textual adjacency—is the durable tool-result association.

The server streams typed events. The harness republishes UI deltas while also turning completed reasoning, function calls, and other items into input for the next inference. A tool result is correlated to its call ID. At the end of a turn, the assistant message and any next user message join the full accumulated state for the following request.

Prompt caching

Codex preserves the prior prompt as an exact prefix of the next request so the provider can reuse computation. Exact-prefix caching means static instructions, examples, images, and tool definitions should precede variable material. Changes to tool availability or order, model, sandbox, approvals, or working directory can invalidate the prefix.

OpenAI documents an actual ordering bug in early MCP integration that caused cache misses. Dynamic tool-list notifications are similarly risky. Where possible, Codex appends a new permission or environment item rather than modifying an earlier item.

Codex’s described implementation sends full stateless requests rather than using a prior-response identifier, partly to support Zero Data Retention. This increases transferred JSON but keeps provider state requirements simpler. Sampling cost dominates network cost, making cache hits more important than request byte size in this design.

Compaction

When a token threshold is exceeded, the harness replaces the accumulated input with a smaller representative item list. The evolved implementation uses a dedicated compaction endpoint and an opaque compaction item that preserves model state, then automatically compacts at a configured limit.

The earlier design required a manual /compact summarisation turn. The current design in the article calls /responses/compact and receives a replacement item list containing an opaque type=compaction item with encrypted content; Codex invokes it automatically after auto_compact_limit is exceeded.

The general lesson is that compaction must be part of loop architecture. It changes the prompt prefix and therefore the caching regime, and it must retain enough objective, evidence, and task state for work to continue safely.

Standards implications

  • Specify the exact instruction, tool, permission, environment, and user-data layers in any EOS-owned harness.
  • Persist structured calls, results, artifacts, and terminal states rather than relying on the final message.
  • Review and sandbox each tool independently.
  • Keep stable prompt prefixes deterministic and observe cache-hit rates.
  • Test compaction and resume as normal execution paths, including work that spans many tool calls and turns.