Skip to main content
Codex CLI is built around three core primitives that structure how you interact with the AI agent. Understanding these concepts will help you work more effectively with Codex.

​
Architecture

Codex uses a conversation-based model where each interaction is structured into distinct units:

Threads

Conversations between you and the agent

Turns

Individual exchanges within a conversation

Items

Atomic units of input and output

​
Threads

A thread represents a complete conversation between you and the Codex agent. Each thread:
  • Contains a history of all interactions (turns)
  • Maintains context across multiple exchanges
  • Persists to disk as a JSONL rollout file
  • Has its own configuration (model, working directory, sandbox settings)
Threads are identified by a unique ID (e.g., thr_123) and can be:
  • Started fresh with codex or thread/start
  • Resumed from disk with codex resume or thread/resume
  • Forked into new branches with thread/fork
  • Archived when no longer needed

​
Thread lifecycle

​
Turns

A turn represents one round of interaction, typically:
  1. You provide input (message, image, skill invocation)
  2. The agent processes your request
  3. The agent responds and executes actions
Each turn has a status:
  • inProgress - Currently executing
  • completed - Finished successfully
  • interrupted - Cancelled by user
  • failed - Encountered an error
Turns are identified by IDs like turn_456 and can be interrupted mid-execution using turn/interrupt.

​
Items

Items are the atomic units that make up a turn. They represent both inputs and outputs:

​
Input items

  • userMessage - Text or images you provide
  • skill - Skill invocations (e.g., $skill-creator)
  • mention - App invocations

​
Output items

  • agentMessage - Text responses from the agent
  • reasoning - Internal reasoning steps (for supported models)
  • plan - High-level plan for multi-step tasks
  • commandExecution - Shell commands executed in the sandbox
  • fileChange - File modifications (edits, creates, deletes)
  • mcpToolCall - MCP (Model Context Protocol) tool invocations
  • webSearch - Web search queries and results
  • imageView - Image viewing operations

​
Item lifecycle

Every item follows a consistent lifecycle:
1

Item started

The item/started event is emitted with initial metadata
2

Streaming updates

Item-specific delta events stream incremental progress (e.g., item/agentMessage/delta)
3

Item completed

The item/completed event provides the final, authoritative state

​
Execution modes

Codex supports two primary execution modes:

Interactive mode

Full TUI with rich display, history, and navigation

Non-interactive mode

Headless execution for automation and CI/CD

​
Interactive mode

Launched with the codex command, interactive mode provides:
  • Real-time terminal user interface (TUI)
  • Streaming output as the agent works
  • Keyboard shortcuts for navigation and control
  • Visual feedback for approvals and errors
Best for: Development, debugging, exploratory tasks

​
Non-interactive mode

Launched with codex exec or codex review, non-interactive mode provides:
  • Programmatic execution without a TUI
  • JSONL event streaming for parsing
  • Exit codes for automation
  • Structured output formats
Best for: CI/CD pipelines, scripts, automated workflows

​
Security model

Codex implements multiple security layers:

Sandboxing

Platform-specific filesystem and network isolation

Approvals

User control over sensitive operations

​
Sandboxing

All commands run in a sandbox by default, using platform-specific technologies:
  • Linux: Landlock + seccomp (or Bubblewrap)
  • macOS: Seatbelt (App Sandbox)
  • Windows: Restricted tokens + job objects
Sandbox modes:
  • read-only - Only file reads permitted
  • workspace-write - Writes allowed in working directory
  • danger-full-access - No sandbox restrictions

​
Approvals

The approval system controls when human oversight is required:
  • never - Auto-approve all operations
  • on-request - Approve when sandbox escalation needed
  • unless-trusted - Always approve unless trusted by policy
  • on-failure - Only approve after sandbox failures

​
Data persistence

Codex stores data in your Codex home directory (typically ~/.codex/):
  • Sessions (sessions/) - Active thread rollouts
  • Archived (sessions_archived/) - Archived conversations
  • Config (config.toml) - User configuration
  • Skills (skills/) - Custom skills and tools
  • Cache (cache/) - Temporary data and indexes
Thread data is stored as JSONL (JSON Lines) for human readability and easy processing with standard tools.

​
Next steps

Interactive mode

Learn keyboard shortcuts and TUI features

Non-interactive mode

Integrate Codex into your automation

Sandboxing

Understand the security model

Approvals

Configure approval policies