Codex CLI
Codex CLI is OpenAI’s terminal-native coding agent: a local command-line harness that lets frontier coding models inspect repositories, edit files, run shell commands, call MCP tools, and operate under explicit sandbox and approval policy. Its importance is less that it is “a model in a terminal” than that it represents a specific agent-harness design: config-first, MCP-native, hook-extensible, sandbox-governed, and increasingly shared across local CLI, IDE, cloud, GitHub, and multi-agent workflows.
Coverage note: verified through May 11, 2026.
Source and naming note
This article treats Codex CLI as the current OpenAI Codex terminal product, not the deprecated Codex API/model family from the early GPT-3 era. OpenAI’s own documentation describes “Codex CLI” as “a coding agent from OpenAI that runs locally on your computer,” available from the terminal and able to read, modify, and run code. OpenAI Developers OpenAI separately documents the shutdown of the older code-davinci-* and code-cushman-* Codex models in March 2023, which are a different product lineage. OpenAI Developers I do not find primary public evidence for a distinct “Codex Inc.” vendor behind this CLI; the public documentation and release notes identify the product as OpenAI Codex.
The short version
Codex CLI is a Terminal-Native Coding Agent: a thin local harness around a coding model, a filesystem, shell execution, policy controls, and external tool adapters. It is close in shape to Claude Code because both systems give an agent access to local project context and controlled side effects, but Codex CLI makes different bets about where governance belongs. Claude Code emphasizes a rich application-layer permission and hook system; Codex CLI emphasizes a more explicit sandbox-mode-as-policy model, TOML configuration, MCP server declarations, and a plugin/skills distribution layer.
That distinction matters because “coding agent” performance is no longer only about the base model. The harness determines which commands the model can run, how context is loaded, how approvals are requested, how tool calls are serialized, whether external services enter through Model Context Protocol, and how safely the agent can be delegated work. Comparative harness writing has converged on this point: superficially similar terminal agents can behave differently because their orchestration protocols, tool schemas, memory files, permissions, and post-training assumptions differ. Nicolas Bustamante
Product surface: what Codex CLI is
OpenAI’s documentation defines Codex CLI as a local coding agent: installable with npm or Homebrew, runnable from a terminal, and capable of reading and editing code, running commands, generating diffs, and helping with testing and debugging. OpenAI Developers The initial public framing appeared alongside OpenAI’s April 2025 o3/o4-mini release, where OpenAI described Codex CLI as a “lightweight coding agent” bringing “frontier reasoning” into the terminal. OpenAI
The modern product surface is broader than a single TUI. OpenAI describes Codex as spanning CLI, IDE extension, cloud tasks, GitHub integration, and web/cloud execution surfaces, while the CLI remains the terminal-native interface for local developer loops. OpenAI In release notes and docs, the CLI is no longer just a prompt-to-patch tool; it is a programmable harness with MCP configuration, hooks, plugins, skills, subagents, app-server reuse, sandbox policy, image attachments, web search, compacting conversation state, and remote-control features. OpenAI Developers
The important boundary is this: Codex CLI is not the model itself. It is the Agent Harness that binds a model to project context, shell access, patch application, tool calls, approvals, and policy. The model supplies reasoning and code synthesis; the harness supplies the operating environment.
Architecture: thin harness, explicit policy
Thin harness philosophy
Codex CLI follows a “thin harness” pattern similar to Claude Code: the agent is placed close to the developer’s repository, gets a small set of high-leverage tools, and works through the same affordances a developer uses—files, diffs, tests, shell commands, dependency managers, and version control. OpenAI’s App Server notes explain that Codex began with a terminal UI agent loop and that the same harness was later reused across IDE and embedded contexts rather than reimplemented for each surface. OpenAI
This “thinness” is strategic. A thick autonomous-development platform can hide the real execution environment behind a cloud abstraction. A terminal-native harness instead asks: what is the smallest set of local powers a model needs to be useful? For Codex CLI, the answer is roughly:
| Harness layer | Codex CLI role | Why it matters |
|---|---|---|
| Conversation loop | Maintains agent state, plans, tool calls, and compacted context | Determines whether the agent stays coherent over long sessions |
| Filesystem access | Reads and edits repository files | Makes the agent useful for real projects rather than isolated snippets |
| Shell execution | Runs tests, build tools, package managers, linters, search commands | Lets the model verify work empirically |
| MCP integration | Connects external tools and context providers | Lets teams extend the agent without changing the core binary |
| Hooks and plugins | Inject lifecycle behavior and reusable capabilities | Enables governance, notifications, workflow automation, and team conventions |
| Sandbox and approval policy | Controls side effects and escape risk | Turns local autonomy into an explicit trust decision |
The recurring architectural point is that Codex CLI’s “intelligence” is distributed. It lives partly in the model, partly in the local tools, partly in configuration, and partly in policy.
Config-first design
Codex CLI is unusually configuration-forward. The main user-level configuration file is ~/.codex/config.toml, and project-level configuration can live under .codex/config.toml for trusted projects. The docs expose keys for sandbox mode, approval policy, profiles, model settings, MCP servers, hooks, and other feature flags. OpenAI Developers
This makes Codex CLI feel closer to a developer tool than a chatbot. Instead of only prompting the agent with “be careful,” the user can encode environment-specific rules: which sandbox mode applies, which MCP servers are available, which hooks run, which profiles are active, and what additional writable roots exist. The resulting pattern is Config-Driven Agent Design: operational behavior is externalized into versioned configuration rather than buried entirely in prompts.
That choice also creates a maintenance burden. As soon as configuration becomes a first-class control plane, users expect profile inheritance, local overrides, repo-local behavior, hot reload, model routing, hook reliability, and clear precedence rules. Some of the active GitHub issues around Codex CLI are precisely about those edges, including requests for separate plan-mode model configuration and reports of repo-local hook configuration not firing in interactive sessions. GitHub
MCP as native extension surface
Codex CLI treats Model Context Protocol as a primary extension surface. OpenAI’s MCP docs describe MCP as a way to connect models to tools and context, with Codex supporting both stdio and streamable HTTP MCP servers in the CLI and IDE. The same docs say the CLI and IDE share MCP configuration in config.toml, either through codex mcp commands or by editing TOML directly. OpenAI Developers
The MCP configuration surface is concrete. Codex’s config reference includes per-server keys such as command, args, cwd, env, url, HTTP headers, OAuth resource metadata, enabled and disabled tools, startup timeout, tool timeout, and “required” server behavior. OpenAI Developers This is a notable difference from agents that treat external tools as mostly ad hoc shell scripts or IDE plugins. Codex’s MCP layer gives teams a structured way to expose databases, internal docs, deployment tools, ticket systems, observability, browser automation, and custom project services to the agent.
The current limitation is directionality. Codex can call MCP tools, but at least one open issue asks for a documented path for inbound MCP notifications to become user-visible messages in an active CLI session. The issue says MCP tools are callable, but arbitrary external channel notifications do not currently route into a running interactive thread. GitHub That matters for inter-agent and chat-channel integrations because agent coordination often needs both pull-style tools and push-style events.
Hooks: lifecycle automation and governance
Codex CLI’s codex_hooks system is the most direct answer to Claude Code’s hooks. OpenAI documents hooks as an extensibility framework that can run scripts at lifecycle events, with a feature flag under [features] codex_hooks = true, configuration through hooks.json or inline TOML, and plugin-bundled hooks. OpenAI Developers The config reference lists managed lifecycle events such as PreToolUse, PostToolUse, PermissionRequest, SessionStart, UserPromptSubmit, and Stop. OpenAI Developers
Hooks create a bridge between Agent Safety and Developer Workflow Automation. A pre-tool hook can block or rewrite risky actions. A post-tool hook can log, summarize, notify, or run checks. A permission hook can encode organizational policy. A session-start hook can inject project context. A stop hook can enforce “do not finish until tests pass” conventions.
The evidence also suggests that Codex hooks are still maturing. Public issues request broader Claude Code hook parity, including missing events such as ConfigChange, CwdChanged, FileChanged, worktree lifecycle events, and fuller compaction hooks. GitHub Other issues report local hook configuration problems or hook execution edge cases. GitHub The conclusion is not that hooks are weak; it is that hooks are becoming a real governance surface, and users are therefore judging them like infrastructure.
Plugins and skills
Codex CLI’s plugin model packages reusable agent capabilities. OpenAI’s plugin docs describe plugins as bundles that can include skills, app integrations, and MCP servers, with a CLI plugin browser exposed through /plugins, marketplace-style discovery, and install/uninstall/toggle flows. OpenAI Developers Plugin authoring docs describe .codex-plugin/plugin.json, marketplace catalogs, and use cases such as sharing workflows across teams or bundling MCP/app integrations. OpenAI Developers
Skills are related but not identical. OpenAI’s skills docs describe skills as packages of instructions, resources, and scripts that the model loads on demand, while plugins are the distribution unit that can bundle skills and other integrations. OpenAI Developers In practical terms, Agent Skills are reusable reasoning-and-action recipes; plugins are the installable supply chain.
This split is architecturally clean but ecosystem-dependent. A plugin model only becomes powerful when there is a large, trusted, well-maintained ecosystem of plugins. As of the current documentation and release notes, OpenAI is actively adding plugin capabilities—sharing metadata, discoverability, bundled hooks, marketplace controls—but the ecosystem is still younger than Claude Code’s broader command/skill/hook community. OpenAI Developers
Sandbox-mode-as-policy
Codex CLI’s most distinctive architectural choice is the explicit coupling of sandbox mode and approval policy. OpenAI’s sandbox docs frame the sandbox as the boundary that defines which files and network resources Codex can access, while approval policy determines when Codex must ask the user before proceeding. Spawned commands inherit those bounds, and enforcement is platform-native. OpenAI Developers
The config reference exposes three sandbox modes: read-only, workspace-write, and danger-full-access. workspace-write can include additional writable roots and configurable network access, while danger-full-access removes the sandbox boundary. OpenAI Developers The docs also describe “full access” as sandbox_mode = "danger-full-access" plus approval_policy = "never", while a lower-risk automation preset uses workspace write with on-request approval. OpenAI Developers
This is different from treating safety as a vague conversation instruction. In Codex CLI, safety is partly a runtime policy object. The agent may propose an action, but the harness decides whether the action is inside the sandbox, whether it needs approval, and whether it can execute. OpenAI’s broader Codex safety language reinforces this: local and cloud Codex environments run with network access disabled by default, ask for permission before dangerous actions, and require human review of work, logs, citations, and test results. OpenAI
This design is powerful, but it can create UX friction. Developers often want autonomy, but only in the safe subset of operations. The hard problem is making “safe subset” legible: why was this command blocked, why did this command ask for approval, why did a shell wrapper change the policy interpretation, and which config layer controls the answer? A public issue about allowed date commands being routed through a forbidden shell-wrapper shape is a small but representative example of how sandbox policy can surprise users. GitHub
Empirical results: what benchmarks do and do not show
The benchmark picture is strong but complicated. OpenAI reports high coding-agent performance for recent Codex models on SWE-Bench-family and Terminal-Bench-family evaluations, but those numbers often measure a model-plus-harness stack, not a model in isolation.
| Evidence source | Result | What it suggests | Caveat |
|---|---|---|---|
| OpenAI GPT-5.5 release evals | GPT-5.5: 58.6 on SWE-Bench Pro; 82.7 on Terminal-Bench 2.0 | OpenAI’s latest general frontier models are highly competitive in coding and terminal-agent tasks | OpenAI notes evidence of memorization on SWE-Bench Pro in some labs’ models; exact harness conditions matter |
| OpenAI GPT-5.2-Codex release | OpenAI claims state-of-the-art on SWE-Bench Pro and Terminal-Bench 2.0 for GPT-5.2-Codex | Codex-specific models are optimized for long coding tasks and terminal execution | Vendor release claims need independent replication |
| Terminal-Bench paper summary | Codex CLI + GPT-5.2 achieved the highest reported average resolution rate, 63%, ahead of Terminus 2 + Claude Opus 4.5 at 58% and Terminus 2 + Gemini 3 Pro at 57% | Codex CLI is competitive as an execution harness on terminal tasks | Terminal-Bench tasks are not the same as day-to-day product engineering |
| GPT-5.1-Codex-Max release | OpenAI reports 30% fewer thinking tokens than GPT-5.1-Codex on SWE-bench Verified and internal >24-hour task performance | OpenAI is optimizing Codex models for long-horizon agent loops | Internal long-task claims are difficult to audit externally |
| OpenAI internal adoption claim | OpenAI says 95% of its engineers use Codex weekly and ship roughly 70% more PRs | Strong internal deployment signal | Confounded by organization, task mix, incentives, tooling, and measurement design |
OpenAI’s GPT-5.5 evaluation table reports GPT-5.5 at 58.6 on SWE-Bench Pro, behind Claude Opus 4.7 at 64.3, and at 82.7 on Terminal-Bench 2.0, ahead of GPT-5.4, Claude Opus 4.7, and Gemini 3 Pro in the displayed comparison. OpenAI OpenAI’s GPT-5.2-Codex release says GPT-5.2-Codex achieved state-of-the-art results on SWE-Bench Pro and Terminal-Bench 2.0, emphasizing large repositories and extended tasks. OpenAI The Terminal-Bench paper summary separately reports Codex CLI + GPT-5.2 as the top stack in its comparison, with a 63% average resolution rate. arXiv
The most important interpretive caution is that “Codex CLI score” and “model score” are not interchangeable. A model might perform differently under Claude Code, Codex CLI, Copilot CLI, OpenCode, or a benchmark-specific harness because each environment changes tool affordances, prompts, permissions, context management, and failure modes. This is the core of Model-Harness Fit: post-training and harness conventions become part of the model’s practical capability. Nicolas Bustamante
The second caution is benchmark contamination and overfitting. OpenAI explicitly notes evidence of memorization on SWE-Bench Pro for some labs’ models in its GPT-5.5 benchmark discussion. OpenAI That does not invalidate SWE-Bench-style results, but it makes them insufficient as a sole procurement or adoption criterion. For engineering teams, the more relevant evaluation is usually a private task suite: real repositories, real flaky tests, real deployment constraints, real style rules, and real review standards.
Deployment patterns
Local developer loop
The simplest deployment is one developer running Codex CLI inside a repository. This pattern is useful for constrained tasks: fixing a test, explaining a failure, adding a small feature, writing a migration, generating docs, or investigating a bug. The agent can inspect files, run commands, propose patches, and iterate.
This is the closest analog to Pair Programming with Agents. The user remains in the loop, but delegates search, patch generation, and test iteration. Codex CLI’s local nature matters here: it sees the actual repo state, local dependencies, shell environment, and project-specific configuration, subject to sandbox policy.
Team-configured agent environment
A more mature deployment uses config.toml, project instructions, MCP servers, hooks, plugins, and skills as team infrastructure. The goal is not “everyone prompts better”; the goal is that the agent inherits a reliable operating environment.
A team might define:
| Artifact | Example use |
|---|---|
.codex/config.toml |
Project-level sandbox, MCP, hook, and profile defaults |
| MCP servers | Internal docs, observability, deployment metadata, issue trackers, database introspection |
| Hooks | Pre-tool policy, post-tool logging, permission gates, test reminders, context injection |
| Plugins | Shared workflows, app integrations, bundled MCP servers |
| Skills | Reusable recipes for migrations, incident writeups, test generation, code review |
This is where Codex CLI begins to look like Agent Operations rather than a personal assistant. The agent is no longer configured solely by natural language. It is embedded in an operational control plane.
Inter-agent communication and HCOM-style coordination
There is public community evidence of Codex CLI being integrated into inter-agent communication layers such as HCOM, though the evidence is thinner and more community-driven than OpenAI’s own documentation. An “awesome LLM agents” listing describes hcom as a tool that lets agents “message, watch, and spawn each other across terminals,” with support for Claude Code, Gemini CLI, Codex CLI, and OpenCode, including mid-turn messaging, transcript reading, file-collision detection, terminal-screen viewing, spawning/forking/resuming, and multi-agent workflows such as debates and code-review watchers. GitHub
This pattern is significant because terminal agents are often easiest to coordinate as processes. Instead of building one monolithic “super-agent,” developers run multiple specialized agents in separate terminals, connect them through an inter-agent bus, and use file outputs, transcripts, or messages as coordination artifacts. That maps naturally to Blackboard Coordination and Agent Ensemble patterns.
The current limitation is that Codex CLI’s official inbound-message story is less mature than its outbound tool-call story. The open issue requesting inbound MCP notifications into active CLI sessions shows that developers want Codex CLI to participate in channel-based and multi-agent workflows without leaving the normal TUI session. GitHub
Codex Council and ensemble review
“Codex Council” is not a stable OpenAI product category in the public docs; it is better understood as a community pattern: spawn multiple agents or judges, ask them to review the same plan/diff/problem from different perspectives, and consolidate their conclusions. Public examples include claude-codex-forge, which documents installing Codex CLI for dual-agent review and migrating /codex and /council callsites. GitHub Another community skill named $council describes a “multi-model consensus council” that can spawn parallel judges and, in mixed mode, add Codex CLI judges that write outputs under .agents/council/. eliteai.tools
The engineering idea is sound but not yet strongly validated. Ensemble review can reduce single-agent blind spots, especially for security, correctness, and architectural tradeoffs. It can also amplify cost, latency, and false confidence. The strongest version of the pattern uses independent context packets, written verdicts, explicit disagreement capture, and a final synthesis step rather than vague “ask several bots” consensus.
GPT Max / long-horizon Codex models
The phrase “GPT Max” is not a precise public product label in the sources I found. The closest primary-source concept is OpenAI’s GPT-5.1-Codex-Max, which OpenAI describes as trained for long-running agentic tasks, with compaction across multiple context windows and better token efficiency than GPT-5.1-Codex on SWE-bench Verified. OpenAI
That matters for Codex CLI because long-horizon agent work stresses different capabilities than short code completion. The system must preserve intent across compaction, avoid repeating failed attempts, track unfinished subtasks, and maintain a stable model of the repository. OpenAI’s release language around Codex-Max suggests a convergence between model training and harness behavior: the model is being optimized for the environment it will inhabit.
Comparison with Claude Code
Codex CLI and Claude Code have the same broad shape: terminal agent, repository context, file edits, shell execution, MCP, hooks, skills, permissions, and increasingly IDE/cloud surfaces. Anthropic describes Claude Code as an agent that reads codebases, edits files, runs commands, integrates tools, works across terminal/IDE/desktop/browser, and follows a composable Unix philosophy suitable for piping, scripting, and automation. Claude
The difference is not “one is an agent and the other is a chatbot.” Both are serious agent harnesses. The difference is where they put control.
| Dimension | Codex CLI | Claude Code |
|---|---|---|
| Default model family | OpenAI Codex/GPT coding models | Anthropic Claude models |
| Core product feel | OpenAI-native, config-heavy, sandbox-forward local harness | Claude-native, permission/hook-rich local harness |
| Main config idiom | ~/.codex/config.toml, project .codex/config.toml, profiles |
Claude settings and project memory conventions |
| MCP | Native config.toml MCP server declarations shared by CLI/IDE |
Mature MCP ecosystem and tool integrations |
| Hooks | codex_hooks, lifecycle events, plugin-bundled hooks |
Shell, HTTP, or LLM prompt hooks with lifecycle decisions |
| Safety emphasis | Sandbox mode plus approval policy | Permissions, modes, hooks, and bypass controls |
| Sandboxing | Explicit read-only, workspace-write, danger-full-access modes |
Permission modes and isolated/bypass guidance |
| Skills/plugins | Skills as capability packages; plugins as distribution bundles | Skills, slash commands, hooks, subagents, broader mature ecosystem |
| Subagents | Codex docs describe explicit custom subagent workflows and sandbox inheritance | Claude Code has mature subagent/background/task orchestration features |
| App reuse | App Server/JSON-RPC reuse across CLI, IDE, desktop-like embedding | Anthropic Agent SDK and Claude Code extensions |
Claude Code’s hooks documentation describes hooks as shell commands, HTTP endpoints, or LLM prompts that receive lifecycle input and can return decisions. Claude Claude Code’s permissions docs describe allow/ask/deny rules and modes such as default, accept-edits, plan, auto, don’t-ask, and bypass-permissions, with bypass recommended only for isolated environments. Claude Anthropic’s engineering updates also emphasize native IDE integration, checkpoints, terminal UX improvements, an Agent SDK, subagents, hooks, and background tasks. anthropic.com
Codex CLI, by contrast, makes sandbox policy more central in the docs. OpenAI’s sandbox model explicitly describes filesystem/network boundaries and approvals, and the config reference exposes sandbox modes as named settings. OpenAI Developers Its MCP configuration is also particularly explicit in TOML. OpenAI Developers
A fair comparison is therefore:
Claude Code is currently more mature as a programmable governance and workflow ecosystem. Codex CLI is more explicit as a sandboxed, config-driven, OpenAI-native execution harness.
That statement is not permanent. Codex release notes show rapid development in hooks, plugin sharing, MCP elicitations, remote control, workspace-aware diffing, resume/fork UI, and sandbox fixes. OpenAI Developers Claude Code is also evolving rapidly. The open question is whether both products converge on the same feature set or preserve different governance philosophies.
Active critiques
1. Model routing and model-choice transparency
Users increasingly want to know which model is actually running and to control model choice by task phase. A Codex GitHub issue requests a first-class plan_mode_model option so planning and execution can use different models instead of inheriting one global model. GitHub Another issue reports a mismatch where config.toml and the TUI were set to gpt-5.3-codex, but captured output showed gpt-5.2-2025-12-11. GitHub
The underlying critique is not merely “users want knobs.” It is that agent work has phases: planning, search, patching, testing, reviewing, summarizing, and deciding whether to stop. A cheaper or faster model may be sufficient for search; a stronger model may be needed for architectural planning or security review. If the harness routes models opaquely, users cannot tune reliability, cost, or latency.
2. Sandbox UX
Sandboxing is one of Codex CLI’s strongest design choices, but strong boundaries create explanation problems. When a command is denied, wrapped, reinterpreted, escalated, or sent through approval, the user needs a clear mental model. The public issue about a previously allowed timezone date command being routed through a forbidden shell-wrapper shape illustrates the problem: the user’s literal command looked safe, but the emitted execution form crossed policy boundaries. GitHub
This is a classic Security UX tradeoff. Kernel-level or OS-level enforcement is valuable precisely because the model cannot talk its way around it. But developers will only trust the system if policy outcomes are predictable and debuggable.
3. Hook and plugin maturity
Codex hooks and plugins are real, but still in active development. The official docs require a feature flag for hooks and describe discovery through hooks.json or inline configuration; release notes show recent work on bundled hooks, hook browsing/toggling, and plugin sharing metadata. OpenAI Developers+2OpenAI Developers+2 Public issues requesting hook parity and reporting hook behavior gaps show that power users are pushing Codex CLI toward a richer lifecycle system. GitHub
The plugin ecosystem faces the usual platform problem: it must become broad enough to matter, but curated enough to be safe. A plugin can bundle instructions, scripts, MCP servers, and hooks; that is powerful, but it also raises supply-chain and permission questions.
4. Benchmark ambiguity
Codex CLI benefits from strong benchmark results, especially on terminal tasks, but interpreting those results requires discipline. Terminal-Bench measures agent ability in terminal-like tasks; SWE-Bench-family evaluations measure repository issue resolution; internal OpenAI claims measure internal productivity under OpenAI-specific conditions. arXiv+2OpenAI+2 None of these directly answers whether Codex CLI will improve a specific team’s incident response, migration velocity, code review quality, or long-term maintainability.
The practical answer is to build a private benchmark suite. Use your own repositories, seeded bugs, migration tasks, flaky integration tests, policy constraints, and review rubrics. Evaluate the full stack: model, harness, sandbox, hooks, MCP tools, cost, latency, and human review burden.
The open question: convergence or durable divergence?
Codex CLI and Claude Code are converging on a shared set of primitives: local terminal execution, repository awareness, shell tools, MCP, hooks, skills, subagents, permissions, context compaction, IDE integration, and cloud/remote execution. This convergence is not accidental. Those primitives are what real software engineering requires.
The unresolved question is whether they converge architecturally or only functionally.
A convergence thesis says that all serious coding agents will eventually look alike. They will expose MCP servers, lifecycle hooks, project memory files, skill packages, subagents, sandbox modes, model profiles, app-server protocols, and plugin marketplaces. Under this thesis, Codex CLI and Claude Code differ mostly because they are at different maturity points and optimized around different model families.
A divergence thesis says the differences are durable because the products encode different philosophies. Codex CLI’s center of gravity is sandboxed execution plus TOML configuration plus OpenAI model integration. Claude Code’s center of gravity is programmable workflow governance plus a mature hook/permission ecosystem plus Claude-native interaction. Both can add the other’s features, but the default mental model may remain different.
The likely answer is mixed. The surface area will converge because developers demand the same capabilities. The control philosophy may remain distinct because model labs optimize their agents around their own post-training, safety assumptions, ecosystem incentives, and developer workflows. In practice, the winning pattern may not be “Codex or Claude,” but Agent Portfolio Design: use Codex CLI where sandboxed OpenAI-native terminal execution fits, Claude Code where its hook/permission/subagent ecosystem fits, and inter-agent coordination where independent critique is worth the overhead.
Evidence map
| Descriptive source label | What it supports |
|---|---|
| OpenAI Codex CLI documentation | Codex CLI definition, local terminal operation, installation, file editing, shell execution OpenAI Developers |
| OpenAI Codex configuration reference | config.toml, project config, sandbox keys, MCP server configuration, hook events OpenAI Developers+2OpenAI Developers+2 |
| OpenAI MCP documentation | MCP support in Codex CLI/IDE and TOML server configuration OpenAI Developers |
| OpenAI hooks, plugins, skills, and subagents documentation | Extensibility model, plugin marketplace, skill packaging, subagent workflows OpenAI Developers+3OpenAI Developers+3OpenAI Developers+3 |
| OpenAI sandbox documentation | Sandbox-mode-as-policy, approvals, default network restrictions, full-access semantics OpenAI Developers+2OpenAI Developers+2 |
| OpenAI Codex release notes | Rapid development of plugins, hooks, remote control, MCP elicitations, sandbox fixes, terminal UI changes OpenAI Developers |
| OpenAI model release notes and Terminal-Bench paper summary | Coding benchmark claims, Terminal-Bench/SWE-Bench results, long-horizon Codex model claims OpenAI+3OpenAI+3OpenAI+3 |
| Anthropic Claude Code documentation | Claude Code comparison baseline: terminal/IDE agent, MCP, hooks, permissions, Unix-style composability Claude+2Claude+2 |
| Comparative harness writing | Model-harness fit, sandbox-versus-hook framing, CLI-agent landscape Nicolas Bustamante+2Blake Crosley+2 |
| Community ensemble and HCOM examples | Thin public evidence for Codex CLI in multi-agent/HCOM/Council-style workflows GitHub+2GitHub+2 |
| GitHub issue evidence | Active critiques around model routing, hook maturity, sandbox UX, and inbound MCP/session integration GitHub+5GitHub+5GitHub+5 |
Companion entries
Core theory: Agent Harness, Terminal-Native Coding Agent, Model-Harness Fit, Tool-Using Agents, Config-Driven Agent Design, Sandboxing as Policy, Context Compaction, Agent Portfolio Design
Codex-specific practice: Codex CLI Config.toml, Codex Hooks, Codex Plugins, Codex Skills, Codex MCP Servers, AGENTS.md, Codex Subagents, Codex App Server
Comparisons: Claude Code, OpenCode, Gemini CLI, GitHub Copilot CLI, Cursor Agents, Aider, Terminal Agent Landscape
Evaluation: SWE-Bench, Terminal-Bench, Private Agent Evals, Coding Agent Benchmarks, Benchmark Contamination, Long-Horizon Agent Tasks
Deployment patterns: Pair Programming with Agents, Agent Operations, Blackboard Coordination, Agent Ensemble, Codex Council, HCOM, Multi-Agent Code Review
Counterarguments and risks: Security UX, Agent Safety, Prompt Injection in Tool-Using Agents, Plugin Supply Chain Risk, Human Review in Agentic Coding, Model Routing Transparency