# Codex Agent Loop

> Understand and apply how the Codex agent loop works, including request assembly (`instructions`, `tools`, `input`), thread/turn/item mental models, tool iteration, prompt growth, caching, compaction, and where `model_instructions_file` and `AGENTS.md` enter. Keep the local references for the durable conceptual model, but fetch current official docs via `openaiDeveloperDocs` for exact config, prompt-loading, and other evolving Codex behavior.

- Skill: `wisdom-in-a-nutshell/codex-agent-loop` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add wisdom-in-a-nutshell/codex-agent-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wisdom-in-a-nutshell/codex-agent-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: wisdom-in-a-nutshell (https://skillmd.com/u/wisdom-in-a-nutshell)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wisdom-in-a-nutshell/codex-agent-loop

---


# Codex Agent Loop

Use this skill when you need the durable mental model for how Codex actually runs: how the initial request is assembled, how inference and tool calls loop within a turn, how conversation state grows across turns, and where `model_instructions_file`, `AGENTS.md`, and local guidance enter.

## Read Order

1. Read `references/unrolling-the-codex-agent-loop.md` for the end-to-end model of threads, turns, items, and tool iteration.
2. Read `references/building-the-initial-prompt.md` for the first request, prompt item ordering, tool definitions, and SSE event flow.
3. Read `references/conversation-growth-and-performance.md` for prompt growth, exact-prefix caching, statelessness, `previous_response_id`, ZDR, and compaction.
4. Read `references/openai-codex-prompt-loading.md` only when exact `model_instructions_file`, `AGENTS.md`, or project config semantics matter.
5. Read `references/prompt-layering.md` only when deciding what belongs in the base prompt versus local guidance or mutable context.

## Core Model

- A `thread` is the durable conversation container.
- A `turn` begins with a new user request and may contain many inference and tool-call iterations before it ends.
- The Responses API request surface is structured as `instructions`, `tools`, and `input`; the server derives the actual prompt shape from those parts.
- Tool calls are part of the normal loop, and their outputs are appended back into later `input` items.
- Stable early prompt content matters because it affects both behavior and prompt caching efficiency.

## Use This Skill Well

- Start with the conceptual reference before reading the lower-level details.
- If the question is narrow, load only the specific reference that answers it.
- Keep the distinction between base `instructions`, later `input`, and appended tool outputs explicit.
- Preserve the blog's mental model: a turn is not a single model call, and the loop does not end until the assistant emits a final message for that turn.
- Use the embedded SVGs in the references when you want the original diagrams in context.
- Reach for exact docs via MCP when configuration or current product behavior matters.

## Reference Policy

1. Treat `references/unrolling-the-codex-agent-loop.md` as the main reusable explanation another agent should remember.
2. Treat `references/building-the-initial-prompt.md` and `references/conversation-growth-and-performance.md` as the detailed mechanics that preserve most of the blog's substance.
3. Fetch official docs via `openaiDeveloperDocs` before answering questions about exact current prompt loading, `AGENTS.md` discovery, fallback filenames, byte limits, config keys, or other evolving behavior.
4. Treat `references/openai-codex-prompt-loading.md` as a local helper summary of official guidance, not a replacement for checking current docs when precision matters.

## Fetch First For

- `model_instructions_file` and config-key semantics
- `AGENTS.md` discovery order, fallback filenames, and byte limits
- project-scoped `.codex/config.toml` behavior
- current Codex config reference details
- any question phrased as latest, current, official, exact, or up to date

## References

- `references/building-the-initial-prompt.md`
- `references/conversation-growth-and-performance.md`
- `references/unrolling-the-codex-agent-loop.md`
- `references/openai-codex-prompt-loading.md`
- `references/prompt-layering.md`