The Architecture Philosophy of Codex: Three Layers of Abstraction and the Design Wisdom of Human-AI Collaboration

All things have their root and their branches; all affairs have their end and their beginning. To know what comes first and what comes last is to be near the Way. — The Great Learning

The finest software architecture is like the learning of illustrious virtue: it must have its root and its branches, its proper order. Codex takes Session as its root (the ground of environment), Task as its trunk (the flow of intent), and Turn as its branches and leaves (the substance of interaction). Each fulfills its own role yet all form a harmonious whole, embodying a profound insight into the nature of human-AI collaboration: technology should serve the human mode of cognition, not force humans to adapt to the logic of machines.

Introduction: Beginning with Design Philosophy

When we examine the architecture of a complex system, what fascinates us most is not what it does, but why it does it that way. OpenAI’s Codex CLI project presents an exquisite piece of architectural design, building a powerful and flexible AI coding assistant around three core abstractions: Session, Task, and Turn.

Let us begin with a simple question: when a human and an AI collaborate on programming, what is the essence of that interaction?

This question leads us straight to the heart of Codex’s architecture. It is less a technical system than a carefully choreographed conversational framework, in which each component carries a specific interactional semantics.

The Philosophy of the Queue: Why the Submission Queue / Event Queue Pattern?

Before diving into Codex’s three core abstractions, let us first understand the foundational communication pattern it chooses. A comment in the code reveals a key design decision:

//! Uses a SQ (Submission Queue) / EQ (Event Queue) pattern to asynchronously communicate
//! between user and agent.

Why Not a Simple Request-Response Model?

Imagine you’re pair-programming with an experienced engineer. What kind of interaction pattern would you expect?

1. You state a need (“Help me refactor this function”)
2. They start working—but not silently
3. You can see progress (“Analyzing dependencies…”)
4. Sometimes they want your confirmation (“This change touches 5 files—continue?”)
5. The work can be interrupted (“Wait—I want to change direction”)

This is exactly why Codex chose the queue-pair pattern. Let us dig into that choice:

pub struct Codex {
    next_id: AtomicU64,
    tx_sub: Sender<Submission>,    // Submission queue: user → AI
    rx_event: Receiver<Event>,      // Event queue: AI → user
}

This bidirectional asynchronous communication pattern brings several key advantages:

1. Non-blocking: The user can send new instructions at any time without waiting for the current task to finish
2. Observability: Every action of the AI is streamed back to the user in real time via events
3. Interruptibility: Tasks can be gracefully interrupted and resumed
4. State decoupling: UI and core engine can evolve independently

But what is the deeper reason? This design reflects a profound understanding of the nature of human-AI interaction: human thought is nonlinear, interruptible, and feedback-hungry. The traditional request-response model assumes a simplified, mechanical interaction, whereas the queue-pair pattern acknowledges and embraces the complexity of real interaction.

Session: The Container of Conversation

What Is a Session?

If we regard human-AI pair programming as a conversation, then a Session is the contextual environment in which that conversation takes place.

pub(crate) struct Session {
    client: ModelClient,
    pub(crate) tx_event: Sender<Event>,
    ctrl_c: Arc<Notify>,

    // Working environment
    pub(crate) cwd: PathBuf,
    base_instructions: Option<String>,
    user_instructions: Option<String>,

    // Security policy
    pub(crate) approval_policy: AskForApproval,
    sandbox_policy: SandboxPolicy,

    // State management
    state: Mutex<State>,

    // ... more fields
}

The Significance of Session

Session is more than a data container; it embodies three important architectural principles:

1. Environment Encapsulation

Session encapsulates all the environmental information of a complete collaboration. It is like a carefully arranged studio in which every tool has its fixed place:

impl Session {
    fn resolve_path(&self, path: Option<String>) -> PathBuf {
        path.as_ref()
            .map(PathBuf::from)
            .map_or_else(|| self.cwd.clone(), |p| self.cwd.join(p))
    }
}

This seemingly simple method reveals a profound design philosophy: all path resolution is relative to the Session’s working directory. This guarantees the determinism and predictability of operations.

2. Security Boundary

Session defines the safety boundary of AI operations:

pub enum SandboxPolicy {
    DangerFullAccess,        // Full trust
    ReadOnly,                // Read-only access
    WorkspaceWrite {         // Restricted write
        writable_roots: Vec<PathBuf>,
        network_access: bool,
        // ...
    },
}

This layered security model reflects a key insight: trust is gradual, not binary. As with trust in human relationships, AI system permissions should also be earned incrementally.

3. State Isolation

Each Session maintains independent state:

struct State {
    approved_commands: HashSet<Vec<String>>,  // Cache of approved commands
    current_task: Option<AgentTask>,          // Currently executing task
    pending_approvals: HashMap<String, oneshot::Sender<ReviewDecision>>,
    pending_input: Vec<ResponseInputItem>,
    history: ConversationHistory,             // Conversation history
}

This state isolation is not a technical necessity but a conceptual clarity. Each Session is like an independent universe, with its own history, rules, and memories.

Why Is Session So Important?

Imagine a world without the Session abstraction. Every interaction would require re-establishing context, reconfiguring security policies, and reloading history. This is not only inefficient but also error-prone. Session is like a persistent workspace that remembers your preferences, your history, your trust level.

More importantly, Session embodies relational thinking. It does not treat the AI as a stateless tool, but as a collaborative partner with memory and context. This design philosophy deeply shapes the behavior of the entire system.

Task: The Executor of Intent

The Essence of Task

If Session is the stage, then Task is the drama performed upon it. Each Task represents the execution of a complete user intent. It is a state machine that continually negotiates between user intent and system capability until a goal is achieved or an insurmountable obstacle is met.

pub(crate) struct AgentTask {
    sess: Arc<Session>,
    sub_id: String,
    handle: AbortHandle,
}

impl AgentTask {
    fn spawn(sess: Arc<Session>, sub_id: String, input: Vec<InputItem>) -> Self {
        let handle =
            tokio::spawn(run_task(Arc::clone(&sess), sub_id.clone(), input)).abort_handle();
        Self {
            sess,
            sub_id,
            handle,
        }
    }
}

The Lifecycle Philosophy of Task

Task’s design embodies an important cognition: human intent is atomic, but its realization is iterative.

Let us understand this philosophy through the code:

async fn run_task(sess: Arc<Session>, sub_id: String, input: Vec<InputItem>) {
    // 1. Announce task start
    let event = Event {
        id: sub_id.clone(),
        msg: EventMsg::TaskStarted,
    };

    // 2. Record initial input
    sess.record_conversation_items(&[initial_input_for_turn.clone().into()])
        .await;

    // 3. Enter the iteration loop
    loop {
        // Fetch pending input
        let pending_input = sess.get_pending_input();

        // Build full conversation context
        let turn_input = sess.turn_input_with_history(pending_input);

        // Execute a Turn
        match run_turn(&sess, &mut turn_diff_tracker, sub_id.clone(), turn_input).await {
            Ok(turn_output) => {
                // Process output, decide whether to continue
                // ...
            }
            Err(e) => {
                // Error handling and retry logic
                // ...
            }
        }
    }
}

On each iteration, the system fetches pending input and combines it with the historical conversation context to build the complete input. It then executes a Turn, attempting to produce output. On success, the system decides based on the output whether to continue iterating; on failure, it enters the error-handling and retry logic. This design lets a task adapt dynamically during execution, accommodating changing input and context—a respect for the nonlinearity of human thought.

Why Can a Task Be Interrupted?

We frequently change our minds mid-execution, adjust direction, or abandon the current path entirely. Task’s interruptibility is not a technical feature but a respect for human cognitive patterns. It reminds me of the philosophical concept of “durée”: consciousness is not a series of discrete states but a continuous flow. Task’s design is precisely a technical realization of that flow.

impl AgentTask {
    fn abort(self) {
        if !self.handle.is_finished() {
            self.handle.abort();
            let event = Event {
                id: self.sub_id,
                msg: EventMsg::Error(ErrorEvent {
                    message: "Turn interrupted".to_string(),
                }),
            };
            // ...
        }
    }
}

Why Only One Task at a Time?

In the code we see the definition of current_task, which constrains a Session to at most one executing Task.

impl Session {
    pub fn set_task(&self, task: AgentTask) {
        let mut state = self.state.lock().unwrap();
        if let Some(current_task) = state.current_task.take() {
            current_task.abort();  // Automatically abort the old task
        }
        state.current_task = Some(task);
    }
}

This design choice reflects a key insight: attention is a singular resource. Just as a human programmer can focus on only one problem at a time, the AI assistant correspondingly maintains a single focus. This yields:

1. Clear causality: every output can be traced back to a specific input
2. Predictable resources: no resource contention
3. Simplified error handling: errors always relate to the current task

This approach also simplifies agent design. And if a user needs multi-tasking, they can simply run multiple Codex instances.

I think that given the current boundaries of AI capability, what matters is not parallel processing of many tasks, but deeply understanding and executing a single task well.

Turn: The Atomic Unit of Conversation

The Essence of Turn

If we liken a Task to a symphony, then each Turn is one of its movements. Each Turn is a complete request → process → response cycle.

async fn run_turn(
    sess: &Session,
    turn_diff_tracker: &mut TurnDiffTracker,
    sub_id: String,
    input: Vec<ResponseItem>,
) -> CodexResult<Vec<ProcessedResponseItem>> {
    // 1. Prepare context
    let tools = get_openai_tools(
        &sess.tools_config,
        Some(sess.mcp_connection_manager.list_all_tools()),
    );

    let prompt = Prompt {
        input,
        user_instructions: sess.user_instructions.clone(),
        store: !sess.disable_response_storage,
        tools,
        base_instructions_override: sess.base_instructions.clone(),
        environment_context: Some(EnvironmentContext {
            cwd: sess.cwd.clone(),
            approval_policy: sess.approval_policy,
            sandbox_policy: sess.sandbox_policy.clone(),
        }),
    };

    // 2. Execute request (with retry logic)
    let mut retries = 0;
    loop {
        match try_run_turn(sess, turn_diff_tracker, &sub_id, &prompt).await {
            Ok(output) => return Ok(output),
            Err(e) => {
                // Intelligent retry logic
                if retries < max_retries {
                    retries += 1;
                    let delay = backoff(retries);
                    tokio::time::sleep(delay).await;
                } else {
                    return Err(e);
                }
            }
        }
    }
}

The run_turn function is an asynchronous function that coordinates the execution of a “turn” within a session. A “turn” represents a complete cycle of request processing and response generation. The function receives a reference to a session, a mutable reference to a turn diff tracker, a subscription ID, and a vector of input response items, and returns a result containing either a vector of processed response items or an error.

The function first prepares the context required for the turn. It retrieves the necessary tools using the session’s tool configuration and connection manager. It then creates a Prompt struct that encapsulates the input, user instructions, and other contextual information such as environment context and policies.

At the core of the function is a loop that attempts to execute the turn using the try_run_turn function. The loop includes a retry mechanism with a backoff policy. If try_run_turn succeeds, the output is returned. If it fails, the function checks whether the maximum number of retries has been reached. If not, it increments the retry count and waits for a computed delay before retrying. If the maximum retries are exceeded, it returns the error. This design ensures robustness by handling transient errors via retries, while providing a structured way to manage turn execution with all the necessary context and configuration.

Streaming Within a Turn

Turn’s implementation demonstrates a subtle balance between real-time responsiveness and completeness:

async fn try_run_turn(
    sess: &Session,
    turn_diff_tracker: &mut TurnDiffTracker,
    sub_id: &str,
    prompt: &Prompt,
) -> CodexResult<Vec<ProcessedResponseItem>> {
    let mut stream = sess.client.clone().stream(&prompt).await?;
    let mut output = Vec::new();

    loop {
        let event = stream.next().await;

        match event {
            ResponseEvent::OutputTextDelta(delta) => {
                // Push text deltas in real time
                sess.state.lock().unwrap()
                    .history.append_assistant_text(&delta);

                let event = Event {
                    id: sub_id.to_string(),
                    msg: EventMsg::AgentMessageDelta(AgentMessageDeltaEvent {
                        delta,
                    }),
                };
                sess.tx_event.send(event).await.ok();
            }
            ResponseEvent::OutputItemDone(item) => {
                // Process a complete response item
                let response =
                    handle_response_item(sess, turn_diff_tracker, sub_id, item.clone()).await?;
                output.push(ProcessedResponseItem { item, response });
            }
            ResponseEvent::Completed { .. } => {
                // Turn complete, return results
                return Ok(output);
            }
            // ...
        }
    }
}

This streaming design brings several key advantages:

1. Instant feedback: users can watch the AI’s reasoning process in real time
2. Progressive construction: the response is built incrementally, allowing early interruption
3. Error isolation: a single error within the stream does not destroy the entire response

More important still, this design embodies a process philosophy. It does not treat the AI’s response as a static result but as a dynamic process of generation. Users see not only the “what” but also the “how.”

The Retry Mechanism Within a Turn

Turn’s retry logic is more than technical fault tolerance; it is a guarantee of user experience continuity. Through transparent retries and user notifications, the system transforms technical failures into understandable delays. There is a profound design philosophy here: failure is not the exception but the norm. A system’s robustness lies not in avoiding failure but in handling it gracefully. This philosophy runs throughout the entirety of Codex’s design.

let max_retries = sess.client.get_provider().stream_max_retries();
if retries < max_retries {
    retries += 1;
    let delay = backoff(retries);

    // Notify the user that a retry is in progress
    sess.notify_background_event(
        &sub_id,
        format!("stream error: {e}; retrying {retries}/{max_retries} in {delay:?}…"),
    ).await;

    tokio::time::sleep(delay).await;
}

The Concerto of Three Abstractions: The Elegance of the Architecture

Let us look at the relationships among the three:

The three abstraction layers—Session, Task, and Turn—exhibit orthogonality:

• Session manages environment and configuration (the spatial dimension)
• Task manages user intent and execution flow (the purposive dimension)
• Turn manages a single interaction and response processing (the temporal dimension)

Each layer has a clear responsibility, non-interfering yet tightly collaborating. This design recalls the Unix philosophy: “Do one thing, and do it well.”

State Transitions

Let us observe how state flows through a complete interaction:

// 1. Session initialization
Op::ConfigureSession { ... }
    → Session::new()
    → EventMsg::SessionConfigured

// 2. User input triggers a Task
Op::UserInput { items }
    → Session::inject_input()
    → AgentTask::spawn()
    → EventMsg::TaskStarted

// 3. Task executes multiple Turns
loop {
    run_turn()
        → Model API call
        → Streaming response processing
        → EventMsg::AgentMessageDelta
        → Tool call execution
        → EventMsg::ExecCommandBegin/End
}

// 4. Task completion
→ EventMsg::TaskComplete

This clean state flow is the product of deliberate design. Every state transition is predictable, traceable, and recoverable.

Error Handling

Codex’s error handling demonstrates a deep understanding of Murphy’s Law—“anything that can go wrong will go wrong”:

pub enum CodexErr {
    Interrupted,              // User interruption
    EnvVar(String),          // Missing environment variable
    UsageLimitReached(String), // Quota limit
    Stream(String),          // Stream connection error
    InternalAgentDied,       // Internal error
    // ...
}

Each error has its own specific handling strategy:

• Recoverable errors (e.g., a dropped stream) → automatic retry
• User errors (e.g., insufficient permission) → request user intervention
• Fatal errors (e.g., internal crash) → graceful termination

This classification is not technical but semantic. It reflects an understanding of the nature of error: some errors are temporary setbacks, some are dilemmas requiring human judgment, and some are insurmountable obstacles.

A Deep Analysis of Design Patterns

1. Resource Management Pattern

Codex cleverly leverages Rust’s ownership system to manage resources: every resource has its birth, existence, and death. By binding resource management to object lifetimes, the system achieves an intrinsic consistency.

impl Drop for Session {
    fn drop(&mut self) {
        self.abort();  // Automatically clean up all active tasks
    }
}

2. Concurrency Pattern

Although Codex does not explicitly use the Actor model, its design philosophy is similar:

async fn submission_loop(
    session_id: Uuid,
    config: Arc<Config>,
    auth: Option<CodexAuth>,
    rx_sub: Receiver<Submission>,
    tx_event: Sender<Event>,
    ctrl_c: Arc<Notify>,
) {
    let mut sess: Option<Arc<Session>> = None;

    loop {
        let sub = tokio::select! {
            res = rx_sub.recv() => match res {
                Ok(sub) => sub,
                Err(_) => break,
            },
            _ = ctrl_c.notified() => {
                // Gracefully handle interruption
                if let Some(sess) = sess.as_ref() {
                    sess.abort();
                }
                continue;
            },
        };

        // Process submission...
    }
}

This loop is like an Actor that:

• Owns private state (sess)
• Communicates via messages (Submission and Event)
• Processes requests asynchronously
• Isolates faults

But this is more than the application of a technical pattern. It embodies a mindset of isolation: each component is an independent entity that interacts through well-defined interfaces. This design improves the system’s comprehensibility and maintainability.

3. Strategy Pattern

Codex’s use of configurable security policies demonstrates an elegant application of the strategy pattern:

impl SandboxPolicy {
    pub fn get_writable_roots_with_cwd(&self, cwd: &Path) -> Vec<WritableRoot> {
        match self {
            SandboxPolicy::DangerFullAccess => Vec::new(),
            SandboxPolicy::ReadOnly => Vec::new(),
            SandboxPolicy::WorkspaceWrite { writable_roots, ... } => {
                // Complex path computation logic
                let mut roots = writable_roots.clone();
                roots.push(cwd.to_path_buf());

                // Intelligently handle temp directory
                if !exclude_tmpdir_env_var {
                    if let Some(tmpdir) = std::env::var_os("TMPDIR") {
                        roots.push(PathBuf::from(tmpdir));
                    }
                }

                // Protect version-control directories
                roots.into_iter().map(|root| {
                    let mut subpaths = Vec::new();
                    if root.join(".git").is_dir() {
                        subpaths.push(root.join(".git"));
                    }
                    WritableRoot { root, read_only_subpaths: subpaths }
                }).collect()
            }
        }
    }
}

This design allows security policies to be swapped flexibly at runtime without affecting core logic. More important still, it embodies a contractual mindset: security is not a binary switch but a series of negotiable contracts.

Extensibility Design

1. Protocol Versioning

Although there is no explicit version field in the current code, the protocol design has already accounted for future extension:

#[non_exhaustive]
pub enum Op {
    /// Configure the model session.
    ConfigureSession { ... },

    /// Abort current task.
    Interrupt,

    /// Input from the user
    UserInput { ... },

    /// Approve a command execution
    ExecApproval { ... },

    /// Approve a code patch
    PatchApproval { ... },

    /// Append an entry to the persistent cross-session message history.
    AddToHistory { ... },

    /// Request a single history entry identified by `log_id` + `offset`.
    GetHistoryEntryRequest { ... },

    /// Request the agent to summarize the current conversation context.
    Compact,
    /// Request to shut down codex instance.
    Shutdown,
}

#[non_exhaustive]
pub enum EventMsg {
    /// Error while executing a submission
    Error(ErrorEvent),

    /// Agent has started a task
    TaskStarted,

    /// Agent has completed all actions
    TaskComplete(TaskCompleteEvent),

    /// Token count event, sent periodically to report the number of tokens
    /// used in the current session.
    TokenCount(TokenUsage),

    /// Agent text output message
    AgentMessage(AgentMessageEvent),

    /// Agent text output delta message
    AgentMessageDelta(AgentMessageDeltaEvent),

    /// Reasoning event from agent.
    AgentReasoning(AgentReasoningEvent),

    /// Agent reasoning delta event from agent.
    AgentReasoningDelta(AgentReasoningDeltaEvent),

    /// Raw chain-of-thought from agent.
    AgentReasoningRawContent(AgentReasoningRawContentEvent),

    /// Agent reasoning content delta event from agent.
    AgentReasoningRawContentDelta(AgentReasoningRawContentDeltaEvent),

    /// Ack the client's configure message.
    SessionConfigured(SessionConfiguredEvent),

    McpToolCallBegin(McpToolCallBeginEvent),

    McpToolCallEnd(McpToolCallEndEvent),

    /// Notification that the server is about to execute a command.
    ExecCommandBegin(ExecCommandBeginEvent),

    /// Incremental chunk of output from a running command.
    ExecCommandOutputDelta(ExecCommandOutputDeltaEvent),

    ExecCommandEnd(ExecCommandEndEvent),

    ExecApprovalRequest(ExecApprovalRequestEvent),

    ApplyPatchApprovalRequest(ApplyPatchApprovalRequestEvent),

    BackgroundEvent(BackgroundEventEvent),

    /// Notification that the agent is about to apply a code patch. Mirrors
    /// `ExecCommandBegin` so front‑ends can show progress indicators.
    PatchApplyBegin(PatchApplyBeginEvent),

    /// Notification that a patch application has finished.
    PatchApplyEnd(PatchApplyEndEvent),

    TurnDiff(TurnDiffEvent),

    /// Response to GetHistoryEntryRequest.
    GetHistoryEntryResponse(GetHistoryEntryResponseEvent),

    PlanUpdate(UpdatePlanArgs),

    /// Notification that the agent is shutting down.
    ShutdownComplete,
}

The #[non_exhaustive] attribute allows new variants to be added without breaking compatibility. The system is not static but constantly evolving. Good design should leave room for future change.

2. Transport-Layer Abstraction

Codex can operate on multiple transport layers:

This transport-agnostic design lets Codex integrate easily into different environments. It embodies the interface-segregation principle: core logic should not depend on any specific transport mechanism.

3. MCP (Model Context Protocol) Integration

mcp_connection_manager: McpConnectionManager,

Through MCP integration, Codex can extend its capabilities and connect to external tools and services. This plug-in design greatly enhances the system’s extensibility.

Pondering the Design Philosophy of Codex

Separation of Concerns

Codex’s architecture embodies the separation of concerns beautifully:

1. Protocol layer (protocol.rs) defines the communication contract
2. Business-logic layer (codex.rs) implements the core functionality
3. Client layer (client.rs) handles interaction with the AI model
4. Safety layer (safety.rs) guarantees the safety of operations

Each layer can evolve independently—the key to long-term maintainability. But this separation is organic, not mechanical. Each layer has its own inner logic and integrity.

User Experience

Codex’s design reflects deep thought about user experience at every turn:

1. Transparency: every operation has a corresponding event notification
2. Controllability: the user can interrupt and adjust at any time
3. Safety: multi-layered security policy options
4. Fault tolerance: graceful error handling and recovery

Balancing Simplicity and Functionality

A famous line attributed to Einstein (though he never said it): “Everything should be as simple as possible, but not simpler.” Codex’s three-layer abstraction precisely embodies this principle: three layers suffice to cover all use cases, each with its own unique and essential responsibility; remove any layer and you lose important functionality—no more, no less.

Future Outlook and Inspiration

Possible Directions of Evolution

Based on the current architecture, we can imagine a few plausible directions of evolution:

1. Parallel Task support: although the current design is single-Task, the architecture has already left room for parallel execution
2. Distributed Session: a Session can span multiple nodes for larger-scale collaboration
3. Turn-level caching: similar Turns can reuse previous results
4. Richer security policies: dynamic security policies based on machine learning

Lessons for Software Architecture

Codex’s design offers several important lessons:

1. Layering of abstraction: good abstractions should form a clear hierarchy
2. Locality of state: state should be confined to the smallest possible scope
3. Recoverability of errors: the system should handle and recover from errors gracefully
4. Primacy of the user: technology should serve the user, not the reverse

Let us consider a deeper question: what is a good model for human-AI collaboration?

Through the design of Session, Task, and Turn, Codex offers an answer:

• Session provides a stable collaborative environment
• Task realizes goal-directed execution
• Turn ensures the continuity of interaction

Together these three constitute a predictable, controllable, and extensible collaboration framework.

---

This article has explored the core architecture of OpenAI’s Codex CLI through an analysis of its source code. May these reflections inspire you to create designs in your own projects that are equally elegant and thoughtful.

If you are interested in the project, feel free to visit https://github.com/openai/codex to learn more.