Unrolling the Codex Agent Loop

Core Mechanism: Response API–Driven Closed-Loop Orchestration

Codex CLI does not merely invoke LLM APIs; it constructs a staged agent loop atop OpenAI’s Responses API—including prompt composition, tool selection, execution dispatch, response streaming, and stateful retry. This loop explicitly separates planning (LLM outputting a structured action plan) from acting (CLI tool execution), enabling fine-grained telemetry for token usage, latency, and tool errors at every step.

Key Component Integration

• Model Layer: Defaults to GPT-4-turbo (gpt-4-turbo-2024-04-09); supports runtime switching to Claude 3 Opus or local Llama 3-70B via Ollama. All requests are wrapped by the Responses API with enforced response_format={"type":"json_object"} for structured output.
• Tool Layer: Ships with built-in adapters for CLI tools including shell, curl, git, and python-exec. Each tool is registered as a ToolSpec, complete with JSON Schema-defined I/O contract, execute() method, and timeout control. Tool failures trigger fallback prompting with max_retries=2.
• Prompt Engineering: Uses a multi-turn system prompt template (specifying role, tool catalog, and output constraints). Prompt versioning is fixed in codex-prompt-v2.1.yaml, supporting per-command overrides.
• Performance Control: Achieves sub-800ms P95 latency via Responses API stream=true, max_tokens=1024, and temperature=0.2. Streaming chunks follow the SSE format data: {"id":"...","delta":{"role":"assistant","content":"..."}} for real-time CLI rendering.

Operational Constraints & Observability Design

• Maximum loop depth is capped at 8 to prevent infinite tool-call cycles. Token consumption per step is logged to codex_usage.jsonl, recording model, prompt_tokens, completion_tokens, tool_calls, and wall_time_ms.
• All traces are OpenTelemetry–compliant and exportable to Jaeger or Datadog. A CLI session auto-generates codex-trace-id-{timestamp}.log for deterministic debugging and replay.