Architectural Layers
Five orthogonal concerns that compose into a complete agent harness
L1 Tools & Execution
What the agent CAN do. The foundation: function tools give the model capabilities to act on the world, gated by approval and sandbox policy.
The Agent Loop
One Loop Is All You Need
The smallest useful agent is a loop that calls the model, runs tools, and feeds results back.
Tool Use
Structured Tools, Not Just a Shell
The loop stays stable while capabilities register into a dispatch table.
Approval & Permissions
Ask Before You Act
Codex's approval modes (untrusted / on-failure / on-request / never) are a harness decision point before the shell runs.
Sandbox
Run It, But Contain It
read-only / workspace-write / danger-full-access, backed by OS isolation, decides what a command can actually touch.
L2 Planning & Control
How work is organized. From the update_plan checklist to instructions assembled from AGENTS.md and config.toml.
The Plan Tool
An Agent Without a Plan Drifts
Explicit plans keep long-running work visible and correctable — Codex exposes this as the update_plan tool.
Subagents
Delegate With a Clean Context
Subagents give each subtask a clean message history while preserving the main thread.
Skills
Load Expertise Only When Needed
Codex skills inject specialized instructions only when the task actually needs them.
Instructions & AGENTS.md
Assembled at Runtime, Never Hardcoded
The system prompt is a generated product of AGENTS.md, config.toml, profiles and built-ins.
Error Recovery
Errors Are the Start of a Retry
A robust harness classifies failures (rate limit, overflow, abort) and decides what kind of retry is worthwhile.
L3 Memory Management
Keeping context within limits. Auto-compaction and session rollouts let agents work indefinitely without losing coherence.
L4 Concurrency & Automation
Non-blocking execution. Background tasks and scheduled automations for parallel and recurring work.
Background Tasks
Slow Work Goes to the Background
The agent keeps reasoning while slow commands finish elsewhere — codex exec taken further.
Automations
Work on a Schedule
Recurring work should be created by the harness, not remembered by the model.
L5 Multi-Agent Platform
Multi-agent coordination. Task boards, teams, protocols, worktrees, and MCP servers that let agents work together.
Task System
Break Big Goals Into Small Tasks
A task graph turns vague goals into ordered, observable work.
Agent Teams
One Agent Isn't Enough, Form a Team
Persistent teammates let work continue in parallel without stuffing every thought into one context.
Team Protocols
Teammates Need Agreements
Multi-agent systems need explicit message contracts, not vibes.
Autonomous Agents
Check the Board, Claim the Task
Teammates become useful when they can discover and claim work themselves.
Worktree Isolation
Separate Directories, No Conflicts
Parallel agents need isolated filesystems as much as isolated conversations — the model Codex Cloud runs on.
MCP Servers
External Tools, Standard Protocol
External services become agent tools through a standard discovery and call protocol configured in config.toml.
The Full Harness
All Mechanisms, One Loop
The final harness is still one loop, now surrounded by the systems that make it production-shaped.
L6 Codex in Depth
codex
The Codex CLI Surface
One Binary, Many Doors
codex exec/resume/review/login/mcp and the /slash commands are one dispatch layer over the same harness.
config.toml in Depth
Every Knob, One Resolver
model_providers, wire_api, sandbox_workspace_write, profiles and mcp_servers all resolve through one precedence chain.
Review, CI & Cloud
The Harness Leaves Your Laptop
codex review, codex exec in CI, and Codex Cloud tasks are the same loop running unattended on real work.
Plugins, Apps & Hooks
Extend Codex Beyond Skills and MCP
Plugins bundle skills/MCP/prompts into installable marketplaces, hooks run on lifecycle events, and codex mcp-server turns Codex itself into a tool.
Tools Beyond the Shell
See, Search, and Drive a Browser
Codex's built-in tools go far past the shell — it can search the live web, read images, generate them, and operate a browser or desktop.
Local Models & Custom Providers
Run Without OpenAI
The same harness points at a local Ollama/LM Studio model or a compatible gateway by swapping one provider and its wire_api.
Codex as a Service & the Other Surfaces
One Engine, Many Frontends
One Codex engine serves the CLI, a desktop app, a VS Code extension, a remote app-server, and the hosted ChatGPT/GitHub integrations.
Sessions, Sandbox & Safety in Depth
Fork, Trust, and the Full Safety Model
The full session lifecycle (resume/fork/archive) and the safety knobs that dial autonomy from read-only up to full bypass — gated by feature flags.