Learn Codex
Build a Codex-style coding-agent harness from 0 to 1, one mechanism at a time
The Core Pattern
Every coding agent shares the same loop: call the model on the Responses API, execute the function calls it returns, and feed each output back. Production harnesses like Codex add approval, sandboxing, and lifecycle layers on top.
while (true) {
const resp = await openai.responses.create({ model, input, tools });
const calls = resp.output.filter((i) => i.type === "function_call");
if (calls.length === 0) break;
for (const call of calls) {
const output = await runTool(call.name, call.arguments);
input.push({ type: "function_call_output", call_id: call.call_id, output });
}
}
Message Growth
Watch the input items grow as the agent loop drives the Responses API
Learning Path
20 progressive sessions, from a single loop to a complete multi-agent harness
The Agent Loop
The smallest useful agent is a loop that calls the model, runs tools, and feeds results back.
Tool Use
The loop stays stable while capabilities register into a dispatch table.
Approval & Permissions
Codex's approval modes (untrusted / on-failure / on-request / never) are a harness decision point before the shell runs.
Sandbox
read-only / workspace-write / danger-full-access, backed by OS isolation, decides what a command can actually touch.
The Plan Tool
Explicit plans keep long-running work visible and correctable — Codex exposes this as the update_plan tool.
Subagents
Subagents give each subtask a clean message history while preserving the main thread.
Skills
Codex skills inject specialized instructions only when the task actually needs them.
Context Compaction
Compaction keeps the conversation usable when the context window gets crowded.
Memory & Sessions
Session rollouts let codex resume survive restarts; some facts should outlive summarization.
Instructions & AGENTS.md
The system prompt is a generated product of AGENTS.md, config.toml, profiles and built-ins.
Error Recovery
A robust harness classifies failures (rate limit, overflow, abort) and decides what kind of retry is worthwhile.
Task System
A task graph turns vague goals into ordered, observable work.
Background Tasks
The agent keeps reasoning while slow commands finish elsewhere — codex exec taken further.
Automations
Recurring work should be created by the harness, not remembered by the model.
Agent Teams
Persistent teammates let work continue in parallel without stuffing every thought into one context.
Team Protocols
Multi-agent systems need explicit message contracts, not vibes.
Autonomous Agents
Teammates become useful when they can discover and claim work themselves.
Worktree Isolation
Parallel agents need isolated filesystems as much as isolated conversations — the model Codex Cloud runs on.
MCP Servers
External services become agent tools through a standard discovery and call protocol configured in config.toml.
The Full Harness
The final harness is still one loop, now surrounded by the systems that make it production-shaped.
The Codex CLI Surface
codex exec/resume/review/login/mcp and the /slash commands are one dispatch layer over the same harness.
config.toml in Depth
model_providers, wire_api, sandbox_workspace_write, profiles and mcp_servers all resolve through one precedence chain.
Review, CI & Cloud
codex review, codex exec in CI, and Codex Cloud tasks are the same loop running unattended on real work.
Plugins, Apps & Hooks
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
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
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 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
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.
Architectural Layers
Five orthogonal concerns that compose into a complete agent harness