Codex CLI Guide 2026: Setup, Sandbox, AGENTS.md & MCP

TL;DR: Codex is a multi-surface coding agent: it reads your codebase, runs commands in an OS-level sandbox, patches files, and delegates tasks to the cloud. Master five systems – config.toml, the sandbox/approval model, AGENTS.md, MCP, and skills – and it becomes a force multiplier. Which model: OpenAI’s models docs now point complex coding and agentic work at GPT-6.1 Sol (gpt-6.1-sol, the CLI’s bundled default since v0.159.1), the hardest end-to-end work at GPT-6-Astra, and focused, repeatable tasks at GPT-6 Luna. Availability depends on plan, client, and workspace settings; GPT-6 Sol and the GPT-5.6 models stay in the picker, and GPT-5.5 retires from Codex for ChatGPT sign-in on October 14, 2026.^146171178 New here? Jump straight to Install and Quick Start. Tracking releases? The latest stable is v0.162.1 (October 9, 2026), two fixes on top of v0.162.0, which turns instant interrupt on by default; Release Highlights opens with a current-state summary (what is on by default, what is still experimental) and then covers each version, and the Changelog lists every guide update.^116178182183

Codex operates as a multi-surface coding agent, not a chatbot that writes code. The CLI reads your codebase, executes commands in a sandbox, patches files, connects to external services via MCP, and delegates long-running tasks to the cloud. It runs locally but thinks globally; the same intelligence powers five distinct surfaces depending on how you work, including the browser extension (Chrome, Edge, Brave, Opera, and Vivaldi) that runs Codex in your browser without taking it over.⁹⁰¹²⁷

The difference between casual and effective Codex usage comes down to five core systems. Master these and Codex becomes a force multiplier:

1. Configuration system: controls behavior via config.toml
2. Sandbox & approval model: gates what Codex can do
3. AGENTS.md: defines project-level operating contracts
4. MCP protocol: extends capabilities to external services
5. Skills system: packages reusable domain expertise

I spent months running Codex alongside Claude Code across production codebases, CI/CD pipelines, and team workflows. This guide distills that experience into the complete reference I wish existed when I started. Every feature includes actual syntax, real configuration examples, and the edge cases that trip up experienced users.

Key Takeaways

• Five surfaces, one brain: CLI, desktop app, IDE extension, cloud tasks, and the browser extension (Chrome, Edge, Brave, Opera, and Vivaldi) all share the same model family, so pick the surface that fits your workflow.⁹⁰
• OS-level sandboxing: Codex enforces filesystem and network restrictions at the kernel level (Seatbelt on macOS, Landlock + seccomp on Linux), not inside containers.
• AGENTS.md is cross-tool: Your project instructions work in Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed, and 60,000+ open source projects. Write once, use everywhere.
• Profiles save context-switching overhead: Define named config presets (fast, careful, auto) and switch between them with --profile.
• Context management matters: the bundled Codex catalog gives GPT-6.1 Sol, GPT-6 Astra, Sol, and Luna and the GPT-5.6 family a 272K context window (the API lists GPT-6.1 Sol, GPT-6 Sol, and Luna at 1.05M); GPT-5.5 provides 400K in Codex until it retires there on October 14, 2026. Use /compact, focused prompts, and @file references to manage token budgets proactively.^83112178

How to Use This Guide

This is a 3,300+ line reference — start where your experience level fits:

The Quick Reference Card at the end provides a scannable summary of all major commands.

Release Highlights: What Changed Recently

The version-by-version record, newest first, for readers tracking Codex’s release train. New here? Skip to Quick Start; nothing below is required to get productive. Verification detail (compares, commit lists, docs checks) lives in the footnotes.

Current State

Codex CLI as of October 14, 2026

• Stable: v0.162.1 (October 9, npm latest), two fixes, after v0.162.0 (October 8), which turns instant_interrupt on by default and adds worktree tools, Command Center pinning, and transcript copying, and v0.161.0 (October 7), which adds /mcp login, voice device selection, API-key model discovery on by default, and the opt-in Daybreak flag.
• Alpha: npm alpha is 0.163.0-alpha.11 (October 14), after alpha.10 on October 13; the 0.163 line has produced no stable.
• Default model since v0.159.1: GPT-6.1 Sol, replacing GPT-6-Astra, including on Amazon Bedrock. Set model in config.toml to keep another. The bundled catalog at v0.162.1 lists the same models as v0.159.1.
• On by default since v0.162.0: instant_interrupt, so new input preempts a model response (instant_interrupt = false under [features] turns it off); the flag stays marked under development.
• On by default since v0.161.0: API-key model discovery (api_key_model_discovery = false under [features] turns it off).
• On by default since v0.158.0: approval for input to elevated terminals (write_stdin_approval = false under [features] turns it off), plus copy-on-select and right-click paste in the fullscreen TUI (copy_on_select = "never", right_click_paste = "off" under [tui]). Guardian thread context is always on; thread_context is ignored.
• On by default since v0.157.0: the fullscreen transcript (fullscreen_transcript = false under [tui]) and background-server autostart (daemon_auto_start = false under [features], or --no-daemon).
• On by default since v0.156.0: /voice, managed worktrees, Guardian parent-compaction reuse.
• Opt-in or experimental: Codex Cloud, code mode and its ranked tool search (code_mode_tool_search, v0.162.0), Daybreak (cli_daybreak, v0.161.0), Guardian history retrieval (guardian_conversation_history_tools, v0.160.0). Experimental context management is not currently available.
• Models: GPT-6.1 Sol for complex coding, GPT-6-Astra for the hardest work, GPT-6 Luna for repeatable tasks. GPT-6 Sol and Luna start on Fast (2.5x credits); GPT-6.1 Sol does not. GPT-5.5 leaves Codex October 14, 2026.
• Pinning: npm install -g @openai/codex@0.162.1, then codex --version.^{176178186187188189}

v0.162.1 (October 9, 2026)

Two fixes, three commits on top of v0.162.0. A TUI crash on asynchronous questions with multiple lines is fixed, with line breaks and complete hyperlink destinations preserved. And the startup failures some v0.162.0 users hit, caused by differences between a running background server’s feature settings and the CLI’s defaults, are gone: the compatibility check now applies only to explicit command-line feature overrides. No defaults, config keys, or models change.

What to do: upgrade, especially if v0.162.0 refused to start while a background server from an earlier version was running.¹⁸⁸

v0.162.0 (October 8, 2026)

instant_interrupt turns on by default. The flag v0.159.0 shipped as opt-in, which lets new input preempt a model response or yield a long-running code-mode call, is on for everyone from this release (PR #51812, merged October 7); it stays marked under development. Set instant_interrupt = false under [features] to restore the old behavior, where typed input waits for the response to finish.

New in the TUI: tools for creating and listing managed Git worktrees from trusted local projects, when the worktrees feature is on, so the model can open a worktree itself (#50148); pinning in the agent Command Center with p, which keeps pinned tasks in a shared Pinned group when the server supports it (#51500); /copy navigates transcript blocks, Ctrl+Insert copies a selection, and tui.mouse_scroll_speed (a finite positive number, default 1.0) tunes mouse-wheel scrolling (#50434, #50215, #50209); URLs are clickable in approval headers, questions, MCP prompts, warnings, and banners, including links that wrap. New TUI threads respect the server’s model and reasoning-summary defaults while keeping explicit launch overrides. codex doctor reports the configured TUI mode, and /status shows the account email again after an account update.

Providers and models: a custom Responses-compatible provider can declare external_web_access and remote_compaction under [model_providers.<name>.capabilities] (#50459). The ultrafast_mode feature ships on, so a model catalog that advertises an Ultra Fast tier (Amazon Bedrock’s Astra models, #50472) can offer it independently of Fast mode; the bundled catalog at this tag lists no such tier. Code mode gains JavaScript helpers for streaming promise results and an opt-in ranked tool search (code_mode_tool_search). apply_patch always preserves existing CRLF line endings, and the apply_patch_preserve_line_endings flag is removed. Retryable Responses and WebSocket failures honor the server’s Retry-After advice.

Sandbox and platform: Linux sandbox startup with multiple denied files is fixed, writable sandbox-construction executables are rejected, and ripgrep configuration can no longer weaken deny-glob masks; Windows 10 regains ordinary drive-letter file access, sandbox temp permissions match the child process, archive checksum verification works with PowerShell 7 module paths, and Windows releases ship a signed PowerShell installer.

What to do: upgrade; if you relied on typing ahead without interrupting the model, set instant_interrupt = false.¹⁸⁷¹⁸⁹

v0.161.0 (October 7, 2026)

Cut from 0.161.0-alpha.13.1 plus one release commit, 155 commits ahead of v0.160.1. Its release notes list GPT-6.1 Sol as the new default (#49318, #49339), but those are the catalog changes v0.159.1 already shipped: the bundled models.json at this tag is byte-identical to v0.160.1’s, so nothing changes for anyone on 0.159.1 or later.

New: /mcp login <name> signs in to an MCP server from a running terminal session (#49290). Voice device selection: choose your microphone, speaker, and microphone input channels for /voice conversations, with preferences saved locally (#49437, #49836). API-key model discovery is on by default (api_key_model_discovery, promoted to stable, #49807): signed in with an OpenAI API key against an endpoint that supports it, Codex refreshes the model catalog from the API instead of relying only on the bundled list; api_key_model_discovery = false under [features] turns it off, and the change takes effect in a new session. Amazon Bedrock supports multi-agent V2 and Ultra reasoning on compatible models, and Bedrock Mantle accepts AWS GovCloud regions (#49345, #49813).

Daybreak (opt-in). A new cli_daybreak flag, off by default and under development, adds Daybreak controls to the CLI: a /daybreak toggle, indicators, and automatic Cyber access-program routing, for ChatGPT sign-ins on the OpenAI provider whose account and model catalog advertise support. Turn it on with --enable cli_daybreak or cli_daybreak = true under [features]; a saved daybreak = true preference alone does nothing. Independently, codex exec --cyber-access-program <standard|daybreak_blue|daybreak_red> (and the TypeScript SDK’s cyberAccessProgram) requests a Cyber access program for one turn, with or without the flag, and leaves the saved choice unchanged (#49856 through #49861, #49939, #51207). The bundled catalog already carries hidden gpt-daybreak-blue-latest and gpt-daybreak-red-latest entries.

Fixes: an approved filesystem escalation can grant broader write access while keeping denied reads and network restrictions, and background tasks keep their originating turn’s permissions; explicit launch permissions survive terminal reconnects; elevated Windows terminal sessions can start with an embedded server; Enter submits buffered input after paste detection expires, in Vim insert mode too; thread resume includes the latest committed history, and startup detects recoverable SQLite corruption earlier, keeping damaged databases as backups; Responses retries and the WebSocket-to-HTTP fallback honor server retry guidance. The authentication docs now say credentials may live in the keyring rather than always in auth.json.

What to do: upgrade. Nothing here changes a default you would notice unless you sign in with an API key, in which case check /model for the discovered catalog.¹⁸⁶¹⁸⁹

v0.160.1 (October 5, 2026)

A fix for remote MCP servers on Windows. When Codex on a macOS or Linux host launches a stdio MCP server on a remote Windows executor, and that server’s config sets explicit remote environment variables, Codex now passes SYSTEMROOT, TEMP, and TMP through as well, so the Windows process keeps the startup environment it needs. Variables you did not request, secrets included, stay excluded. The release is one backport on top of v0.160.0 and changes no defaults, config keys, or models.

What to do: upgrade if you run remote stdio MCP servers on a Windows executor from a Unix host.¹⁸³

v0.160.0 (October 1, 2026)

The 0.160 line’s stable release, cut from 0.160.0-alpha.6.1 plus one backport. No default changes. The bundled model catalog at the tag is byte-identical to v0.159.1 and v0.159.2, so GPT-6.1 Sol stays the default, and the two new feature flags ship off. The backport (#49763) brought the frozen 0.160 candidate, branched before v0.159.1, up to the 0.159 maintenance line: the GPT-6.1 Sol bundled and Amazon Bedrock catalogs and the account-security reminders from v0.159.3. Without it, 0.160 would have shipped without GPT-6.1 Sol.

Opt-in Guardian additions (both under development, off by default):

• Guardian can read earlier user messages. Set guardian_conversation_history_tools = true under [features]. With Apps enabled, the reviewer gets user_message.search_messages and user_message.read_messages through the parent session’s own Apps connection, so it can check earlier instructions, restrictions, and revoked permissions before approving an action with side effects. Each call rechecks the parent’s current app and tool policy. Responses are capped at an estimated 4,000 tokens by default (auto_review.conversation_history_max_output_tokens), and auto_review.experimental_conversation_history_prompt replaces the built-in retrieval instructions.
• Handoff-aware root context (guardian_root_handoff_context): when Guardian reviews a worker agent’s action, it selects the three root messages before each handoff to that worker or its ancestors, plus the three latest root messages, so a recent cancellation stays visible.

Always on: encrypted agent messages now appear in Guardian transcripts, in order, instead of being dropped.

TUI changes: in a folder with no project config and no saved trust decision, a new session can start with workspace-write permissions and granular approvals, but only when local execution, your config, and managed policy all allow it. Resumed sessions restore their saved permissions unless you override them, and /cd can ask for folder trust with a “Keep current directory” option. The agent command center gains a “Show more” row that loads older tasks ten at a time. On local Linux X11 terminals (not Wayland, SSH, tmux, WSL, or VS Code), fullscreen transcript selections go to the primary selection, and middle-click pastes into the composer. The fullscreen status line shows Plan mode (shift+tab to cycle) when there is room. The Pro tiers now read “Pro 100,” “Pro 200,” and “Pro 500” in /status and analytics. Startup tips point to the desktop app for your platform instead of plan or Fast-mode promotions, and queued messages that were never sent resume after a reconnect without duplicates.

Providers and connections: the TUI keeps an app server’s provider, reasoning-summary, and verbosity settings, shows the right sessions in resume and fork history, and hides reasoning-summary settings in /status for server connections. A provider with an explicit model catalog (model_catalog_url) now gets only that catalog: no bundled models are merged in, metadata matches the exact model ID, a failed refresh discards cached entries instead of reusing them, and a startup with no available model reports a configuration error unless model is set. When a content filter stops a response, the retry tells the model to explain the limitation, offer a permitted alternative, and continue other work.

Fixes: Windows sandbox PowerShell fallbacks, ACL repair for long runtime paths, and no console windows from background helpers; subagents keep environments that are still starting; SQLite no longer stalls at connection setup and reports initialization errors instead of timeouts. The log database reclaims unused space in the background, and plugin loading caches parsed manifests and reuses HTTP connections. The provider docs now say that requires_openai_auth credentials use the backend chosen by cli_auth_credentials_store, and that env_key names the environment variable holding the API key.

What to do: upgrade. If a custom provider sets model_catalog_url, make sure its catalog lists every model you select.¹⁸²

v0.159.3 (September 30, 2026)

Optional account-security reminders. Local TUI sessions signed in with ChatGPT on the OpenAI provider can show a dismissible banner asking you to finish account security setup, with a button that opens chatgpt.com. The server decides who sees it; the CLI fetches the notice in the background without blocking a turn, shows nothing when the state is unknown, skips remote workspaces and FedRAMP accounts, and remembers a dismissal across threads and reconnects. Usage banners take priority. It is the release’s only change, and v0.160.0 carries the same code.

What to do: nothing. The reminder is optional.¹⁸⁴

v0.159.2 (September 29, 2026)

A Windows fix for flashing console windows. On Windows, Codex no longer opens a console window each time it starts a background process. That covers shell-tool commands, hooks, Git and npm calls, Amazon Bedrock credential refreshes run without a terminal, doctor checks, sandbox setup refreshes, and commands in the legacy Windows sandbox. Commands that need your terminal still inherit its console. The release is one backport of two fixes from main, published about three and a half hours after v0.159.1. It changes no defaults, config keys, or models, and the new launch helper behaves as before on macOS and Linux.

What to do: on Windows, upgrade if console windows flash while Codex works, especially with the background server installed.¹⁸⁰

v0.159.1 (September 29, 2026)

GPT-6.1 Sol becomes the default model. When config.toml sets no model, the CLI now starts on GPT-6.1 Sol (gpt-6.1-sol) instead of GPT-6-Astra, and GPT-6.1 Sol replaces GPT-6 Sol as the default in the Amazon Bedrock Mantle and Runtime catalogs. The /model picker lists it first, as “Latest workhorse model for coding and everyday work,” followed by GPT-6-Astra, GPT-6 Sol (now “Previous generation workhorse model”), GPT-6 Luna, and the older models. Saved choices are not migrated: a config that names gpt-6-sol or gpt-6-astra keeps that model, and the migration prompts for older GPT-5 selections still point to GPT-6 Sol or GPT-6 Luna.

OpenAI’s docs added the model the same day and now recommend it for complex coding and agentic workflows: “near-Astra performance for complex work at a lower cost than Astra.” It costs 50 credits per 1M input tokens (2.5 cached, 250 output), and the Plus band is 15-160 messages. Two catalog details differ from GPT-6 Sol: it has no default service tier, so a session starts at Standard speed rather than Fast, and its default reasoning effort is low rather than medium. The launch rollout covers Plus, Pro, Business, Enterprise, and Edu; Enterprise and Edu keep it off until an administrator enables it, and Free and Go are not included at launch.

What to do: upgrade, then check the model in /status. If your account does not have GPT-6.1 Sol yet, pin one it does have with model in config.toml or -m.¹⁷⁸

v0.159.0 (September 29, 2026)

Cut from 0.159.0-alpha.13, about 27 hours after v0.158.0. Several items in its release notes shipped earlier, in v0.158.0, as backports: the Windows console-window and launcher fixes, Markdown-preserving copy, the welcome screen and turn tips, and the sign-in fixes. The tui.prompt_suggestions setting the notes list as removed never appeared in a stable release.

New in this release:

• instant_interrupt (opt-in, under development): new input preempts a model response or yields a long-running code-mode call. Set instant_interrupt = true under [features] to try it. On by default since v0.162.0.
• The warnings viewer dismisses the warnings you have seen when it closes; press k to keep one for later.
• You can scroll the transcript while deciding whether to implement a plan.
• Mermaid rendering handles more flowchart edges, labels, and node groups.
• Blank sessions keep their drafts when you switch tasks, and threads can be archived before their first turn.
• /status renders without borders and wraps long values.
• App-server clients can page thread history from a specific item.

Sandbox changes: approved commands keep explicit filesystem denials, .aws directories under writable roots are protected by default (explicit rules still override), network-enabled macOS sandboxes allow TLS trust evaluation, and execution environments that require a proxy now get one. The bundled plugin-creator skill is removed.

What to do: if a sandboxed task writes under .aws, expect it to be blocked unless you add an explicit rule.¹⁷⁷

v0.158.0 (September 28, 2026)

The 0.158 line’s stable release, cut from 0.158.0-alpha.15.4: alpha.15 plus sixteen backports, including the four Windows fixes from v0.157.1. It is 207 commits ahead of v0.157.0.

Defaults that change:

• Terminal input approval is on. When Codex sends input to a running command that has elevated permissions (extra permission grants, a sandbox bypass, or a policy that changed since the command started), the input needs approval first. Runtime-only grants, such as those plugins use for metrics, no longer trigger a review. To turn it off, set write_stdin_approval = false under [features].
• Copy-on-select in the fullscreen transcript: mouse selections are copied when you release the button. The default, auto, skips direct terminals that forward their own copy shortcut (Ghostty 1.2+, Kitty on macOS, Windows Terminal, and VS Code on Windows). Copies keep Markdown formatting. Set copy_on_select = "never" (or "always") under [tui].
• Right-click paste in the fullscreen TUI on Windows, WSL, and Linux. Set right_click_paste = "off" under [tui], or "on" to add macOS.
• Guardian thread context is always on. The v0.157.0 off-switch is gone: thread_context under [features.guardianv2] is ignored, including in profiles, and Codex shows a notice asking you to remove it.

Models and plans: GPT-5.4 leaves the bundled and Bedrock catalogs, and saved GPT-5.4 selections still get the migration prompt to GPT-6 Sol. Codex recognizes the Pro Max plan and labels the Pro tiers “Pro,” “Pro (More),” and “Pro (Max).” Reasoning shortcuts can reach Max.

Also new: MCP servers that need a pre-registered OAuth client secret (codex mcp add --oauth-client-secret), bearer tokens for exec-server WebSocket connections, transparent backgrounds for generated images, and multiline command previews in /ps. Fixes cover Windows sandbox failures (ordinary Windows 10 paths, rejected stored credentials, large permission policies), Linux sandbox startup with nested writable roots, Git metadata protection across writable roots, macOS path aliases in patch approvals, and Guardian reviews that now retry instead of aborting when you send a message mid-review.

What to do: if automation sends keystrokes to elevated commands, expect approval prompts or turn the feature off, and remove thread_context from your config.¹⁷⁶

v0.157.1 (September 26, 2026)

A Windows patch of four fixes backported from main. Codex no longer opens a console window when it starts the code-mode host or a local stdio MCP server. The background server can launch when Windows leaves the process inside an outer job object, and a detached background server no longer holds the launcher’s output pipes open, which could leave the calling command waiting after the launcher exited. The GitHub release notes and the changelog entry say only that highlights “could not be determined”; the list above comes from the release’s commits.

What to do: upgrade if you run Codex on Windows. The four fixes are Windows-only.¹⁷⁴

v0.157.0 (September 25, 2026)

The release that flips three more defaults.

• The fullscreen transcript is on by default. The fullscreen UI that v0.156.0 offered through /tui is now what a session opens in, including when config has no [tui] section. To keep terminal scrollback, pick Scrollback in /tui or set fullscreen_transcript = false under [tui]; --no-alt-screen and tui.alternate_screen = "never" still take precedence. Shift-click now extends a transcript selection.
• The background server starts automatically for eligible interactive launches, and the option leaves /experimental. Launches with --no-daemon, --oss, --profile, or most -c overrides do not use it. If a running server’s settings do not match the session, Codex offers to run without it, restart it with the required settings, or cancel (the default). To turn automatic startup off, set daemon_auto_start = false under [features].
• Guardian thread context is on by default for synchronous and asynchronous reviews, independent of the Guardian v2 enabled toggle. To turn it off, set thread_context = false under [features.guardianv2].

Models: GPT-6 Sol and Luna, first shipped in v0.156.1, are in this release too, and the Amazon Bedrock catalogs now carry them, with GPT-6 Sol replacing GPT-5.6 Sol as the Bedrock default. GPT-5.6 Sol loses its ultrafast service tier, leaving Fast. The bundled catalog no longer marks GPT-6-Astra as supporting experimental context management (see Context Management).

Also new: an f shortcut forks a conversation that is open in another app, keeping drafts and queued prompts; /import works in remote and background-server sessions; and the terminal renders Unicode bullets, checkboxes, and aligned equations. Fixes keep voice conversations running when you switch threads, recover unsent answers when a turn ends, respect tmux mouse settings, route realtime connections and standalone web search through configured proxies, retry transient file uploads with a five-minute timeout, and enforce network restrictions across redirects and open HTTP and WebSocket connections. On Windows, sandbox object access is limited to the runner’s logon session.¹⁷⁴

v0.156.1 (September 23, 2026)

A one-change patch that brings GPT-6 Sol and GPT-6 Luna to the stable CLI. Both now appear in the /model picker below GPT-6-Astra, which stays first and remains the bundled default when config.toml sets no model. The picker relabels the GPT-5.6 family as older models (GPT-5.6 Sol reads “Older coding model for complex work”) and GPT-5.5 as a “Legacy coding model.” When you approach a rate limit, the switch prompt now suggests gpt-6-luna instead of gpt-5.6-luna.

If your config names an older model, expect a one-time migration prompt: saved selections of gpt-5.6-sol, gpt-5.6-terra, gpt-5.5, and gpt-5.4 point to GPT-6 Sol, and gpt-5.6-luna and gpt-5.4-mini point to GPT-6 Luna. The Amazon Bedrock catalogs do not change in this release: they carry no GPT-6 Sol or Luna, and GPT-5.6 Sol stays the Bedrock default.

One cost detail the docs do not mention: the bundled catalog sets Fast (priority) as the default service tier for GPT-6 Sol and Luna, so a TUI session with no service_tier set can start in Fast mode, which ChatGPT sign-in bills at 2.5x Standard credits. Check with /fast status; /fast off switches to Standard.

What to do: upgrade, then try codex -m gpt-6-sol on a familiar task. Availability depends on your plan, workspace settings, and the rollout; Enterprise administrators must enable the new models first.¹⁷¹

v0.156.0 (September 22, 2026)

The release that flips three defaults at once; the docs changelog announced the first two the same day.

• Voice is on by default. /voice starts a live conversation on supported builds without a visit to /experimental. New alongside it: a configurable F8 toggle, a /voice settings picker for the voice used in future conversations, bundled voice runtimes for Linux and Windows, and reduced-motion support.
• Managed worktrees are on by default. --worktree and /worktree no longer need a feature flag. Worktree sessions can attach to an existing local daemon and can be created from the agents overview.
• Guardian parent-compaction reuse is on by default: when Guardian restarts a review session, it can reuse the parent thread’s encrypted compaction.

How to turn each off is in the /voice and /worktree rows of the slash-command table and in the Guardian section.

Also new: an optional fullscreen TUI, chosen with /tui, with transcript search, mouse selection and copy, right-click copy, clickable links, and a warnings viewer; six bundled themes in the /theme picker; the /usage analytics dashboard; Mermaid diagrams and TeX math rendered in the terminal, each with its own toggle; a /daemon menu and a --no-daemon flag; and reasoning summaries off by default for new TUI threads. Security fixes close Windows inbound-traffic, privileged-socket, and read-only-file-handle sandbox gaps, and codex doctor no longer echoes config values in its errors. Bug fixes keep streamed answers after failed or interrupted turns, repair clipboard forwarding in tmux and SSH, restore Plan mode on resume, and let login recover through system proxies.¹⁶⁹

v0.155.1 (September 18, 2026)

A one-fix hotfix. On 0.155.0, a new local TUI thread with no model_reasoning_summary in config requested detailed summaries, and providers that do not support reasoning summaries rejected the request outright. 0.155.1 restores none as the fallback, so an unset key requests no summaries. Explicit auto, concise, and detailed settings were always honored and still are. The same one-line change also landed on main and shipped in 0.156.0.

What to do: if new TUI sessions on 0.155.0 failed against a non-OpenAI or self-hosted provider, upgrade. If you want summaries, set the key explicitly (see the config reference).¹⁵⁸

v0.155.0 (September 17, 2026)

Voice arrived in the stable TUI as an experimental, opt-in feature: /voice opened a live conversation with a streaming transcript and microphone controls, enabled through /experimental on supported builds, with a configurable mute shortcut and signed voice resources in the macOS packages. v0.156.0 turned it on by default five days later. Managed worktrees stayed off by default in this release.

Also in 0.155.0:

• MCP user verification: Touch ID verification of MCP requests, signed by the Secure Enclave, in local TUI sessions on supported Macs, with workspace-scoped identity restriction and native verification in MCP tool continuations.
• The Windows /sandbox-add-read-dir slash command is removed.
• Worktree management: hide, archive, and delete worktree sessions in the agents overview, see ownership details, and confirm before deleting a clean managed worktree.
• Live reasoning summaries stream in the TUI status row, with completion timestamps on finished work.
• Daemon: configurable update schedules, a codex app-server daemon update command, and thread recovery after daemon restarts.
• Amazon Bedrock AWS credential commands, and Python SDK publishing aligned with stable CLI releases.

Security fixes close WSL interop escapes and shell-snapshot credential exposure. Memory v2 lands as storage and consolidation groundwork only, not a usable feature.¹⁵⁶

v0.154.0 (September 9, 2026)

This release was cut at roughly the 0.154.0-alpha.6 boundary, so everything that first appeared in alpha.7 (live TUI voice, MCP user verification, Memory v2, daemon auto-update configuration, reasoning-effort pinning) waited for 0.155.

Removed: codex mcp-server and the standalone codex-mcp-server binary. Move integrations to the app-server protocol or the Codex plugin for Claude Code; codex mcp, which connects Codex to external MCP servers, is unaffected (see Running Codex AS an MCP Server). The legacy Guardian approval review paths are gone too, and approvals are now rejected when new user instructions invalidate them.

New:

• Experimental managed worktrees via --worktree or /worktree, with codex exec support and a TUI worktree browser.
• Asynchronous user messages: answer inline questions while Codex keeps working, without losing your draft.
• Windows service support: sandbox provisioning, the app-server daemon on Windows, and managed daemon updates.
• Remote permission profiles, discovered from the app server and selectable by name in the TUI.
• Vim R replace mode, live context-compaction status, and experimental context management gated by model capability at session startup.

Security: PATH helpers no longer run before workspace trust is established, and the macOS sandbox is hardened against terminal input injection. MCP connections coordinate OAuth token refreshes, remote resume and fork keep saved permissions, and resuming a conversation open in another app shows a read-only transcript. Voice shipped only as runtime infrastructure, and the first Daybreak code references landed with no public docs.¹⁵²¹⁵³

v0.153.3 and v0.153.4 (September 4, 2026)

Same-day patches that carried the GPT-6-Astra launch into the CLI. v0.153.3 added Astra to the Amazon Bedrock catalogs (GPT-5.6 Sol stayed the Bedrock default) and corrected Astra’s async-clarification guidance. v0.153.4 put Astra in the model picker, made it the bundled default when no model is configured, and qualified async-question guidance by tool availability.

What to do: Astra works with -m gpt-6-astra from v0.153.1 and appears in the picker from v0.153.4; no minimum CLI version is documented, so treat those as the floors. If your account is not entitled to the model the bundled default selects, set model explicitly in config.toml rather than relying on the default.^145146147148

v0.153.1 and v0.153.2 (September 3, 2026)

v0.153.1 makes Guardian’s computer-use scoring honor model requirements: computer-use-only scoring and fast approval decisions run only when the active model’s metadata sets node_repl_auto_review_required, and a model switch that skips scoring invalidates prior or in-flight scores, so switching back cannot revive a stale approval. The release body lists only a backported GPT-6-Astra catalog entry, configurable through the API; the picker and default did not change until v0.153.4. v0.153.2 corrects the Astra Fast-tier description from “1.5x” to “2x speed, increased usage” (display text only).¹⁴²¹⁴³

v0.153.0 (September 3, 2026)

• Vim undo and redo: u and Ctrl+R restore complete composer drafts, including pasted content and image attachments; vim_normal.redo is a configurable keymap action.
• Remote plugin marketplaces: the plugin CLI can list, install, and remove remote plugins, and codex plugin list shows source, version, install policy, and authentication policy.
• tui.auto_recap = false turns off automatic recaps; manual /recap still works.
• Earlier rate-limit warnings for Plus and Team when less than half the allowance remains in a roughly five-hour window; other plans keep the 75/90/95% thresholds.
• Guardian scope follows approval mode: Full Access skips Guardian reviews for confirmation-only actions, and User approval mode skips background scoring and prewarming.
• features.context_management.experimental_mode (off by default) enables token-budget context, history notes, and the new_context tool for eligible Plus, Pro, and Pro Lite sessions on the Codex backend.
• tui.disable_paste_burst replaces the top-level key, which still works as a fallback.

Fixes: TUI sessions reconnect after an app-server drop with drafts intact, Guardian review history survives compaction, restarts, and forks, and remembered MCP approvals are scoped to the selected account.¹⁴⁰

v0.152.0 and v0.152.1 (September 1, 2026)

update_plan became opt-in: tools.update_plan.enabled defaults to false, and while it is off the bundled update_plan guidance is removed from model, collaboration-mode, multi-agent, compaction, prewarm, and goal-continuation prompts (see Plan Mode & Collaboration). Also new: Vim search with / and ? plus n/N, composable with operators, with fresh drafts starting in Insert mode; actionable rate-limit banners; credential-refresh progress, including Amazon Bedrock reauthentication; package-style MCP server names (:, @, /, and . are allowed); MCP openai/elicitation form requests; a per-tool MCP output_token_limit; cloud task credentials restricted to trusted origins; configurable thread/shellCommand timeouts; and token budgeting on by default through model metadata. v0.152.1 lets Guardian approval review source its Node REPL policy from model metadata.¹³⁸¹³⁹

v0.151.0 (August 29, 2026)

• /recap summarizes the conversation on demand, and Codex recaps eligible idle, unfocused conversations automatically.
• Code-mode hosts drop the WebSocket transport (stdio and gRPC only).
• Durable threads default to paginated history where the store supports it.
• The persistent reasoning effort arrives with clock tools and bundled proactivity guidance.
• Guardian v2 defaults to computer-use reviews with images.
• Vim gains f/F/t/T find and till motions plus gg/G.
• Input to escalated terminals can require fresh approval (write_stdin_approval, off by default).
• A configurable grace period for optional MCP servers (mcp_optional_startup_grace_ms, default 1,000 ms), and extensions can inspect or replace MCP tool results.

Fixes stop /cd from weakening sandbox restrictions and stop stale Guardian classifications from authorizing actions after permission changes. The release body lists only the last few PRs; the full change set is in the compare.¹³⁴¹³⁵

v0.150.0 and v0.150.1 (August 26-27, 2026)

Hooks gain an Interrupt event that runs when an active top-level turn is interrupted (1-second default timeout, 3-second cap, never for subagents). /copy opens a picker for the full response, individual code blocks, or blockquotes. Tasks become addressable with @ mentions, agents can read, create, and message tasks, and /rename suggests an editable title. Markdown links render as clickable labels, shortcuts can cycle permission modes, Vim gains . repeat, and untrusted projects no longer supply project-level AGENTS.md instructions. features.network_proxy.credential_broker and Guardian v2’s review_scope.computer_use_only arrive as configurable, default-off surfaces. v0.150.1 counts retained images toward remote compaction’s token budget.¹³²¹³³

v0.149.0 and v0.149.1 (August 20-24, 2026)

The untrusted approval policy is retired; move configs that name it to on-request. New: an interactive codex agents dashboard, /cd, /pwd, and /cwd, codex queue for messaging existing local or remote sessions, more Vim change motions, a broader codex doctor (endpoint protection, network and proxy failures, desktop-app state, update connectivity), and max/ultra reasoning efforts in the SDKs. Resumed and forked threads restore their permission profile. v0.149.1 adds codex exec --thread-source <SOURCE> (user, subagent, memory_consolidation, or a feature name; threadSource in the TypeScript SDK).

Pricing in the same window: OpenAI cut GPT-5.6 Sol pricing by more than 20% for three months from August 21 (through at least November 21, 2026), and the Codex credit rate for Sol dropped from 125/12.5/750 to 100/10/500 credits per 1M input, cached, and output tokens.^120121126

v0.147.0 and v0.148.0 (August 7-18, 2026)

v0.147.0 removes codex exec --full-auto (deprecated since v0.128); use --sandbox workspace-write plus an approval flag or profile. It also adds --approve-for-me, portable Agent Plugins with search across catalogs, the opt-in MCP 2026-07-28 protocol, and conversation sections. v0.148.0 adds /export to Markdown, codex exec fork, estimated credits or cost in /status, Amazon Bedrock Runtime as a built-in provider, asynchronous and MCP-invoking hooks, and sandbox restrictions that fail closed on denied or unreadable paths.¹¹⁶¹¹⁸

Earlier Releases (May-July 2026)

• v0.146.0 and v0.146.1 (July 29, August 5): configured proxies cover every transport; Agent Plugins manifests plus the Amazon Bedrock and Claude Code marketplaces; session naming with thread pinning; executor-provided skills; hardened automatic-review defaults for cyber-capable models.¹¹⁴¹¹⁵
• v0.145.0 (July 21): /import from Cursor as well as Claude Code; voice returns as streaming realtime V3 conversations; the opt-in multi-agent v2 experience is stabilized; experimental paginated thread history and Amazon Bedrock login; bundled GPT-5.4 selections migrate to GPT-5.6 Terra and Luna. v0.144.6 set the GPT-5.6 context windows to 272,000 tokens.¹¹¹¹¹²
• v0.140.0 (June 15): /usage, codex delete and /delete, /import from Claude Code, the unified @ mentions menu, Amazon Bedrock API-key authentication, and encrypted local storage for CLI and MCP OAuth credentials; the old /realtime voice controls were removed.¹⁰²
• v0.139.0 (June 9): code mode can call web search directly, tool schemas keep oneOf/allOf, codex doctor reports editor and pager details, and marketplace sources appear in JSON output.¹⁶⁵
• v0.138.0 (June 8): /app hands a CLI session to the desktop app, and parent-to-subagent task text is encrypted in multi-agent v2.¹⁶⁶¹⁰⁸
• v0.137.0 (June 4): multi-agent v2, F13-F24 TUI keybindings, and a v1 skills extension.¹⁶⁷
• v0.132.0 through v0.135.0 (May 20-28): local conversation history search, --profile as the primary profile selector, goals on by default, permission-profile inheritance and managed requirements.toml, codex remote-control start and stop, richer codex doctor and /status, Vim text objects, named permission profiles in /permissions, Python SDK auth and Sandbox presets, and codex exec resume --output-schema. The May 21 app update added Appshots, Goal mode GA, and opt-in locked Computer Use.^{96979899100101192}

Legacy --full-auto is removed as of v0.147.0, and js_repl remains removed.^86878991116

Stability note: Stable, documented surfaces: the core CLI and TUI, sandboxing and approval policies, config.toml, AGENTS.md, skills, hooks, plugins, multi-agent tools, goals, permission profiles, /voice and managed worktrees (default since v0.156.0), the fullscreen transcript and automatic background-server startup (default since v0.157.0), terminal input approval, copy-on-select, and right-click paste (default since v0.158.0), and instant interrupt (default since v0.162.0, still marked under development). Browser, Computer Use, and Appshots are documented user-facing surfaces whose availability depends on platform and plan. Experimental or under development: Codex Cloud, code mode and code mode tool search, Memory v2, the local agent message board, Daybreak (cli_daybreak, v0.161.0), the Guardian history and handoff-context flags (v0.160.0), and anything marked [EXPERIMENTAL] in this guide or listed under /experimental; these can change between releases. Experimental context management is, per the config reference, “not currently available.” Removed: --full-auto (v0.147.0), the untrusted approval policy (v0.149.0), codex mcp-server (v0.154.0), the Guardian thread_context opt-out (v0.158.0), and js_repl.

Alpha channel: alpha builds ship several times a day, release bodies on the alpha lines are stubs, and out-of-band builds cut from older bases appear regularly. At least twice the npm alpha tag pointed at one of them, so @alpha installed a build older than latest. The 0.158 line ran from 0.158.0-alpha.2 (September 23) to alpha.15 (September 25); its stable, v0.158.0 (September 28), was cut from the out-of-band build 0.158.0-alpha.15.4, alpha.15 plus sixteen backports, and was npm latest until v0.159.0 published 27 hours later. The 0.159 line ran from alpha.1 (September 25) to alpha.13 (September 28) and shipped as v0.159.0 from alpha.13. The 0.160 line reached 0.160.0-alpha.6 (September 29) and froze there; 0.161.0-alpha.1 is alpha.6 with only the version number changed. On September 30, 0.160.0-alpha.6.1 added to alpha.6 the one v0.159.2 Windows console fix it lacked. The same day, the 0.159 line shipped one more patch, v0.159.3. The 0.160 line then shipped stable as v0.160.0 (October 1), cut from alpha.6.1 plus one backport, and v0.160.1 (October 5). The 0.161 line has produced alphas and out-of-band backports, the latest 0.161.0-alpha.13.1 (October 6), but no stable; it is not called skipped, because no higher version has shipped stable. alpha now points at 0.162.0-alpha.16. If you track alphas, check npm view @openai/codex dist-tags and install an exact version rather than @alpha.^176179181185 A dated history of how recent alpha lines resolved into stable releases is in ¹⁷³. The 0.161 line shipped as v0.161.0 on October 7 from 0.161.0-alpha.13.1 (one release commit on top of it); v0.162.0 followed on October 8 from 0.162.0-alpha.18.1, while 0.162.0-alpha.20 ran 52 commits ahead of that stable cut; v0.162.1 added three commits on October 9; alpha was 0.163.0-alpha.5 on October 10, moved through alpha.8, alpha.9, and alpha.10 on October 13, and is 0.163.0-alpha.11 as of October 14.^189190191

How Codex Works: The Mental Model

Before diving into features, understand how Codex’s architecture shapes everything you do with it. The system operates across five surfaces backed by a shared intelligence layer:

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                       │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐   │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │   │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘   │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
│  ┌──────────┐                                           │
│  │ Browser  │  Signed-in browser workflows              │
│  │Extension │  (launched May 2026)                      │
│  └──────────┘                                           │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                 │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (on-request → never)       │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions             │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                             │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens         │
└─────────────────────────────────────────────────────────┘

Core Layer: The GPT model family powers everything. As of September 29, 2026, the current generation is GPT-6: gpt-6.1-sol for complex coding and agentic work (the bundled CLI default when no model is configured, since v0.159.1), gpt-6-astra for the hardest end-to-end work, gpt-6-luna for focused, high-volume tasks, and the previous-generation gpt-6-sol. The GPT-5.6 models (Sol, Terra, Luna) remain available during the rollout; gpt-5.5 (400K context in Codex, 1M in the API) retires from Codex for ChatGPT sign-in on October 14, 2026, and gpt-5.4 retired from Codex on August 31, 2026.^{83117146148149171178} It reads files, writes patches, executes shell commands, and reasons about your codebase. When context fills, Codex compacts the conversation to free space. This layer costs tokens.

Security Layer: Every command Codex runs passes through an OS-level sandbox. On macOS, Apple’s Seatbelt framework enforces kernel-level restrictions. On Linux, Landlock + seccomp filter filesystem and syscall access. The sandbox operates at the kernel level, not inside containers. The approval policy then decides when to ask for human confirmation.

Extension Layer: MCP connects external services (GitHub, Figma, Sentry). Skills package reusable workflows that Codex loads on demand. Apps connect to ChatGPT connectors. Web search adds real-time context from the internet.

Surface Layer: CLI for terminal power users and automation. Desktop app for multi-threaded project management. IDE extension for edit-compile-test loops. Cloud for async tasks that run independently.

The key insight: Most users only use one surface. Power users use all five: Cloud for long-running tasks, CLI for deterministic repo operations, IDE extension for tight coding loops, the desktop app for planning and coordination, and the browser extension for signed-in browser workflows.

Table of Contents

1. How Do I Install Codex?
2. Quick Start: Your First Session
3. Core Interaction Surfaces
4. Configuration System Deep Dive
5. Which Model Should I Choose?
6. What Does Codex Cost?
7. Decision Frameworks
8. How Does the Sandbox & Approval System Work?
9. How Does AGENTS.md Work?
10. Hooks
11. What Is MCP (Model Context Protocol)?
12. Code Mode
13. JavaScript REPL Runtime
14. What Are Skills?
15. Plugins
16. Plan Mode & Collaboration
17. Memory System
18. Session Management
19. Non-Interactive Mode (codex exec)
20. Codex Cloud & Background Tasks
21. The Codex Desktop App
22. GitHub Action & CI/CD
23. Codex SDK
24. Performance Optimization
25. How Do I Debug Issues? – including codex doctor
26. Enterprise Deployment
27. Best Practices & Anti-Patterns
28. Workflow Recipes
29. Migration Guide
30. Quick Reference Card
31. Changelog
32. References

How Do I Install Codex?

Package Managers

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

# Upgrade to latest
npm install -g @openai/codex@latest

How Do I Update, Downgrade, or Uninstall the Codex CLI?

Codex ships a self-update command as of v0.128.0; everything else runs through whichever package manager installed it.⁸⁶ As of v0.146.0, release artifacts, channel metadata, and installer aliases are served from OpenAI-hosted release infrastructure, with GitHub as a fallback.¹¹⁴ If your network allowlists GitHub for Codex installs and updates, add the OpenAI release host too — the fallback means an allowlist miss degrades quietly rather than failing loudly.

# Check what you are running
codex --version                          # -> codex-cli 0.162.1
npm view @openai/codex version           # Latest published version

# Update
codex update                             # Built-in self-update (v0.128.0+)
npm install -g @openai/codex@latest      # Or update via npm
brew upgrade --cask codex                # Or via Homebrew

# Pin or downgrade to an exact version
npm install -g @openai/codex@0.144.6

# Uninstall
npm uninstall -g @openai/codex
brew uninstall --cask codex
winget uninstall OpenAI.Codex

Pinning is the right move when a release breaks you. Codex tracks a fast stable line, so installing an exact version is the fastest rollback – file the issue, pin, and move on. Verify the rollback took with codex --version, since a shadowed second install on your PATH will silently keep serving the old binary (codex doctor flags exactly this under Environment).

Uninstalling the package does not remove your state. Auth, config, and session history live in ~/.codex/. Leave it in place to preserve logins and history across a reinstall; delete it only for a genuinely clean slate – rm -rf ~/.codex also discards config.toml, auth.json, and every stored session.

Direct Install Script (v0.106.0+)

For macOS and Linux, a one-line install script is available as a GitHub release asset:⁶⁰

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

The script auto-detects your platform and architecture, downloads the correct binary, and places it on your PATH.

Binary Downloads

For environments without npm or Homebrew, download platform-specific binaries from GitHub Releases¹:

System Requirements

• macOS: Apple Silicon or Intel (full sandbox support via Seatbelt)
• Linux: x86_64 or arm64 (sandbox via Landlock + seccomp)
• Windows: Native sandbox with restricted tokens (promoted from experimental in v0.100.0). WSL also supported²

Authentication

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

Two authentication paths:

1. ChatGPT Account (recommended): Sign in with your existing Plus, Pro, Team, Business, Edu, or Enterprise subscription. Full feature access including cloud tasks.
2. API Key: Set via CODEX_API_KEY environment variable or codex login --with-api-key. Some features (cloud threads) may be unavailable.

Expert tip: Credential storage is configurable via cli_auth_credentials_store in config.toml. Options: file (default), keyring (OS keychain), or auto (keyring if available, file fallback).

Amazon Bedrock login (v0.145.0, experimental): Teams whose model access runs through Amazon Bedrock get an experimental login path with custom endpoint and authentication support, alongside the existing managed API-key authentication (v0.140.0+) and the AWS credential chain (see Custom Model Providers). GPT-5.6 Sol is the default Bedrock model.¹¹² v0.150.0 fixes conversation compaction and multi-agent compatibility for Amazon Bedrock models.¹³² v0.151.0 adds a feature-gated Amazon Bedrock option to eligible TUI sign-in flows: onboarding discovers existing AWS profiles and environment credentials, offers manual setup for profiles, access keys, environment variables, and Bedrock API keys, collects the AWS Region, masks secrets during entry, and restarts the embedded server when the provider changes.¹³⁵ v0.152.0 surfaces credential-refresh progress: the TUI and codex exec show progress while a model provider refreshes expired credentials, Amazon Bedrock session reauthentication included, backed by stable modelProvider/authRecoveryStarted and modelProvider/authRecoveryCompleted app-server notifications carrying the thread, turn, provider, and a user-facing message.¹³⁸

Shell Completions

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

Verify Installation

codex --version
# codex-cli 0.162.1

Quick Start: Your First Session

Get from zero to productive in 5 minutes.

1. Install and authenticate:

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. Navigate to a project:

cd ~/my-project                  # Any git repo works

3. Start Codex:

codex

You’ll see the interactive TUI. Codex reads your project structure automatically.

4. Ask a question:

> What does this project do? Summarize the architecture.

Codex reads key files and explains the codebase. A question like this makes no changes — Codex only patches files when you ask for a change, and the sandbox and approval policy govern when it must ask first.

5. Make a change:

> Add input validation to the login endpoint

Codex proposes edits as a diff. Review and approve with y, or reject with n.

6. Use a slash command:

> /plan Refactor the database layer to use connection pooling

Codex creates a plan without executing. Review the plan, then approve to begin execution.

7. Check your work:

> /diff

See all changes Codex has made in the current session.

What’s next:

• Set up AGENTS.md with project instructions (see How Does AGENTS.md Work?)
• Configure a profile for your workflow (see Profiles)
• Try codex exec for non-interactive automation (see Non-Interactive Mode)

Core Interaction Surfaces

Codex provides five distinct interfaces backed by the same intelligence. Each surface optimizes for a different workflow pattern.

1. Interactive CLI (Terminal UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-6-sol          # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

The terminal UI is a full-screen application with:

• Composer: Type prompts, attach files with @, run shell commands with ! prefix
• Output pane: Streaming model responses, tool calls, and command output
• Status bar: Model, token usage, git branch, sandbox mode

Key TUI shortcuts:

Status line change (v0.121.0): The old context-window meter in the status line has been replaced by a context-percent indicator showing how full your context window is. If you have scripts or hooks parsing the status line, check for this format change.⁸² Codex will also surface a CLI update announcement when a new version is available.

Slash commands available in the TUI:

Workflow picker redesign (v0.129.0): Resume and fork are now easier to reach from a redesigned picker, and a new raw scrollback mode lets you scroll through the unrendered transcript when you need to copy commands or model output verbatim. Useful when triaging a long debugging session or piping output to another tool.⁸⁹

Unified @ mentions menu (v0.140.0): Typing @ in the composer now opens a single mentions menu spanning files, plugins, and skills by default, replacing the file-only attach flow — one keystroke to reference any project resource.¹⁰²

2. Codex Desktop App (macOS + Windows)

codex app                    # Launch desktop app (auto-installs if missing)

The desktop app adds capabilities the CLI doesn’t have:

• Multi-tasking: Run multiple parallel agents across different projects simultaneously
• Git worktree isolation: Each thread works on an isolated copy of your repo
• Inline diff review: Stage, revert, and commit changes without leaving the app
• Integrated terminal: Per-thread terminal for running commands
• Conversation forking: Branch conversations to explore alternatives
• Floating pop-out windows: Detach conversations into portable windows
• Automations: Schedule recurring tasks (issue triage, CI monitoring, alert response)
• Appshots: Attach the frontmost Mac app window to a thread with a screenshot plus available text
• In-app browser comments: Preview local or public pages, leave element/area comments, and let Codex address precise visual feedback
• Computer Use: Let Codex operate allowed Mac apps for scoped GUI work; locked use is opt-in for eligible remote Mac Computer Use turns

ChatGPT Voice, powered by GPT-Live (desktop 26.715, July 23, 2026): The desktop app can now be driven by speech — talk through work and coordinate tasks across Chat, Work, and Codex without typing. On macOS, turning on Screen context shares an appshot of your frontmost window with the conversation, so you can ask about what you’re looking at instead of describing it. Available on Plus, Pro, Business, Edu, and Enterprise, on the desktop app and through Remote on iOS. This is desktop-surface voice. The CLI has its own, separate voice features: /voice live conversations in the TUI (on by default since v0.156.0) and spacebar dictation (added experimentally in v0.105.0).¹¹³¹⁶⁹

Shared thread snapshots (August 20, 2026): On all Codex plans, the macOS desktop app can share a read-only snapshot of a local Codex thread. The snapshot does not update when the original thread changes; personal-account links open for anyone with the link, workspace-account links only for members of the originating workspace. Codex redacts known secret patterns before sharing, but OpenAI tells you to review the shared content because sensitive content may remain. View or revoke links in ChatGPT data controls under Shared links.¹²⁸

When to use the app vs CLI: Use the desktop app when you’re coordinating multiple workstreams or need visual diff review. Use the CLI when you want terminal composability, scripting, or CI/CD integration.

3. IDE Extension (VS Code, Cursor, Windsurf)

The Codex IDE extension integrates directly into your editor:

• Agent mode by default: Reads files, makes edits, runs commands
• Inline edits: Context-aware suggestions in your active files
• Shared sessions: Sessions sync between CLI and IDE extension
• Same authentication: Sign in with ChatGPT account or API key

Install from the VS Code Marketplace or Cursor/Windsurf extension stores.³

4. Codex Cloud [EXPERIMENTAL]

Cloud tasks run asynchronously in OpenAI-managed environments:

• Fire and forget: Queue tasks that run independently of your local machine
• Parallel execution: Run multiple cloud tasks simultaneously
• PR creation: Codex creates pull requests from completed work
• Local apply: Pull cloud results into your local repo with codex apply <TASK_ID>

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

Cloud tasks are also accessible from chatgpt.com/codex.⁴

5. Browser Extension (Chrome, Edge, Brave, Opera, Vivaldi)

Codex ships as a browser extension for Google Chrome, Microsoft Edge, Brave, Opera, and Vivaldi, adding a fifth surface alongside the CLI, desktop app, IDE extension, and cloud. The extension launched for Chrome in May 2026; the August 25, 2026 changelog added the other four browsers, set up from Settings > Computer Use in the ChatGPT desktop app. All five support tab mentions and browser control; Opera does not support side chat, so start its tasks from the desktop app. The extension is designed to ride alongside your normal browsing rather than take it over: Codex works in parallel across tabs in the background, and you stay in control of which sites it touches.⁹⁰¹²⁷

• Parallel tab execution: Codex operates across multiple tabs at once without locking the foreground tab.
• Per-site control: You allow-list which websites Codex can interact with; default is no access.
• Browser as the workbench: The extension is best for app-and-website work where the page is the source of truth — admin consoles, internal dashboards, content-management UIs, ticket systems — not a replacement for the CLI on local repos.
• Same brain: the browser extension runs the same GPT-5.x-Codex intelligence the other surfaces use, so an AGENTS.md or skills configuration that works in the CLI carries the same conventions into browser-driven work.

Install from the browser extension docs, the page formerly titled Codex for Chrome.¹²⁷

Configuration System Deep Dive

Codex uses TOML for configuration. Understanding the precedence hierarchy is critical because it determines which settings win when they conflict.

Precedence (Highest to Lowest)

1. Session overrides (highest): CLI flags (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) and -c key=value overrides
2. Project config (.codex/config.toml, discovered from CWD upward to project root; closest directory wins)
3. User config ($CODEX_HOME/config.toml, defaults to ~/.codex/config.toml)
4. System config (/etc/codex/config.toml on Unix)
5. Built-in defaults (lowest)

requirements.toml acts as a policy constraint layer that restricts what values users can select after normal config merging. See Enterprise Deployment.

Config File Locations

Expert tip: The CODEX_HOME environment variable overrides the default ~/.codex directory. Useful for CI/CD or multi-account setups.

Desktop multi-folder projects (26.715, July 23, 2026): A local project in the ChatGPT desktop app can now span several related folders, with one of them designated the primary folder (project menu → Edit project). Automatic discovery of config.toml runs against the primary folder only; secondary folders stay available for file search, reading, and editing but contribute no configuration. A .codex/config.toml sitting in a secondary folder is a file Codex can read, not a config it loads. This is desktop-app project scoping, not a change to the precedence rules above — the CLI still resolves project config by walking upward from the current working directory.¹¹³

Complete Configuration Reference

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-6.1-sol"                  # Docs' example; unset = bundled default (gpt-6.1-sol since v0.159.1)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-6-sol"             # Optional model for /review command
service_tier = "fast"                  # Preferred service tier for new turns
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # on-request|never (untrusted retired in v0.149.0)

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Tools ─────────────────────────────────────────────
tools.update_plan.enabled = false       # Planning tool opt-in (v0.152.0); exposes update_plan when true

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output (global; per-tool MCP overrides in v0.152.0)
log_dir = ""                            # Custom log directory
sqlite_home = ""                        # Override SQLite-backed resumable state location

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]
mouse_scroll_speed = 1.0                # Mouse-wheel scroll multiplier, a finite positive number (v0.162.0)

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
instant_interrupt = true                # New input preempts the model's response; on by default since v0.162.0 (under development)
api_key_model_discovery = true          # Fetch the model catalog when signed in with an OpenAI API key; on by default since v0.161.0 (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Browser-extension browser use (stable)
computer_use = true                     # macOS Computer Use (stable, plan/region gated)
in_app_browser = true                   # Shared rendered-page preview (stable)
image_generation = true                 # Image-generation tool (stable)
guardian_approval = true                # Auto-review approval path (stable)
skill_mcp_dependency_install = true     # Prompt/install missing skill MCP deps (stable)
tool_suggest = true                     # Tool/plugin suggestion surface (stable)
workspace_dependencies = true           # Workspace dependency discovery (stable)
memories = true                         # Memories (experimental)
network_proxy = false                   # Sandboxed-command network proxy (experimental); boolean or table, see below
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)
guardian_conversation_history_tools = false  # Guardian reads earlier user messages (under development, v0.160.0)

# Removed or deprecated feature names still appear in `codex features list`
# for migration diagnostics. Do not set removed flags such as
# `collaboration_modes`, `request_rule`, `codex_git_commit`,
# `apply_patch_freeform`, `search_tool`, or `js_repl` in new configs.

# ─── Guardian Auto-Review (v0.160.0 history keys) ─────
[auto_review]
conversation_history_max_output_tokens = 4000   # Per history-tool response, estimated tokens (default 4,000)
experimental_conversation_history_prompt = ""   # Blank = built-in retrieval instructions

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

features.network_proxy is boolean | table. The boolean form only starts or stops the proxy; the table form carries the policy. The proxy is what enforces permission-profile domain rules for sandboxed commands: with it off, [permissions.<name>.network] domain rules are not enforced and command network access is direct. It does not filter web search, apps, MCP servers, or other hosted tools.¹³⁰

[features.network_proxy]
enabled = true
allow_local_binding = false
proxy_url = "http://127.0.0.1:3128"

[features.network_proxy.domains]
"api.github.com" = "allow"
"*.npmjs.org" = "allow"          # subdomains only
"**.example.com" = "deny"        # apex plus subdomains; deny wins on conflicts

Administrator-managed experimental_network requirements in requirements.toml can start the proxy without features.network_proxy.¹³⁰

Profiles

Named configuration presets for different work modes. Since Codex 0.134.0 each profile is its own file — ~/.codex/<name>.config.toml, holding top-level keys only — and --profile <name> overlays that file on ~/.codex/config.toml. The older [profiles.<name>] tables inside config.toml and the top-level profile = "<name>" selector are no longer read; a leftover [profiles.<name>] table makes --profile <name> refuse to start until you move its keys into the profile file.¹²²

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0
sandbox_mode = "read-only"

# ~/.codex/auto.config.toml
model = "gpt-6.1-sol"
# GPT-6.1 Sol starts at Standard speed; /fast toggles Fast (2.5x credits)
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

A profile file is a layer above your base user config and below project and CLI config, so it only needs the values that differ from your base.¹²²

Activate a profile:

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

Expert tip: Set a default profile with profile = "fast" at the top level of your config. Override per-session with --profile.

Custom Model Providers

Connect to Azure, AWS Bedrock, local models, or proxy services:

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
# v0.140.0+ adds managed Amazon Bedrock API-key authentication, and stores
# CLI and MCP OAuth credentials in encrypted local storage.[^184]
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

env_key names the environment variable that holds the provider’s API key; the key itself never goes in config.toml. A provider with requires_openai_auth = true shows the login screen on first run and stores its credentials in the backend chosen by cli_auth_credentials_store (file, keyring, or auto), not necessarily in auth.json. Since v0.160.0, a provider that sets model_catalog_url gets only the models in that catalog, with no bundled models merged in, and a failed catalog refresh discards cached entries rather than reusing stale ones.¹⁸² Since v0.162.0 a custom Responses-compatible provider can also declare what it supports under [model_providers.<name>.capabilities]: external_web_access = false keeps hosted web search off the live web for that provider, and remote_compaction = "v2" opts it into the Responses compaction_trigger protocol, which otherwise only OpenAI and Azure Responses providers get ("unsupported" keeps compaction local).¹⁸⁷

Warning: The chat/completions wire API (wire_api = "chat") was deprecated for OpenAI-hosted models, with OpenAI announcing removal in February 2026.³⁴ Local providers (Ollama, LM Studio) may still accept this format. For OpenAI endpoints, use wire_api = "responses" instead.

Use local models with the --oss flag:

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

Or set in config:

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

Inline Config Overrides

Override any config value from the command line:

codex -c model="gpt-5.5" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

Which Model Should I Choose?

Available Models (September 2026)

GPT-5.5 (April 23, 2026) was OpenAI’s recommended choice for most Codex tasks at launch: complex coding, computer use, knowledge work, and research workflows. Available in Codex CLI / web / desktop on April 23 for ChatGPT Plus / Pro / Business / Enterprise / Edu / Go; in the OpenAI API on April 24. Context window: 400K in Codex, 1M in the API — Codex caps the window at 400K to balance throughput and cost across subscriber tiers; the API exposes the full 1M. Pricing (API): $5 input / $30 output per MTok (2× the GPT-5.4 rate; OpenAI states ~20% effective increase after token-efficiency improvements). Benchmarks: 82.7% Terminal-Bench 2.0 (current SOTA across publicly available models), 84.9% GDPval (44 occupations), 78.7% OSWorld-Verified, 98.0% Tau2-bench Telecom (no prompt tuning). OpenAI used GPT-5.5 + Codex internally to rewrite serving infrastructure pre-launch — yielded a 20% boost in token generation speed.⁸³

GPT-5.5 retires from Codex with ChatGPT sign-in on October 14, 2026 – the models docs scope the retirement to ChatGPT, ChatGPT Work, and Codex on all plans (consumer, Business, Enterprise, and Edu included) and state it does not apply to the OpenAI API.¹⁵⁵ The replacement guidance changed with the GPT-6 launch: on Plus, Pro, Business, Enterprise, and Edu, choose gpt-6-sol; on Free and Go, choose gpt-6-luna in the desktop app, each “when available.” Replace gpt-5.5 in workspace defaults, saved model settings, managed configurations, custom agents, scheduled tasks, and scripts.¹⁷¹

GPT-5.4 and GPT-5.4 mini retired from Codex with ChatGPT sign-in on August 31, 2026.¹¹⁷ The models docs now name gpt-6-sol and gpt-6-luna as their replacements (in Enterprise and Edu, an administrator must enable Luna first); API-key use is unaffected.⁶⁴¹⁷¹ The exact model list varies by account and rollout. Check your local cache: ~/.codex/models_cache.json.

Deprecation note (March 11, 2026): GPT-5.1 models are no longer available in ChatGPT. Existing conversations automatically continue on GPT-5.3 Instant, GPT-5.4 Thinking, or GPT-5.4 Pro. GPT-5.1-Codex-Mini remained available via API and CLI until the July 23, 2026 shutdown.⁷¹⁸⁸

Free-tier note (May 5, 2026): GPT-5.5 Instant rolled out to the ChatGPT free tier on May 5, 2026. This widens the audience for the GPT-5.5 family beyond paid plans, though Codex CLI access continues to require an eligible Plus / Pro / Business / Enterprise / Edu / Go subscription or API key.⁹²

GPT-5.4 mini (March 17, 2026): A smaller, faster variant of GPT-5.4 with 400K context at $0.75/$4.50 per MTok — uses only 30% of GPT-5.4 quota. Ideal for subagent delegation: let GPT-5.4 handle planning and coordination while GPT-5.4 mini subagents handle narrower subtasks (codebase search, file review, document processing) in parallel.⁷⁶

Bedrock GPT-5.6 (Sol, Terra, Luna) (v0.143.0, July 8, 2026): Codex added first-class support for three GPT-5.6 model variants hosted on Amazon Bedrock, including support for the max reasoning-effort level. For teams whose model access runs through a Bedrock provider, these are selectable the same way as other custom-provider models (see Custom Model Providers); the max effort tier targets the hardest reasoning and agentic workloads.¹⁰⁶ v0.144.6 (July 18, 2026) refreshed the bundled instructions for Sol, Terra, and Luna and corrected their context windows to 272,000 tokens.¹¹¹ v0.145.0 (July 21, 2026) adds experimental Bedrock login with custom endpoint and authentication support, makes GPT-5.6 Sol the default Bedrock model, and migrates bundled GPT-5.4 model selections to the corresponding Terra and Luna variants.¹¹²

GPT-6-Astra (launched September 3, 2026; in Codex via v0.153.1-v0.153.4): the chronology, with explicit dates: v0.153.1 staged an API-only catalog entry on September 3, 2026; OpenAI announced GPT-6-Astra the same day; and v0.153.4 added the picker entry and the bundled-CLI-default flip on September 4. The announcement describes a phased rollout that begins with a limited set of organizations (cybersecurity-program partners first) and extends to ChatGPT Plus, Pro, Business, and Enterprise “over the coming days,” plus the OpenAI API and AWS – the rollout facts are press-reported (CNBC, Axios, Forbes, Al Jazeera, 9to5Mac).¹⁴⁵ Superseded September 4: OpenAI announced on X that GPT-6 Astra “is now available to all Pro, Enterprise, and Business Premium users in ChatGPT Work and Codex” and “live in the API,” with Plus and Business expected within days, and the Codex lead Tibo Sottiaux followed up the same evening: “Astra is now rolled out to all Plus and Business users too.” Entitlement remains uneven in practice – September 5 community reports show Plus accounts still seeing only GPT-5.6 models in Codex – and the models docs availability line quoted below is unchanged, so it remains the operative first-party statement.¹⁴⁹ First-party docs are live: the API model page lists gpt-6-astra as the flagship, “Our most capable model, built for the hardest end-to-end work” – $10/MTok input, $50/MTok output at standard short-context rates, a 1.05M-token context window with 922,000 max input tokens, 128K max output, knowledge cutoff April 30, 2026 – with a documented long-context tier: prompts above 272K input tokens are priced at 2x input and 1.5x output for the full request, $20/MTok in and $75/MTok out on the pricing page – above GPT-5.6 Terra (balanced) and Luna (budget), and the Codex docs name Astra the recommended Codex model, with availability that “depends on the rollout, your sign-in method, and your client” and eligibility named for Pro, Business ($100), and Enterprise accounts. Astra’s documented Codex reasoning ladder: Low, Medium, High, Extra High, Max, Ultra – the docs models page marks Medium as the default, while the bundled catalog v0.153.4 ships sets default_reasoning_level to low, so treat the effective default as surface-dependent and check /status in a session; the ladder is unchanged at the September 15 re-access, now with per-level picker descriptions (Ultra, verbatim: “Maximum reasoning with automatic task delegation”), and the Max and Ultra rungs carry SDK confirmation – the Python SDK 0.154.0 release (September 10, 2026) adds the max and ultra reasoning-effort values (#39662).^146148153 In the CLI, Astra is API-configurable since v0.153.1 (-m gpt-6-astra), joins the Amazon Bedrock catalogs in v0.153.3 (GPT-5.6 Sol stayed the Bedrock default until v0.157.0 made it GPT-6 Sol¹⁷⁴), and sits in the model picker and as the bundled default when no model is explicitly configured as of v0.153.4 – no minimum CLI version is documented, so treat those as the effective floors. That default flip is a bundled-CLI-catalog fact, not an all-surfaces one – though the cloud gap has since closed: the September 4 and September 7 accesses marked Astra unavailable for Codex cloud (GPT-5.6 Sol available there), while the September 15 re-access shows the availability matrix marking Astra available for Codex cloud as well; the page still notes “Currently, you can’t change the default model for Codex cloud chats.” Rollout caveat: entitlement varies by account, and on CLI 0.153.4+ an account outside the rollout carries a bundled default it cannot yet serve – pin a model in config.toml (or pass -m) for deterministic selection; since v0.156.1 the docs’ own example is model = "gpt-6-sol". Astra Fast-mode billing is documented even though the models page lists no Fast tier: the Codex speed docs put it at 2.5x Standard credits with ChatGPT sign-in (“where available”), and the API pricing page carries Fast-mode rates at exactly 2x the applicable Standard rates ($20/$100 per MTok short-context, $40/$150 long-context). The “2x speed” half of v0.153.2’s catalog string remains catalog display text only – the speed page states no speed multiplier for Astra.^145146147148 Superseded in part, September 23, 2026: the models docs no longer describe Astra as the recommended Codex model. Their “Recommended models” section now leads with GPT-6 Sol and Luna, reserves Astra for “the hardest end-to-end work,” marks Astra unavailable for Codex cloud, and gives Astra’s starting effort as Light (low), which matches the bundled catalog. Astra remains the bundled CLI default when no model is configured.¹⁷¹ Superseded September 29, 2026: v0.159.1 makes GPT-6.1 Sol the bundled default and moves Astra to second in the picker, and the models docs now recommend GPT-6.1 Sol for complex coding while keeping Astra for the hardest end-to-end work; the docs’ configuration examples now use gpt-6.1-sol.¹⁷⁸

Power presets under Astra (docs addition, on or before September 6, 2026): the Codex models docs’ model-picker passage now maps the picker’s Power options onto GPT-6-Astra reasoning tiers – the first docs mapping of the Power presets onto Astra – in a paragraph absent at ¹⁴⁶’s September 5 re-access and confirmed live September 7. Verbatim: “For eligible Pro, Business ($100), and Enterprise accounts, the Astra rollout updates the Power options to Terra Light, Sol Light, Sol Medium, Astra Light, Astra Medium, and Astra Extra High. Options can differ by plan and rollout stage.” The preceding docs sentence notes the picker illustrations still show GPT-5.6 controls. Read alongside the models table above: “Power” has meant GPT-5.6 Sol at medium reasoning; on an entitled account the same preset ladder now spans Terra, Sol, and Astra at fixed reasoning levels, and the options remain plan- and rollout-dependent. The paragraph is unchanged verbatim at the September 15, 2026 re-access.¹⁴⁶ Updated September 23, 2026: after the GPT-6 Sol and Luna launch the docs list the six Power presets as “Luna High, Sol Light (the starting preset), Sol Medium, Astra Light, Astra Medium, and Astra Extra High,” note that some paid plans omit Astra Extra High, and suggest starting at Medium for Sol, High for Luna, and Light (low) for Astra.¹⁷¹

Experimental cross-context notes (Astra, docs-published, opt-in): the Codex models docs page carries a section headed “Experimental context management,” verbatim: “On supported Codex clients, users signed in with ChatGPT Plus or Pro can opt in to experimental context management. Astra keeps notes across context windows and can search earlier messages and tool results from the same task. This experiment is off by default and isn’t available with Business, Enterprise, or API-key sign-in at launch.” The opt-in mechanism, verbatim: “To opt in, set features.context_management.experimental_mode = true in your config.toml, then start a new task.” That is the same features.context_management.experimental_mode surface v0.153.0 shipped (see Context Management) – the docs page now ties it to Astra by name and to Plus and Pro sign-in, where the v0.153.0 release notes had named eligible Plus, Pro, and Pro Lite sessions. v0.154.0 tightens the code side: eligibility for the experiment is now gated by the active model’s capabilities at session startup (#43147). The docs section is unchanged verbatim at the September 15, 2026 re-access. Experimental and off by default; expect the behavior and eligibility to change.^140146152 v0.157.0: the bundled model catalog no longer marks GPT-6-Astra, or any other bundled model, as supporting experimental context (#47397), and the CLI turns the experiment on only for a model marked that way. With the bundled catalog, then, the opt-in has no effect; whether the catalog served to signed-in accounts differs is not documented. The models docs still described the opt-in on September 26, 2026.¹⁷⁴ September 29, 2026: the models page no longer carries the section, the config reference describes features.context_management.experimental_mode as “Experimental context-management setting. The feature is not currently available,” and GPT-6.1 Sol is not marked as supporting it either.¹⁷⁸

Model Selection Flowchart

Is this a quick fix, extraction, or other well-defined repeatable task?
├─ Yes → gpt-6-luna (most efficient; docs suggest starting at High)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Hardest end-to-end work across many steps and tools?
   │     │  ├─ Yes → gpt-6-astra (strongest; most expensive)
   │     │  └─ No → gpt-6.1-sol (near-Astra at lower cost; default since v0.159.1)
   └─ GPT-6.1 Sol not yet available on your account? → gpt-6-sol, then gpt-5.6-sol

Reasoning Effort

Control how much the model “thinks” before responding:

Supported levels are model-dependent. minimal is only available for GPT-5 models. Not all models support every level.

persistent details (v0.151.0): turns running at persistent effort default the current-time reminder and the interruptible clock.sleep tool on (explicit features.current_time_reminder settings and managed requirements are preserved), and ship bundled proactivity and follow-up guidance that model metadata can override or disable via persistent_instructions.¹³⁵

codex -c model_reasoning_effort="xhigh" "find the race condition"

Expert tip: xhigh reasoning can use 3-5x more tokens than medium for the same prompt. Reserve it for genuinely hard problems where the extra thinking pays off.

TUI quick reasoning controls (v0.124.0+).⁸⁵ In an interactive TUI session, Alt+, lowers reasoning one step and Alt+. raises it one step — useful when a hard problem mid-session warrants a temporary medium → high → xhigh ramp without /effort or -c. When you accept a model upgrade mid-session, reasoning resets to the new model’s default rather than carrying the prior level over.

Model Switching

Switch models mid-session with the /model slash command, or set per-run via --model / -m:

codex -m gpt-5.3-codex-spark "pair with me on this component"

What Does Codex Cost?

See also Model Selection for capabilities and Decision Frameworks for choosing the right model per task.

Access via ChatGPT Plans

Codex availability depends on your ChatGPT plan and organization settings:⁵¹

April 2026 pricing update: Business annual pricing dropped from $25 to $20/seat/mo. Codex-only seats with pay-as-you-go pricing are now available for Business and Enterprise workspaces — no fixed seat fee, billed on token consumption.⁷⁹ The pricing page now publishes limits as per-model bands (see the table above) rather than the promotional 2x multipliers from the February 2026 Desktop App launch.¹⁶¹⁶²

May 2026 usage limit boost (expired May 31, 2026): Codex on the Plus plan ran at a 25× 5-hour limit (vs the standard 20× boost), and the $100/month tier was doubled for the same window.⁸⁹

Rate-limit UX in the TUI (v0.152.0-v0.153.0): hitting a limit is no longer a dead end. v0.152.0 renders actionable rate-limit banners above the composer – check usage, manage credits, reset limits, notify the workspace owner, and manage plans – filtered to the authenticated account and user; usage refreshes after limit errors, and when the banner instructs it, Codex switches to the first available fallback model without changing unrelated thread settings.¹³⁸ v0.153.0 adds earlier warnings for Plus and Team plans: a warning fires when less than half of the allowance remains in an approximately five-hour usage window, while other plans and window lengths keep the existing 75%, 90%, and 95% thresholds.¹⁴⁰

Credit Costs

Codex operations consume credits from your plan allocation:

The rates are for Standard speed, and the pricing page says GPT-5.6 Sol, Terra, and Luna rates “remain unchanged” after the GPT-6 launch. In practice, “GPT-5.6 usage averages 5-30 credits per message” (the page said 5-40 at the August access); Fast mode costs 2.5x the Standard credit rate for GPT-6.1 Sol and GPT-6 Astra, Sol, and Luna “where available,” and the bundled catalog makes Fast the default tier for GPT-6 Sol and Luna (not GPT-6.1 Sol) in the TUI unless you set service_tier, so check /fast status if credits drain faster than expected. Image generation burns included limits 3-5x faster than comparable text-only turns.^162171178

Enterprise and Edu plans scale credits with contract allocation. Check /status in the TUI for current usage.

API Billing

When using Codex through the API, OpenAI bills usage per token under standard OpenAI API pricing for the selected model (plus any applicable prompt-caching discounts). Current API rates per 1M tokens: GPT-6.1 Sol $2 input / $10 output ($0.10 cached input), GPT-6 Sol $2 / $10, GPT-6 Luna $0.10 / $0.50, GPT-6 Astra $10 / $50; for all four, prompts above 272K input tokens cost 2x input and 1.5x output for the full request, and Fast mode costs 2x.^146171178 ChatGPT credit multipliers do not apply to API-key sign-in. Check the official API pricing page for current rates.²⁰

Cost Optimization Strategies

1. Use profiles: Create a fast profile with gpt-6-luna and model_reasoning_effort = "low" for routine tasks
2. Reserve high reasoning: Only use xhigh for genuinely hard problems, as it costs 3-5x more tokens
3. Use --ephemeral: Skip session persistence in CI/CD to reduce overhead
4. Minimize reasoning summaries: Set model_reasoning_summary = "none" when you don’t need explanations
5. Batch with exec mode: codex exec avoids TUI overhead for automation workflows
6. Monitor usage: Check /status in the TUI and your org billing dashboards — as of v0.148.0, /status, status lines, and terminal titles show estimated thread credits or cost for eligible workspaces¹¹⁸

Real-World Cost Examples

Representative API costs for common tasks (a mid-2026 gpt-5.3-codex pricing snapshot, medium reasoning — the relative sizes transfer across models):

Costs vary by reasoning effort, caching, and conversation length. Use gpt-5.6-luna for routine tasks to cut routine-task spend substantially. Cached input tokens are billed at a discount.

Hidden Token Overhead

Every tool call adds tokens beyond your visible prompt:

Expert tip: Monitor your actual usage via /status in the TUI. The token count includes all overhead, not just your visible messages. If costs surprise you, check how many MCP servers are connected — each adds tool definitions to every API call.

Team Cost Management

Strategies for team cost control:

• Set requirements.toml to enforce model and reasoning effort limits organization-wide
• Use gpt-5.6-luna for CI/CD — automated pipelines rarely need maximum reasoning
• Profile-based budgeting — define ci, review, and dev profiles with appropriate cost ceilings
• Monitor via OpenTelemetry — enterprise deployments can export usage telemetry to existing observability stacks

Decision Frameworks

When to Use Each Surface

When to Use Each Sandbox Mode

When to Use Each Reasoning Level

Plan Mode vs Direct Execution

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Steer Mode: Enter vs Tab

Rule of thumb: Enter = “stop, listen to this now.” Tab = “when you’re done, also do this.”

Desktop App vs CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

Which Profile?

Match your task to a pre-configured profile:

Profile files (one per preset, in ~/.codex/; the legacy single-file profile = "default" + [profiles.*] layout is not read since 0.134.0¹²²):

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"

# ~/.codex/pair.config.toml
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

# ~/.codex/ci.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Switch profiles per-session: codex --profile careful

How Does the Sandbox & Approval System Work?

Codex uses a two-layer security model that separates what is technically possible from when Codex asks for human approval. The approach differs fundamentally from Claude Code’s permission system — Codex enforces restrictions at the OS kernel level.⁵ See also Enterprise Deployment for requirements.toml constraints that administrators enforce organization-wide.

v0.148.0 hardening: sandbox restrictions now fail closed — a denied or unreadable path is treated as blocked instead of silently allowed — on both Linux and Windows.¹¹⁸

Layer 1: Sandbox (What Is Possible)

The sandbox controls filesystem and network access using OS-native mechanisms:

Platform-specific enforcement:

• macOS: Apple’s Seatbelt framework via sandbox-exec with mode-specific profiles compiled at runtime and enforced by the kernel⁶. As of v0.121.0, macOS sandbox profiles can allowlist specific Unix sockets (e.g., docker.sock, editor IPC sockets) and private DNS resolution is no longer blocked by default.⁸²
• Linux: Landlock for filesystem restrictions + seccomp for syscall filtering. A standalone helper process (codex-linux-sandbox) provides defense-in-depth isolation.⁵ Bubblewrap (bwrap) is vendored and compiled as part of the Linux build (promoted from optional in v0.100.0)⁷. v0.117.0 improved sandbox reliability on older distros with legacy kernel configurations.⁷⁵ v0.129.0 hardened sandbox startup on Linux and bumped vendored Bubblewrap to 0.11.2 with upstream security patches; v0.130.0 added further startup hardening.⁸⁹⁹¹
• Windows: Native sandbox with restricted tokens (promoted from experimental in v0.100.0). WSL also supported (inherits Linux Landlock + seccomp). v0.117.0 includes restricted-token sandbox improvements for better process isolation.⁷⁵ v0.130.0 grants sandbox users access to the desktop runtime binary cache so that the Windows sandbox can resolve runtime binaries reliably for workspace-sandbox users.⁹¹

Why this matters: Unlike container-based sandboxing (Docker), OS-level sandboxing is faster, lighter, and harder to escape. The kernel enforces restrictions before Codex even sees the system call.

Security fixes:

• zsh-fork sandbox bypass (v0.106.0): Fixed a vulnerability where shell execution via zsh forking could bypass sandbox restrictions.⁶⁰ If you are on an earlier version, upgrade immediately.
• Input size cap (v0.106.0): Codex now enforces an approximately 1-million-character input cap to prevent hangs from excessively large payloads.⁶⁰
• Secure devcontainer profile (v0.121.0): A new hardened customer profile for Docker devcontainers uses Bubblewrap for sandboxing inside the container. WSL2 is supported; WSL1 is explicitly rejected (Bubblewrap is incompatible with WSL1’s kernel shim).⁸²
• Guardian review + hooks (v0.121.0): Hooks are disabled during Guardian review sessions so pre/post-tool hooks cannot interfere with the Guardian subagent’s decisions.⁸² If you rely on hooks for logging or validation, be aware that a Guardian review skips them — fall back on app-server observability if you need a full audit trail.
• Linux /dev filesystem (v0.105.0): Sandboxed commands on Linux now receive a minimal /dev filesystem, improving compatibility with tools that expect device nodes.⁶¹

ReadOnlyAccess policy (v0.100.0+): A configurable policy shape for granular read access control. Use it to restrict which directories Codex can read from, even in workspace-write mode:

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

Layer 2: Approval Policy (When To Ask)

The approval policy determines when Codex pauses to ask for human confirmation:

on-failure still appears in some older examples and compatibility paths, but current OpenAI configuration docs mark it deprecated. Prefer on-request for interactive runs and never for non-interactive runs that already have an external safety boundary.⁸⁷

As of v0.150.0 you can bind a keyboard shortcut that cycles permission modes from the composer – configure it via /keymap.¹³²

Distinct Approval IDs (v0.104.0+)

Codex now assigns distinct approval IDs to each command within a multi-step shell execution. This means approvals are granular — approving one command in a sequence doesn’t automatically approve subsequent ones in the same shell invocation.⁴⁹

Flexible Approval Controls (v0.105.0+)

The approval flow now supports extra sandbox permissions and granular rejection:⁶¹

• Extra sandbox permissions: When a command needs access beyond the current sandbox mode, Codex can request specific additional permissions rather than requiring a full mode change
• Granular rejection: Reject individual tool calls with feedback so Codex can adjust its approach rather than simply re-attempting the same command

Runtime Permission Requests (v0.113.0+)

Codex now includes a built-in request_permissions tool that allows the model to request additional permissions at runtime.⁶⁹ When the model encounters a task requiring elevated access, it can formally request specific permissions (filesystem paths, network access, etc.) through the TUI approval flow rather than failing silently or requiring the user to restart with different flags.

App Approval Mode writes (v0.144.0+)

Apps and connectors gain a middle approval tier: the writes app-approval mode lets an app’s declared read-only actions run without prompting while still pausing for anything that writes.¹⁰⁷ Before this, app approvals were closer to all-or-nothing; writes matches the trust shape most operators actually want for integrations — free to look, ask to touch.

Automatically Reviewed Approvals: --approve-for-me (v0.147.0+)

The new --approve-for-me CLI flag turns approval prompts into automatically reviewed approvals: instead of interrupting you, each request is adjudicated by a review pass and approved or refused on your behalf.¹¹⁶ This sits between “approve everything” (the posture --full-auto used to encourage, now removed) and “interrupt for everything” — the prompts still exist as decision points, but a reviewer answers them. Pair it with the v0.146.1 safer auto-review defaults for cyber-capable models, which this flag inherits. Treat it like any delegation of authority: right for long unattended runs where interruption means a stall, wrong for sessions touching credentials or production state where you want to be the reviewer.

Approval for Escalated Terminal Input (v0.151.0; on by default since v0.158.0)

The write_stdin_approval feature flag – off by default when it arrived in v0.151.0, on by default since v0.158.0 – requires a fresh approval before non-empty input is sent to an escalated unified-exec terminal. These reviews route through hooks, Guardian, the app server, and the TUI as writeStdin approvals; the terminal’s environment, launch directory, and escalation state persist across turns, and the process identity is revalidated after approval before any bytes are written. The fully formatted action and approval reason must fit within 8,000 bytes – oversized or truncated actions are rejected before approval is requested or anything reaches the terminal.¹³⁵ v0.158.0 turns the flag on (#47799) and stops runtime-only grants, such as those plugins use for metrics, from triggering a review, while extra agent permissions, sandbox bypasses, and policy changes since launch still do (#48073). To turn it off: set write_stdin_approval = false under [features] in config.toml.¹⁷⁶

Permission Profiles (v0.113.0+, expanded in v0.128.0 and v0.133.0)

Permission profiles split filesystem and network sandbox policies into named, reusable sections. Set default_permissions to a built-in profile such as :read-only, :workspace, or point it at a custom [permissions.<name>] table.⁸⁷ v0.133.0 promotes profiles as a managed surface: list APIs expose available profile metadata, profiles can inherit from one another, managed requirements.toml can declare permission requirements, active profiles refresh at runtime, and Windows sandbox setup now consumes the resolved profile rather than a separate ad hoc policy.⁹⁸

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

Use none for sensitive files and globs that should be unreadable even when the project root is writable. For one-off command exceptions, prefer rules over broadly expanding a profile.⁸⁷

v0.151.0: restored app-server threads keep their permission profiles instead of being flattened into legacy per-turn sandbox overrides – profiles survive turn routing and compatible /cd directory changes, and a /cd that cannot represent the restored profile safely as a legacy sandbox mode is rejected rather than silently weakening restrictions.¹³⁴

Legacy --full-auto Guidance

Older guides described --full-auto as a convenience alias for:

codex --sandbox workspace-write --ask-for-approval on-request

In v0.128.0, release notes mark --full-auto deprecated, and current CLI help no longer lists it for interactive runs. Use the explicit flags above or a named permissions profile instead.⁸⁶

v0.147.0 completes the removal: codex exec --full-auto is gone. A script still passing the flag now errors rather than running. The migration is mechanical — replace it with --sandbox workspace-write (plus an approval flag or profile if your old invocation relied on --full-auto’s approval behavior). Audit any automation that shells out to codex exec before upgrading: the failure shows up as a broken pipeline, not a deprecation warning.¹¹⁶

Sandbox reliability (v0.129.0): Linux sandbox startup hardening reduces races on slow filesystems or symlinked checkouts; Windows sandbox reliability improvements address several edge-case crashes during long-running runs; and the vendored Bubblewrap is bumped to 0.11.2 with upstream security patches. No config changes required. Run codex update to pick these up.⁸⁹

Recommended Configurations

Daily development (safe default):

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Power user (full access, human-in-the-loop):

sandbox_mode = "danger-full-access"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0

Community write-ups recommend the pairing as a “sweet spot”⁸; understand what it actually does before repeating the advice: approval prompts fire when a command needs to leave the sandbox or reach the network, and danger-full-access removes both boundaries, so on-request has almost nothing left to escalate. It is maximum capability with minimal asking, not maximum capability with a human check on every command; if you want the latter, keep workspace-write and let the sandbox boundary do the prompting.¹²³

CI/CD automation:

sandbox_mode = "workspace-write"
approval_policy = "never"

Smart Approvals with Guardian Subagent (v0.115.0+)

Smart Approvals can route review requests through a guardian subagent instead of requiring human approval for every action. The guardian session persists across approvals to reuse prompt cache and avoid startup overhead. Each review gets a clean history (prior decisions don’t leak into later reviews).⁷³

Configure the reviewer in config.toml:

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

This is particularly useful for CI/CD workflows where you want automated review with reasoning rather than blanket approval_policy = "never".

Guardian v2 defaults flipped (v0.151.0): Guardian v2 now defaults to computer-use reviews with images. features.guardianv2.review_scope.computer_use_only defaults to true – set it to false to retain the broader tool review scope – and features.guardianv2.transcript.include_images defaults to true – set it to false to keep images out of Guardian transcripts. Both shipped as configurable, default-off surfaces in v0.150.0; v0.151.0 is where the defaults turned on.¹³⁵

Guardian scope follows the approval mode (v0.153.0): two modes now skip Guardian work that cannot change the outcome. In Full Access (which already combines approvalPolicy: "never" with unrestricted permissions), confirmation-only Guardian and MCP requests are approved without synchronous review, sampler prewarming, or background scoring – pending, failed, or restricted environments are not treated as Full Access, and the active permission state is re-evaluated each turn so an existing thread can enter or leave Full Access safely. In User approval mode (approvals_reviewer = "user"), Guardian prewarming and asynchronous scoring are skipped and ordinary node_repl.js execution confirmations are accepted automatically, while sensitive-action checks and requests for user input keep their existing behavior.¹⁴⁰ This narrows when Guardian runs, not the human approval layer: the prompting behavior this guide describes for danger-full-access under on-request is approval policy, a separate mechanism. v0.152.1 additionally lets Guardian approval review source its Node REPL policy from model metadata (auto_review.node_repl_policy), falling back to the bundled policy when the field is absent.¹³⁹

Guardian computer-use scoring honors model requirements (v0.153.1): computer-use-only Guardian scoring and fast approval decisions now run only when the active model sets node_repl_auto_review_required in its metadata, and prior or in-flight scores are invalidated when a model switch skips scoring – so switching back to a reviewed model cannot revive a stale approval decision. This is the headline of the v0.153.1 patch, and it is unlisted in the release body: #42422 (a cherry-pick of 38ba8cdc) is provable only via the rust-v0.153.0…rust-v0.153.1 compare.¹⁴²

Guardian parent-compaction reuse is on by default (v0.156.0): #46522 promotes guardian_reuse_parent_compaction to a stable feature and enables it by default, which lets Guardian reuse the parent thread’s encrypted compaction when it restarts a review session. Per the PR’s tests, cached review sessions are still invalidated when the parent history changes. To restore the previous behavior: set guardian_reuse_parent_compaction = false under [features] in config.toml, or run codex features disable guardian_reuse_parent_compaction.¹⁶⁹¹⁷¹

Guardian thread context is on by default (v0.157.0): #47275 promotes guardianv2.thread_context to stable and enables it for synchronous and asynchronous Guardian reviews, so reviews use thread-owned context. It is independent of the Guardian v2 enabled toggle. In v0.157.0 you could turn it off with thread_context = false under [features.guardianv2]; v0.158.0 removed that option.¹⁷⁴

Guardian thread context is always on (v0.158.0): #47686 and #47689 make thread-owned context unconditional for Guardian session capture and subagent history forks. Codex ignores thread_context under [features.guardianv2], including profile overrides and managed requirements, and shows a deprecation notice asking you to remove it from config.toml. There is no replacement off-switch.¹⁷⁶

Guardian can read earlier user messages (v0.160.0, opt-in): the transcript Guardian reviews can omit an earlier instruction, restriction, or revoked permission. With guardian_conversation_history_tools = true under [features] and Apps enabled, the reviewer gets two tools, user_message.search_messages and user_message.read_messages, served through the parent session’s own Apps connection and identity. Each call rechecks the parent’s current app and tool policy and fails closed on a disabled tool or one that needs approval. Two [auto_review] keys tune it: conversation_history_max_output_tokens caps each response (an estimated 4,000 tokens by default; stricter parent limits still apply), and experimental_conversation_history_prompt replaces the built-in retrieval instructions (blank uses the default). A second opt-in flag, guardian_root_handoff_context, narrows the root-conversation evidence for a worker agent’s review to the messages around each handoff to it, plus the latest three. Both flags are under development and off by default; the config reference does not list them yet.¹⁸²

[features]
guardian_conversation_history_tools = true

[auto_review]
conversation_history_max_output_tokens = 4000

PowerShell classifier tightening (v0.142.2): PowerShell commands containing executable AST regions the safety classifier cannot inspect now require approval instead of slipping through auto-approval — closing a gap where obfuscated or dynamically built PowerShell could evade classification on Windows.¹⁰⁵

Dangerous-command detection expanded (v0.144.5): Detection now recognizes more forced rm forms, and rejected commands come back with clearer rejection reasons instead of an opaque denial — useful when you are tuning approval policies and need to know why a command was blocked.¹¹⁰

Enabling Network Access

Codex blocks network access by default in workspace-write mode. Enable it when needed:

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

WebSocket Proxy Support (v0.104.0+)

For corporate environments that route WebSocket traffic through a proxy, Codex now supports WS_PROXY and WSS_PROXY environment variables:⁴⁹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

These complement the existing HTTPS_PROXY and SOCKS5 proxy support (v0.93.0+).

v0.146.0 is the release that made “all transport layers” actually true. Configured proxies are now honored across authentication, plugin downloads, MCP authorization, remote execution, WebSocket connections, HTTP redirects, and LM Studio connections — seven paths that the changelog lists as previously ignoring the proxy.¹¹⁴ If you ran Codex behind a corporate proxy before v0.146.0 and saw logins or plugin installs fail while ordinary model calls worked, that gap is the likely explanation.

System proxy on macOS (v0.142.2+): with respect_system_proxy enabled, macOS authentication clients honor the system proxy, PAC, and WPAD settings — so corporate Macs that push proxy config via profiles no longer need per-shell proxy env vars for auth traffic.¹⁰⁵ As of v0.143.0 this extends to Windows and to Responses API traffic: Codex routes both authentication and Responses API calls through the macOS or Windows system proxy, including PAC and WPAD autoconfiguration, closing the last gap for locked-down corporate networks on either OS.¹⁰⁶

Testing the Sandbox

Verify sandbox behavior before trusting it:

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

If the sandbox is working correctly, both commands should fail with a permission denied error under a workspace-scoped profile. If either command succeeds, your sandbox configuration needs investigation.

How Does AGENTS.md Work?

AGENTS.md is Codex’s project instruction system — an open standard⁹ now governed by the Linux Foundation’s Agentic AI Foundation. Supported by Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode, and 60,000+ open source projects. It defines how Codex behaves within a specific repository or directory. See Skills for reusable expertise packages that complement AGENTS.md.

Discovery Hierarchy

Codex builds an instruction chain at session start by walking the directory tree:

1. Global (~/.codex/): AGENTS.override.md > AGENTS.md
2. Project (git root to current directory): Each level checked for AGENTS.override.md > AGENTS.md > fallback filenames
3. Merging: Files concatenate root-down; closer files appear later in the prompt and override earlier guidance

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

Untrusted projects skip project AGENTS.md (v0.150.0): the walk above assumes the project is trusted. Since v0.150.0, “Untrusted projects no longer supply project-level AGENTS.md instructions, and managed deny-read rules remain enforced after permission changes” – project-scoped discovery is skipped while user-level ~/.codex/AGENTS.md instructions are preserved, so an untrusted checkout cannot inject an operating contract before you trust it.¹³²

Desktop multi-folder projects (26.715, July 23, 2026): The walk above describes the CLI, which resolves everything relative to the current working directory. The ChatGPT desktop app now lets a local project span several related folders, and it resolves discovery against exactly one of them: “New chats, Git operations, and automatic discovery of AGENTS.md, skills, and config.toml use the primary folder. Secondary folders remain available for file search, reading, and editing.” You choose which folder is primary from the project’s menu via Edit project.¹¹³

That single setting governs three of Codex’s five core systems at once — instructions, skills, and configuration all follow the primary folder. Practically: an AGENTS.md in a secondary folder is a file Codex can open, not an operating contract it loads. If the repo carrying your rules is the one you attached second, either promote it to primary or restate those rules in the primary folder’s AGENTS.md; the same applies to repository skill folders you expected to be picked up. Nothing about the CLI’s directory walk changed — this is desktop-app project scoping.

What Makes a Great AGENTS.md

Based on direct guidance from Codex itself and community patterns¹⁰:

DO:

• Be specific: "Use rg --files for discovery" beats "search efficiently"
• Define closure: What does “done” mean? (tests pass, lint clean, etc.)
• Include commands: Build, test, lint, format (exact invocations)
• Organize by task: Coding, review, release, incident/debug sections
• Define escalation: What to do when blocked or encountering unexpected state

DON’T:

• Dump entire style guides without execution rules
• Use ambiguous directives (“be careful,” “optimize”)
• Mix contradictory priorities (speed + exhaustive verification + no runtime budget)
• Write prose documentation (AGENTS.md is operational policy, not README)

Example: Production AGENTS.md

# Repository Guidelines

## Build, Test, and Development Commands

- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions

- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines

- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security

- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

Secret Handling in Agent Sessions

Treat Codex-visible history as a security surface, not just source code. Codex release notes document shell snapshotting and environment-variable redaction work, and the memory system scans memory writes for secrets, but those protections do not turn command output, session transcripts, shell snapshots, local logs, or helper scripts into safe places to print credentials.³⁷⁵⁵⁹⁵

The operating rule is simple: do not print secrets for the model to inspect; keep helper credentials in environment-required config; separate executable source, docs, generated caches, session transcripts, shell snapshots, logs, and intentional secret stores during audits; redact local history when a high-confidence secret shape appears; and promote prevention hooks only after the manual hygiene loop is proven. The public lesson is the surface map and acceptance criteria, not private token values, exact paths, or detector internals.⁹⁵

The Override Mechanism

AGENTS.override.md at any directory level replaces the normal AGENTS.md for that scope. Use for:

• Release freezes: “No new features, fixes only”
• Incident mode: “All changes must be reviewed by on-call”
• Temporary hardening: “No dependency updates this sprint”

Configuration

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

Scaffold Generation

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

Or verify your instruction chain:

codex --ask-for-approval never "Summarize your current instructions"

Hooks

Codex introduced hooks in v0.99.0 and v0.100.0 under the legacy AfterAgent and AfterToolUse names, added an experimental hooks engine in v0.114.0 with SessionStart and Stop,⁷⁰ and made hooks stable in v0.124.0 (April 23, 2026).⁸⁵ The engine shipping in rust-v0.150.0 registers twelve events (HOOK_EVENT_NAMES in codex-rs/hooks/src/lib.rs) – eleven at v0.149.1, with Interrupt added as the twelfth in v0.150.0¹³² – and the legacy names are gone from the configurable surface: AfterToolUse no longer appears anywhere in the source tree, and AfterAgent survives only as the internal payload name of the legacy notify bridge.¹²⁴ Hooks run scripts or MCP tools during the agentic loop. Matching hooks from multiple files all run, multiple matching command hooks for one event launch concurrently, and every non-managed hook must be reviewed and trusted before it runs.¹²⁴ v0.148.0 extends the engine: hooks can run commands asynchronously and can invoke MCP tools – set async = true on a command handler to let it run in the background while Codex continues, or use an mcp_tool handler to reach the same MCP servers the agent uses.¹¹⁸¹²⁴

Available Hook Events

Hosted tools such as WebSearch do not pass through the hook path, and some specialized tool paths can opt out; OpenAI’s own framing is “a useful guardrail, not a complete enforcement boundary.”¹²⁴

Hook Configuration

Hooks are organized in three levels – an event, a matcher group, and one or more handlers – and live either in hooks.json (~/.codex/hooks.json, <repo>/.codex/hooks.json, or a plugin’s hooks/hooks.json) or inline in config.toml and requirements.toml. Project-local hooks load only when the project .codex/ layer is trusted.¹²⁴ The inline TOML form:

# ~/.codex/config.toml or <repo>/.codex/config.toml
[[hooks.SessionStart]]
matcher = "startup|resume"

[[hooks.SessionStart.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/session_start.py"
additionalContextLimit = 5000

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use_review.py"
async = true
timeout = 120

Handler fields: type (command or mcp_tool; prompt and agent handlers are parsed but skipped), command, timeout in seconds (600 by default; SessionEnd 1 second, up to 3), statusMessage, additionalContextLimit (how much additionalContext reaches the model before Codex saves the full text to disk and sends a preview), commandWindows (Windows-only override), and async. Commands run with the session cwd as their working directory, so repo-local hooks should resolve paths from git rev-parse --show-toplevel rather than a relative .codex/hooks/... path.¹²⁴

Review and trust. Codex records trust against each non-managed hook’s current hash; new or changed hooks are marked for review and skipped until trusted. Run /hooks to inspect hook sources, review, trust, or disable individual hooks; when hooks need review at startup, Codex prints a warning pointing at /hooks. Managed hooks from system, MDM, cloud, or requirements.toml sources are trusted by policy and cannot be disabled from the user hook browser. --dangerously-bypass-hook-trust runs enabled hooks without persisted trust for one invocation, for automation that vets hook sources elsewhere.¹²⁴

The SessionStart hook’s stdout feeds into the model’s context, making it ideal for injecting dynamic information (dates, branch names, environment variables) at session start.

Replicating Claude Code Hook Patterns

Codex uses the same event names as Claude Code for the events it implements, so most hook configs port by moving the JSON into hooks.json and trusting it through /hooks:

Expert tip: New hook events still ship in releases – v0.150.0 added the Interrupt event (¹³²) – so check HOOK_EVENT_NAMES in codex-rs/hooks/src/lib.rs and the Codex changelog for the current list.

In-TUI hook browser (v0.129.0): Run /hooks in the TUI to discover available hooks, see which are currently active, and toggle individual hooks without editing config.toml. Useful when troubleshooting a misbehaving plugin-bundled hook or temporarily disabling a PostToolUse linter for a heads-down editing session.⁸⁹

What Is MCP (Model Context Protocol)? [EXPERIMENTAL]

MCP extends Codex’s capabilities by connecting to external tools and services. The codex mcp command group is currently marked experimental, and commands and config format may change between releases. Codex supports two transport types: STDIO (local processes) and Streamable HTTP (remote servers).¹¹

v0.121.0 MCP changes: Tools are now registered with a namespace, so tool names in listings appear as <server>:<tool> rather than bare names — update any scripts or prompts that grep against unqualified tool names. A new supports_parallel_tool_calls flag is plumbed through to included MCPs, enabling parallel execution for servers that declare support. Sandbox-state metadata now flows through MCP tool metadata so servers can adapt behavior (e.g., warn if running under a read-only sandbox). The custom codex/sandbox-state request has been removed — use the metadata path instead. Phase 3 of the MCP Apps rollout lands here with tool-call support; flattened deferred tool calls are now supported for servers using the deferred-call pattern.⁸²

v0.142.2 MCP changes (June 25, 2026): MCP tools now use tool search by default when supported — instead of loading every tool definition upfront, Codex discovers tools on demand, improving discovery in tool-heavy setups while staying compatible with older models and providers. Remote stdio MCP servers also accept absolute working directories written in the remote platform’s path format (a Windows-style path from a macOS client, or vice versa).¹⁰⁵

v0.147.0 MCP changes (August 7, 2026): Codex adds opt-in support for the MCP 2026-07-28 protocol revision — paginated discovery (large tool catalogs stream in pages instead of one oversized listing), multi-round requests (a server can hold a multi-step exchange within one logical request), and non-blocking server startup, with cached MCP tools exposed before the server finishes starting so a slow server no longer stalls session launch. Opt-in, so servers on the older revision keep working unchanged.¹¹⁶

v0.151.0 MCP changes (August 29, 2026): Optional MCP servers get a configurable startup grace period – mcp_optional_startup_grace_ms (default 1,000 ms) controls how long tool catalog capture waits for optional servers, 0 disables the shared grace so optional servers fall back to their configured startup_timeout_sec, and updated values apply during runtime and MCP configuration refreshes. Extensions can also inspect or replace MCP tool results before they reach the model: ToolLifecycleContributor::on_mcp_tool_result runs before MCP completion is published and before the result is prepared for the model, for successful and error results alike, including through Code Mode.¹³⁴

v0.152.0 MCP changes (September 1, 2026): Three additive changes. openai/elicitation form requests land: Codex advertises form support when the client declares an object-valued form capability, handles openai/elicitation/create requests, and forwards their metadata and opaque schema through the app server as openaiForm (preserving x-openai-* annotations); legacy openai/form handling stays independent, and the TUI automatically declines form requests it cannot render. Per-tool output limits: each entry under an MCP server’s tools configuration accepts a positive output_token_limit (for example [mcp_servers.context7.tools.search] with output_token_limit = 2000); the most restrictive limit wins when plugin and user policies overlap, and the effective budget is carried in conversation history so tool output, post-tool hook responses, and resumed sessions truncate at the same limit – additive alongside the global tool_output_token_limit. Package-style server names: MCP server names may now contain :, @, /, and . (so npm:@modelcontextprotocol/server-sequential.thinking is a legal name), preserved across mcp add/get/list/remove, runtime tool namespaces, and OAuth credential lookup, with non-bare names quoted in generated config.toml recovery hints.¹³⁸

Configuring MCP Servers

STDIO servers (local processes):

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

HTTP servers (remote):

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

CLI Management

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

In-session: /mcp shows active servers and available tools. /mcp verbose (v0.123.0+)⁸⁴ returns full server diagnostics, resources, and resource templates — useful when a server is failing to load or tools aren’t appearing where expected. Plain /mcp stays fast. As of v0.144.0, MCP tools can request authentication interactively without an experimental opt-in — a server that needs auth mid-session prompts through the normal flow instead of failing until you pre-authenticate with codex mcp login.¹⁰⁷

Plugin MCP loading (v0.123.0+) accepts both the standard mcpServers schema and top-level server maps in .mcp.json, so plugins authored against either convention load cleanly.⁸⁴

MCP user verification (v0.155.0, supported Macs): local TUI sessions on supported Macs can verify MCP requests with Touch ID, signed by the Secure Enclave (#43624, #43712, #43715). The verification identity is restricted to the workspace it was enrolled in (#43524), and verification carries natively into MCP tool continuations (#44346). First watched on the v2.68 promotion checklist, cut from 0.154.0 with the alpha.7 cluster, shipped in 0.155.0.¹⁵⁶

Running Codex AS an MCP Server

Removed (v0.154.0, September 9, 2026). The codex mcp-server command and the standalone codex-mcp-server binary are gone as of stable 0.154.0 (#42993), completing the August 24, 2026 deprecation. The official changelog (September 5, 2026): “The codex mcp-server command and standalone codex-mcp-server binary have been removed after their deprecation on August 24, 2026. Update integrations that launch either command before upgrading Codex.” Integrations should target the app-server protocol, the interface behind the VS Code extension and desktop app (authentication, conversation history, approvals, streamed agent events) – which the removal entry itself labels experimental and “isn’t supported for production workloads” – or, from Claude Code, the Codex plugin for Claude Code: “Use Codex from Claude Code to review code or delegate tasks.” Connecting Codex TO external MCP servers (codex mcp ..., /mcp) is unaffected.^125152153

On CLI 0.153.4 and earlier the command still exists (deprecated since August 24, 2026; since v0.149.0 it prints warning: `codex mcp-server` is deprecated and will be removed in a future release. to stderr and then starts anyway, PR #39657), so pinning npm install -g @openai/codex@0.153.4 is the stopgap if an integration cannot migrate immediately:^12125148152

codex mcp-server                        # REMOVED in 0.154.0; works only on 0.153.x and earlier (deprecated, warns)

On 0.153.x and earlier the server exposes two tools: 1. codex(): Start a new session with prompt, sandbox, model, and approval parameters 2. codex-reply(): Continue an existing session with threadId and prompt

Use with the Agents SDK (Python) – CLI 0.153.4 or earlier only:

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "@openai/codex@0.153.4", "mcp-server"]},  # pin: removed in 0.154.0
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

Notable MCP Servers

Practical Patterns

Pattern 1: Context-aware development — Pair Context7 with your framework docs so Codex always has current API references:

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Pattern 2: Output limits — MCP tool responses are truncated at ~25K characters by default. For tools that return large payloads (database queries, log captures), use enabled_tools to restrict to specific tools and keep responses focused.

Pattern 2a: Multimodal tool output (v0.107.0) — Custom tools can now return multimodal output (images, rich content) alongside text. This enables tools that produce visual artifacts — screenshots, diagrams, chart renders — to pass them directly to the model for analysis.⁶²

Pattern 3: Enterprise MCP governance — Lock down which MCP servers developers can use via requirements.toml:

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

Any server not matching an identity in requirements.toml will be blocked at startup. See Enterprise Deployment for full policy configuration.

Code Mode [EXPERIMENTAL]

Code mode (v0.114.0) provides more isolated coding workflows by restricting the agent’s scope to code-focused operations.⁷⁰ When enabled, the agent focuses on reading, writing, and testing code without broader system interactions.

As of v0.139.0, code mode can call standalone web search directly — including from nested JavaScript tool calls — and receives plaintext results, so a code-mode flow can fetch live information without leaving the sandboxed coding context.¹⁶⁵ v0.146.0 extends standalone web search to compatible custom model providers, so the capability is no longer limited to OpenAI-hosted models.¹¹⁴

v0.146.0 let app-server connect to remote Code Mode hosts, so the code-mode runtime no longer has to live on the same machine as the client – originally over WebSocket.¹¹⁴ v0.151.0 removes the WebSocket transport (#40692): app server --code-mode-host connections accept only http:// and https:// gRPC endpoints, and the standalone code-mode host is limited to stdio and gRPC listeners – at tag rust-v0.151.0 its listener doc reads verbatim “Transport endpoint: stdio, stdio://, or grpc://IP:PORT.” WebSocket survives only as an optional endpoint that streams raw OTLP trace batches for tracing, not as a session transport.¹³⁵

This feature is experimental. Check release notes for updates.

JavaScript REPL Runtime [REMOVED]

Codex v0.100.0 added an experimental JavaScript REPL runtime (js_repl) and v0.106.0 promoted it through the /experimental surface.⁶⁰ That guidance is now historical. In v0.128.0, the release changelog includes “Remove js_repl feature,” and the current feature list marks both js_repl and js_repl_tools_only as removed.⁸⁶

Do not add features.js_repl = true to new configs. Use shell commands, checked-in scripts, MCP tools, or a Codex skill with a scripts/ directory when you need repeatable executable logic.

What Are Skills?

Skills are reusable, task-specific capability packages that Codex loads on demand. They follow the open agent skills standard.¹³

Skill Structure

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

Discovery Locations

Codex stores user-installed skills in $CODEX_HOME/skills (default: ~/.codex/skills), including built-in system skills under .system/. Codex supports symlinked skill folders.

Creating a Skill

SKILL.md format:

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

Metadata (agents/openai.yaml):

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

Invoking Skills

• Explicit: /skills menu or $skill-name mention in prompt
• Implicit: Codex auto-detects matching skills from task description (if allow_implicit_invocation: true)
• Creator: Use $skill-creator to interactively build a new skill
• Installer: Use $skill-installer install <name> to install community skills
• Executor-provided (v0.146.0): Codex discovers skills offered by the executor and reads their associated resources, including skills you select explicitly¹¹⁴

Context budgets truncate skill catalogs. v0.146.0 retains more available skills under tight context and warns when a catalog has to be truncated.¹¹⁴ Before this, a large skill library could be silently trimmed, so a skill you expected to be in scope simply was not offered. If you rely on implicit invocation across many skills, watch for that warning.

Enable/Disable

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Skills vs Slash Commands

Debugging Skills

If a skill isn’t activating:

1. Check discovery: /skills should list it in the TUI
2. Verify path: Ensure the skill folder is in a recognized location (~/.codex/skills/, project root, or /etc/codex/skills/)
3. Check enabled: Skills with enabled = false in config.toml won’t load
4. Check implicit activation: If relying on auto-detection, ensure allow_implicit_invocation: true in agents/openai.yaml
5. Use keywords: Include the skill’s description terms in your prompt to improve implicit matching

Production Example: Deploy Skill

A complete multi-file skill showing references and scripts working together:

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md:

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

Invoke with: $deploy to staging or $deploy production with canary rollout

Plugins

Plugins unify skills, MCP entries, hooks, and app connectors into a single installable package (v0.110.0+).⁶⁵ As of v0.117.0, plugins are first-class citizens: product-scoped plugins sync automatically at startup and /plugins provides an in-TUI browser for discovery and management.⁷⁵ v0.128.0 expanded plugin workflows with marketplace installation, remote bundle caching, remote uninstall APIs, plugin-bundled hooks, hook enablement state, and external-agent config import.⁸⁶ v0.129.0 (May 7, 2026) adds plugin workspace sharing (push a plugin set to teammates without re-publishing), share access controls (per-recipient enable/disable, revoke), source filtering (limit which marketplaces a workspace pulls from), and marketplace operations that can be invoked directly from the /plugins browser instead of the CLI.⁸⁹ v0.133.0 (May 21, 2026) makes plugin discovery easier to audit: list output is marketplace-aware, installed versions are visible, marketplace roots are listed, and remote plugin collections can be surfaced without guessing which registry a result came from.⁹⁸ v0.130.0 (May 8, 2026) makes plugin packaging more transparent and the share workflow more controllable:⁹¹

• Bundled hooks visible in plugin details. The /plugins detail view now lists every lifecycle hook a plugin bundles (SessionStart, UserPromptSubmit, Stop, etc.). Before installing a plugin, you can see exactly which hooks it will register against your session — no more surprise hook side effects from a plugin you trust on its tools alone.
• Plugin share metadata in shareContext. When a plugin is shared from a workspace, the share-link payload now exposes link metadata (creator, scope, freshness) so receiving sessions can show provenance and decide whether to accept.
• Discoverability controls on share settings. Share settings expose a discoverability toggle so teams can publish plugins to specific workspaces or recipient lists without making them generally listable across an organization.

v0.143.0 (July 8, 2026) turns remote plugins on by default. Remote plugins are now enabled without an opt-in flag, the /plugins catalog gains richer rows (npm marketplace sources alongside git and local), and each entry shows both its remote and locally installed versions so drift is visible at a glance.¹⁰⁶ For a team standardizing on a shared plugin set, remote-by-default removes the per-machine enablement step that used to gate rollout.

Plugin Sources

As of v0.147.0, plugin search spans local, personal, workspace, and remote catalogs in one query — you search for a capability, not for the catalog that happens to hold it. Combined with portable Agent Plugin packages, a plugin built in one environment installs cleanly in another instead of being tied to the machine or workspace where it was authored.¹¹⁶

Plugin Discovery

Codex tells the model which plugins are enabled at session start (v0.111.0), improving discovery of installed MCPs, apps, and skills.⁶⁵ The model can suggest relevant plugins during a session based on the task context. In v0.117.0, product-scoped plugins are synced at startup, ensuring the latest plugin catalog is available without manual intervention.⁷⁵ As of v0.142.0, the /plugins menu organizes remote plugins into OpenAI Curated, Workspace, and Shared with me sections, and eligible turns can recommend and install relevant plugins inline.¹⁰⁴ As of v0.151.0, plugin/list and plugin/installed load the effective plugin configuration for every requested cwd – local marketplaces combine in request order, installed and enabled state merges across repositories, and invalid project configurations are reported through marketplaceLoadErrors without dropping valid local catalogs or globally enabled remote catalogs.¹³⁴

@plugin Mentions (v0.112.0+)

Reference any installed plugin directly in chat with @plugin-name.⁶⁸ When you mention a plugin, its context (capabilities, tools, configuration) is automatically included in the model’s context window — no need to describe what the plugin does.

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

This works with any installed plugin, including custom skills, MCP servers, and app connectors.

Plugin Marketplace (v0.113.0+)

The plugin marketplace now includes richer discovery with metadata, categories, and ratings.⁶⁹ Install-time auth checks verify that plugins requiring API keys or OAuth have valid credentials before installation. An uninstall endpoint cleanly removes plugins and their associated configuration.

Adding Third-Party Marketplaces (v0.121.0+)

Current OpenAI Codex docs keep marketplace source management under codex plugin marketplace. This formalizes third-party plugin distribution beyond OpenAI’s first-party marketplace and supports GitHub repo shorthand, HTTP(S) Git URLs, SSH URLs, and local marketplace root directories; use --ref to pin a Git ref and repeat --sparse PATH only for Git-backed marketplace repos.⁹³

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add git@example.com:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

Once added, a marketplace’s plugins appear in the /plugins browser alongside the default ones. App-server callers (IDE/desktop integrations) have a parallel endpoint to register marketplaces programmatically.⁸²

Security consideration: Third-party marketplaces run arbitrary plugin code with your Codex permissions. Vet sources before adding them, and prefer sandboxed execution during first runs.

Agent Plugins: the Cross-Vendor Standard (v0.146.0–v0.147.0)

“Agent Plugins” is not just a Codex feature name — it is an open, vendor-neutral packaging standard, published as Agent Plugins 1.0.0 on August 6, 2026, whose official site summarizes it as “A portable package format for reusable components that extend AI agents.”¹⁶¹ A plugin is a directory with a required plugin.json manifest (a closed schema of exactly ten permitted top-level fields — $schema, name, version, description, author, homepage, repository, license, keywords, extensions — where “Clients MUST report and ignore each unknown field”), an optional skills/ folder (each immediate child directory containing a SKILL.md is one skill), an optional mcp.json declaring stdio, Streamable HTTP, or legacy HTTP+SSE servers, and optional reverse-domain client-namespace directories that other clients “MUST ignore.” Its normative scope is packaging: the spec “defines the canonical Agent Plugins Specification v1.0.0 for packaging reusable components that extend AI agents into distributable plugins” — Agent Skills and MCP keep their own specifications underneath it.¹⁶¹

The governance is the story. Vercel initiated the proposal and developed the 1.0 specification with Amazon, Anysphere (Cursor), GitHub, Microsoft, and OpenAI; the spec repository’s maintainer roster spans Amazon, Cursor, Microsoft, OpenAI, and Vercel, and Google announced on launch day that it is joining the core maintainers.¹⁶¹ The named launch clients span ChatGPT, Codex, Cursor, GitHub Copilot, Kiro, and VS Code. One conspicuous absence: Anthropic, which created the underlying Agent Skills format and MCP itself, is not among the maintainers — Claude Code keeps its own plugin format, and Codex bridges the gap from its side with the Claude Code marketplace source (v0.146.0) and /import.¹⁶¹

In Codex terms: v0.146.0 adds Agent Plugins manifests, workspace plugin publishing, and two additional plugin marketplaces — Amazon Bedrock and Claude Code¹¹⁴ — and v0.147.0 completes the loop with portable Agent Plugins installation and search across local, personal, workspace, and remote catalogs.¹¹⁶ Workspace publishing is the operationally useful half for teams: publish plugins into your own workspace instead of standing up a public marketplace or asking every developer to add a Git source by hand.

The release notes announce the Codex surfaces without publishing their configuration keys or CLI syntax. This entry records that the capability landed and what the standard specifies, not how to drive it from Codex — treat the manifest-authoring workflow and any codex plugin publish invocation as unverified until OpenAI’s docs cover them.

Managing Plugins

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace
codex plugin list                        # List plugins; includes remote catalog entries (v0.153.0)
codex plugin list --json                 # JSON adds source, version, install + auth policy (v0.153.0)

v0.153.0 extends the plugin CLI from marketplace management to plugin-level operations against remote marketplaces: codex plugin list includes remote catalog entries (with their source, version, install policy, and authentication policy in JSON output), and remote plugins can be added and removed through the existing plugin CLI. Remote catalogs are cached by scope and collection – fresh cached results are preferred, an add request that misses a plugin in the cache refetches once, and the local curated catalog is preserved when an unfiltered remote listing fails (errors still surface for explicitly selected remote marketplaces).¹⁴⁰

In the TUI, use /plugins (v0.117.0+) to browse, install, and remove individual plugins interactively without leaving your session.⁷⁵

Expert tip: Plugins consolidate what used to require separate MCP config, skill installation, and app connector setup. A single plugin can bundle all three — making team onboarding faster and configuration more portable.

Plan Mode & Collaboration

Plan mode lets Codex design an approach before executing changes. It’s enabled by default (since v0.94.0).¹⁴ See Decision Frameworks for the “Plan Mode vs Direct Execution” decision tree.

Plan mode vs the update_plan tool (v0.152.0): these are two different things, and only one of them is on by default. Plan mode – the collaboration mode this section describes, where Codex proposes before executing – has been enabled by default since v0.94.0 and is unchanged. update_plan is a planning tool the model can call to maintain a structured plan inside a turn, and it shipped opt-in in v0.152.0: tools.update_plan.enabled defaults to false, and while it is disabled Codex also strips the bundled update_plan guidance from its model, collaboration-mode, multi-agent, compaction, prewarm, and goal-continuation prompts (custom base instructions, model catalog instructions, collaboration policies, and user goal text are preserved even when they mention planning). Enable it explicitly with tools.update_plan.enabled = true in config.toml.¹³⁸

Entering Plan Mode

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

In plan mode, Codex:

• Reads files and analyzes the codebase
• Proposes an implementation plan
• Does not make changes until you approve
• Streams the plan in a dedicated TUI view

Steer Mode

Steer mode (enabled by default since v0.98.0) allows you to inject new instructions while Codex is actively working, without interrupting its current task.¹⁴

There are two injection methods:

Practical examples:

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

Steer mode is always active in the TUI. If you prefer to wait until Codex finishes before giving instructions, just type normally after the turn completes — no special mode needed.

TUI Enhancements (v0.105.0–v0.106.0)

Syntax highlighting (v0.105.0): The TUI now syntax-highlights fenced code blocks and diffs inline. Use /theme to choose a color scheme.⁶¹

New TUI commands (v0.105.0+):⁶¹

Voice transcription (v0.105.0, experimental): Press spacebar to dictate prompts via voice transcription. This feature is experimental and may require microphone permissions.⁶¹ As of v0.107.0, realtime voice sessions support microphone and speaker device selection, allowing you to choose specific audio input/output hardware.⁶² Removed in v0.140.0, returned in v0.145.0: the experimental /realtime voice controls and their audio dependencies were dropped from the TUI in v0.140.0 (spacebar voice transcription was unaffected).¹⁰² v0.145.0 brings voice back in a new form: audio inputs and audio tool outputs in common local audio formats, plus streaming realtime V3 conversations.¹¹² v0.155.0 and v0.156.0: live voice conversations. v0.155.0 (September 17, 2026) added /voice as an experimental, opt-in feature: a live conversation with a streaming transcript and microphone controls, enabled through /experimental on supported builds (#43581, #43651, #44331), with a configurable mute shortcut (#43690) and signed voice resources in the macOS packages (#43983). v0.156.0 (September 22, 2026) made it stable and on by default (#44921), and the docs changelog announced it the same day: “Voice conversations are enabled by default, with an F8 toggle, a /voice settings picker, and bundled audio runtimes for Linux and Windows.” To turn it off, set realtime_conversation = false under [features] in config.toml. The CLI slash-command reference still does not list /voice, and the docs Voice feature page covers ChatGPT Voice in the desktop app, a separate surface.¹⁵⁶¹⁶⁹

Other improvements:

• Long links now remain clickable even when wrapped across TUI lines (v0.105.0)⁶¹
• Local file links render with improved formatting (v0.106.0)⁶⁰
• TUI markdown keeps web links clickable via OSC 8 metadata, and cramped tables fall back to readable key/value records without losing link targets (v0.136.0)¹⁶⁸
• Markdown links appear as clickable labels in supported terminals, with visible URLs retained elsewhere (v0.150.0)¹³²
• Ctrl+C handling for sub-agents fixed to properly terminate child processes (v0.106.0)⁶⁰

Memory System

Codex has a persistent memory system (v0.100.0+) that stores facts, preferences, and project context across sessions.²⁴

Memory Commands

Memories are stored in markdown files under ~/.codex/memory/. Codex loads them at session start and uses them to inform behavior across all future sessions.

What to Store

Memories work best for persistent preferences and project facts:

• Project conventions: “This project uses tabs, not spaces” or “API responses always include a meta field”
• Tool preferences: “Use pnpm instead of npm” or “Run tests with pytest -x --tb=short“
• Architecture decisions: “The auth module is in src/core/auth/, not src/middleware/“
• Workflow preferences: “Always run the linter before showing me a diff”

Memory in Pipelines

When running codex exec, memories are loaded automatically. This means CI/CD pipelines and scripts benefit from the same context as interactive sessions — no need to repeat instructions in every invocation.

Memory Refinements (v0.101.0–v0.107.0)

• Secret sanitization: Memories are automatically scanned for secrets before being written to disk
• CWD awareness: Memory files now include the working directory context for project-specific recall
• Developer message exclusion: Developer/system messages are excluded from phase-1 memory input, improving memory quality by focusing on user interactions
• Diff-based forgetting (v0.106.0): Memory now uses diff-based forgetting to remove stale facts, keeping the memory store lean and relevant over time⁶⁰
• Usage-aware selection (v0.106.0): Memory retrieval is now usage-aware, prioritizing frequently accessed and recently relevant memories⁶⁰
• Configurable memories (v0.107.0): Memories are now fully configurable. Use codex debug clear-memories to reset all stored memories for a clean slate — useful when switching contexts between unrelated projects or when memory state has drifted⁶²
• Phase-2 model upgrade (v0.121.0): The phase-2 memory consolidation model is now gpt-5.4 (up from the prior default). The phase-2 pipeline runs between sessions to distill phase-1 transcripts into durable facts; the model change improves recall quality at the same token cost.⁸²
• TUI memories menu (v0.121.0): A new in-session UI exposes memory mode, individual memory deletion, and a reset button. Memory reset now preserves past rollouts rather than invalidating them, so resetting clears the future recall surface without breaking session replay.⁸²

Memory vs AGENTS.md