CodexArchitecture & History
From generating a snippet of code to running a complete task.
See how the model, tools, context, and sandbox work together.
Updated · Official docs and source
The model is swappable. The harness keeps the task running.
Pick a surface and a model, then watch which layer changes.
Manage threads by project, review edits, and organize parallel work. Execution still uses the same harness.
Model
Responses API · reasoning and tool requests
Codex Harness
The core that runs the task
Execution environment
Act only in the authorized scope
- ShellCommands and tests
- Git / FilesystemCode, files, and diffs
- BrowserPages and app actions
- MCPExternal tools and data
As of 2026.09.10 it is in eligible Codex accounts; CLI needs 0.153.0+. Changing the model changes reasoning quality and speed. Tools and permissions still belong to the runtime.
Codex is an agent product and a runtime system.The model reasons. The harness organizes context, runs tools, and handles feedback. The interface lets you start, follow, and review work.
Agent Loop: act, inspect the result, decide again
A failed build is not the end. Tool errors become the next input to the model.
- Task and inputGoal, constraints, and prior record
- Build contextInstructions, relevant files, and tool definitions
- Model decisionAnswer the user, or propose a tool call
- Permission checkApproval policy and accessible scope
- Run toolsCommands, files, browser, or MCP
- Result and feedbackOutput returns to the model for the next turn
- DeliverExplain the change and verification
Record the goal: finish the migration and verify the build.
Context is working memory. Threads are the task record.
The model receives the available context each turn. Clients show ongoing work through threads and events.
Context compaction
Capacity diagramReading files, inspecting diffs, and running tests all add content the model has to handle.
Percentages explain the process. They are not a real token limit or compaction ratio.
How does the task continue after compaction?
- Keep the task directionThe current goal, key decisions, and open questions need to travel into the next stretch of work.
- Cut the historical loadLong logs and intermediate steps do not need to be sent in raw form every turn.
- Re-read when precision mattersCompaction is not a lossless archive. Exact code and the latest state should still be confirmed from files or tools.
The Responses API can return an opaque compaction item that carries prior state in fewer tokens. That is not the same as this readable summary.
Thread → Turn → Item
- User message
- Tool execution and output
- Code diff
- Agent message
- New user message
- Tool execution and verification
- Agent message
A thread holds multiple turns; each turn holds a sequence of items. Persisted history lets a client reconnect, continue, or fork a session.
What does the model actually receive?
instructionsSystem and developer instructions, plus task constraintstoolsDefinitions and parameters for available toolsinputUser messages, project context, tool calls, and tool outputAGENTS.md supplies project rules such as test commands, code conventions, and directory notes. It shapes task context.
API-key mode calls the model through the Responses API. ChatGPT login uses the matching Codex backend. The exact request depends on the chosen provider and client config.
Approvals decide whether to ask. The sandbox limits what can run.
After the model proposes a tool call, execution policy and environment constraints still apply.
Extensions: connect tools, and pass along working methods
MCP
Connect external tools and data sources over a standard protocol — code hosts, databases, or business systems.
Skills
Package instructions, resources, and scripts into reusable working methods, loaded when a task needs them.
Plugins
Combine related apps, Skills, and tool integrations into a complete setup for a role or workflow.
From a TypeScript prototype to a Rust runtime
Native execution, terminal interaction, state, and system isolation make up the CLI’s engineering base.
TypeScript + Ink
React Ink made it fast to build and iterate on a terminal UI. It required Node.js 22+ at the time.
Rust + Ratatui
The move targeted a standalone binary, native security bindings, lower memory overhead, and an extensible protocol.
Runtime core
Rust · TokioAgent state, async work, and process coordination.
core / execTerminal UI
Ratatui · Crossterm · ClapDraw the terminal UI and handle keyboard input and CLI flags.
tui / cliModel transport
Reqwest · Rustls · WebSocketSend requests, keep the connection secure, and receive streamed responses.
http-client / backend-clientClient protocol
Serde · JSON-RPC · JSONLTurn client requests and runtime events into structured messages.
app-server / app-server-protocolConfig and state
TOML · SQLite · SQLxRead config and persist some local state. Thread history has a separate store.
config / history / rolloutTools and terminals
rmcp · portable-pty · Tree-sitterConnect external tools, control terminal child processes, and parse command structure.
rmcp-client / utils/ptyObservability
tracing · OpenTelemetryRecord runtime events to diagnose calls and execution.
otelSystem isolation
Seatbelt · bubblewrap · seccompConstrain tool execution by platform and policy. Linux still has a compatible Landlock path.
core / linux-sandboxItems come from the Rust workspace and Core docs. The migration goals above were the team’s engineering notes at the time, not a performance benchmark. Dependencies and module layout change across versions.
Codex timeline
From the code model behind Copilot to an agent system that can call tools and finish tasks.
19 milestones
- Model
GPT-6 Astra arrives in Codex
As of September 10, official help docs confirm Astra for eligible Codex accounts. The CLI needs 0.153.0 or later. Availability still depends on plan and workspace permissions.
OpenAI Help Center · Original sourceModels keep iterating. Codex still supplies the tools and task runtime.
- Model
GPT-5.6: Sol, Terra, Luna
Sol targets complex work, Terra balances capability, speed, and cost, and Luna is for faster, cheaper tasks. Coding, research, and computer use land in one model family.
OpenAI · Original sourcePick a model for the job instead of splitting “regular GPT” from a code model.
- Product
Plugins, Sites, and knowledge work
Role-specific plugins, shareable Sites previews, and result annotations shipped. Analysis, design, and research became explicit product surfaces.
OpenAI · Original sourceDeliverables expanded from code to reports, charts, and interactive pages.
- Product
Codex can operate the computer and apps
The desktop app added background computer use, a built-in browser, image generation, memory preview, and more plugins, plus broader automation and SSH development-environment support.
OpenAI · Original sourceA task can span the repo, the browser, and desktop apps.
- Model
GPT-5.4: coding and general capability converge
The mainline GPT model absorbed GPT-5.3-Codex coding ability and strengthened computer use and knowledge work.
OpenAI · Original sourceCodex as an agent product moved further apart from any one model name.
- Model
Codex-Spark: a real-time coding path
A research preview on Cerebras hardware. At launch it was text-only, with a 128K context and official reports of more than 1,000 tokens/s.
OpenAI · Original sourceAlongside long tasks, Codex added a low-latency, rapid-edit working style.
- Model
GPT-5.3-Codex: coding joined with reasoning
It combined GPT-5.2-Codex coding with GPT-5.2 reasoning and domain knowledge, supporting long tasks that include research, tool use, and complex execution.
OpenAI · Original sourceAnalysis and implementation in one task can stay on the same model.
- Engineering
OpenAI published the App Server architecture
The official write-up unpacked the shared harness, bidirectional JSON-RPC protocol, and Thread / Turn / Item data model, showing how local clients and the cloud attach to the same core.
OpenAI · Original sourceDifferent interfaces can reuse the same execution logic and task events.
- Product
Codex App: managing parallel tasks
A macOS app shipped first, organizing multiple agents by project and independent threads, with worktrees, change review, Skills, and automation entry points.
OpenAI · Original sourceWork expanded from a single terminal collaboration to managing many tasks.
- Model
GPT-5.2-Codex: long tasks and context compaction
It strengthened context compaction, reliable tool calls, large-scale refactors and migrations, and improved Windows performance.
OpenAI · Original sourceThe focus moved from generating a function to finishing complex work in a real codebase.
- Product
Codex becomes generally available
Codex entered GA with an SDK, Slack integration, and admin controls, connecting terminal, editor, and cloud work.
OpenAI · Original sourceThe agent could be embedded in team workflows and other software.
- Model
GPT-5-Codex: a coding model for agents
Optimized for real software-engineering work: interactive edits, independent long tasks, and code review, used across CLI, IDE, and cloud experiences.
OpenAI · Original sourceTraining goals moved closer to reading, changing, and testing real projects.
- Engineering
Codex CLI announces a move to Rust
The early TypeScript and React Ink implementation started migrating to Rust, aiming for standalone installs, native security bindings, lower memory overhead, and an extensible protocol.
OpenAI · GitHub · Original sourceCLI engineering shifted toward a native agent runtime.
- Product
Cloud Codex and codex-1
Tasks ran in an isolated cloud environment preloaded with the repo, able to read and write files, run tests, and open PRs. codex-1 was an o3 variant optimized for software engineering.
OpenAI · Original sourceDevelopers could hand off a full coding job asynchronously.
- Product
Codex CLI: the brand returns as an agent
An open-source terminal agent shipped with o3 and o4-mini, connecting model reasoning to local code and command execution.
OpenAI · Original sourceGive it a goal, and the agent can inspect the project, change code, and verify the result.
- Model
First-generation Codex API models retire
code-davinci-001/002 and code-cushman-001/002 left the API. This refers to the old code models, not the Codex agent product that returned after 2025.
OpenAI Docs · Original sourceThe first code-completion API ended. Later Codex reused the name.
- Product
Codex API opens private beta
OpenAI opened natural-language-to-code to developers through a private API beta.
OpenAI · Original sourceA code-generation model became a service other apps could call.
- Model
The Codex paper and HumanEval
The paper studied a GPT model fine-tuned on public GitHub code and released HumanEval. Codex in the paper scored 28.8% pass@1 on that benchmark.
OpenAI · arXiv · Original sourceGenerated programs were measured with executable tests.
- Product
GitHub Copilot technical preview
GitHub launched a Copilot technical preview powered by OpenAI Codex, bringing code suggestions into the editor.
GitHub · Original sourceMany developers first used Codex inside an IDE.
The 2021 unit of workA snippet of code
The modern Codex unit of workA task
Sources
Timeline entries cite sources from the time of publication. Architecture and model availability were checked through September 10, 2026.