OpenAI Codex CLI Agent Loop Technical Overview

OpenAI has detailed the internal architecture of the Codex CLI agent loop, the core orchestration logic that manages interactions between the user, the LLM, and local software tools. This system is designed to produce reliable software changes by iteratively executing tool calls and managing a growing conversation context to maintain performance and stability.

The Agent Loop Architecture

The agent loop is the central mechanism that orchestrates the flow of information between the user and the model. A single "turn" in a conversation consists of multiple iterations of inference and tool execution until a final state is reached.

The Iterative Process

  1. Input and Prompting: The agent takes user input and prepares a textual prompt for the model.
  2. Inference: The prompt is tokenized and sent to the model to generate a response.
  3. Decision Point: The model either produces a final assistant message (terminating the turn) or requests a tool call (e.g., executing a shell command like ls).
  4. Execution and Feedback: If a tool is called, the agent executes the command, appends the output to the prompt, and re-queries the model.

This cycle repeats until the model emits an assistant message, signaling that the work is complete and control should return to the user.

Model Inference and Prompt Construction

Codex CLI utilizes the Responses API to drive its agent loop. Depending on the configuration, it connects to various endpoints, including ChatGPT login, OpenAI hosted models via API keys, or local instances using gpt-oss with Ollama or LM Studio.

Building the Initial Prompt

Rather than sending a verbatim prompt, Codex sends a JSON payload containing specific input types. The Responses API server then structures these into a prompt based on roles with the following priority (highest to lowest): system, developer, user, and assistant.

Key components of the initial prompt include:

  • Instructions: System or developer messages inserted into the context.
  • Tools: A schema-defined list of tools, including Codex-provided shell tools, Responses API tools, and user-provided tools via MCP (Model Context Protocol) servers.
  • Input: Aggregated text, images, or files. This includes developer instructions from config.toml and user instructions sourced from AGENTS.md or AGENTS.override.md files found in the project root or $CODEX_HOME.

Handling Conversation Turns

Each turn is processed as a Server-Sent Events (SSE) stream. When a model produces reasoning or function calls, these are appended to the input field for subsequent requests. To optimize performance, Codex ensures that the old prompt remains an exact prefix of the new prompt, which is critical for enabling prompt caching.

Performance and Context Management

As conversations grow, the prompt length increases, potentially exhausting the model's context window and increasing latency. Codex employs two primary strategies to mitigate this: prompt caching and conversation compaction.

Prompt Caching

To avoid the quadratic cost of sending ever-increasing JSON payloads, Codex relies on prompt caching. Cache hits occur only for exact prefix matches. To maintain these hits, Codex avoids modifying earlier messages in the conversation. Instead, it appends new messages to reflect changes:

  • Configuration Changes: Changes to sandbox configuration or approval modes are added as new role=developer messages.
  • Environment Changes: Changes to the current working directory are added as new role=user messages.

Failure to maintain a consistent order of tools (such as in early MCP tool implementations) can result in cache misses and degraded performance.

Context Window Compaction

When the number of tokens exceeds the auto_compact_limit, Codex uses the /responses/compact endpoint of the Responses API. This process replaces the extensive conversation history with a smaller, representative list of items. This includes a special type=compaction item containing encrypted_content that preserves the model's latent understanding of the conversation without requiring the full token history.

Sources