Advanced Codex Usage

September 12, 2026 release refresh

Updated for Codex CLI 0.154.0 (September 9). npm latest=0.154.0 and alpha=0.155.0-alpha.3.10 were checked on September 12, 2026 KST.

• Sessions: experimental --worktree and /worktree create isolated checkouts for new or forked sessions, with browse/resume support. Inline questions accept choices or free text while work continues.
• Extensions and approvals: existing sessions refresh installed plugin tools, skills, and hooks. Failed MCP OAuth refreshes surface sign-in without replaying rejected calls. Resume/fork preserve permissions, and new user instructions invalidate stale automatic approvals.
• Compatibility: codex mcp-server and the standalone codex-mcp-server were removed. External MCP connections through codex mcp remain supported. Evaluate migration to experimental codex app-server; the official documentation does not support production workloads on that command.
• Editing: /copy preserves formatting and supports status output; Vim gains R replace mode. Windows gains a shared background server and daemon management.

Sources: official changelog, npm dist-tags.

Previous verification snapshot (September 5, 2026)

Codex is useful as an individual coding agent, but its real leverage appears when teams standardize configuration, safety rules, automation, context, and review practices.

This handbook is for senior developers and engineering leads who already use Codex and want to make it reliable in shared repositories and team workflows.

• GPT-6 Astra (released 2026-09-03): gpt-6-astra is now Codex's top model. It requires CLI 0.153.0 or later and, from 0.153.4, is the bundled default when no model is explicitly configured. It has a 1,050,000-token context window, 128K max output, API pricing of $10 input / $1 cached input / $50 output per 1M, and an April 30, 2026 knowledge cutoff. Teams that pin model in config.toml are unaffected by the default change, so adopt it deliberately.

• Astra security classification: OpenAI classifies Astra as its first model to reach the Critical cybersecurity capability level under the Preparedness Framework. Narrow /permissions, sandboxing, and auto-approval scope before granting it broad automation.

• CLI 0.153.0–0.153.4: Vim undo/redo, remote marketplace management from the plugin CLI, tui.auto_recap = false, TUI history showing complete patches and individual completed commands, and earlier allowance warnings for Plus and Team. Guardian review history now survives compaction, restarts, and forks, and Full Access skips Guardian reviews for confirmation-only actions. tui.disable_paste_burst and the disabled-by-default features.context_management.experimental_mode also land here.

• CLI 0.152.0: the planning tool is disabled by default (enable with tools.update_plan.enabled = true). MCP server names accept :, @, /, and .; individual MCP tools accept output_token_limit; app-server clients can set thread/shellCommand timeouts beyond one hour; and rate-limit banners gain usage, credit, and plan actions.

• CLI 0.151.0: a configurable discovery grace period for optional MCP servers, extensions that can inspect or replace MCP tool results before the model sees them, per-repository plugin catalog configuration, and nested subagent tokens counted toward root goal budgets.

• CLI 0.150.0–0.150.1: task mentions and agent task messaging, the /copy picker, automatic task titles and /rename suggestions, clickable Markdown links, Interrupt hooks, untrusted-project instruction isolation, persistent managed deny-read policy, image-aware remote compaction, and reliability fixes.

• CLI 0.149.0: the codex agents dashboard, codex queue, /cd//pwd//cwd, broader codex doctor diagnostics, and permission-profile restoration across resume and fork.

• MCP transition: codex mcp-server is deprecated as of August 24; new integrations should use codex app-server while existing callers migrate.

• CLI 0.148.0: /export writes a complete TUI conversation to Markdown, codex exec fork forks non-interactively, the resume picker archives/restores sessions, startup accepts draft prompts, and eligible workspaces see estimated credits/cost. It also adds a built-in Amazon Bedrock Runtime provider, async and MCP hook invocation, and broad resume, OAuth, rendering, and fail-closed sandbox fixes.

• CLI 0.147.0: portable Agent Plugins and catalog search, manually ordered transcript sections, --approve-for-me, Cursor-skill import and conversation sync, and opt-in MCP 2026-07-28 support. Deprecated codex exec --full-auto is removed; use --sandbox workspace-write.

• Model baseline: GPT-6 Astra is the top model; within GPT-5.6 use Sol for the hardest work, Terra for everyday engineering, and Luna for explicit repeated work. GPT-5.4 and GPT-5.4 mini retired from ChatGPT-sign-in Codex on 2026-08-31.

• CLI 0.146.0: named /new and /clear threads, pinning and side-conversation switching, paginated-history forks, Agent Plugin manifests/workspace publishing, additional Bedrock and Claude Code marketplaces, remote Code Mode hosts, custom-provider web search, executor-provided skills, broader proxy handling, and live MCP/App tool refresh.

• CLI 0.145.0: experimental paginated thread history with names, search, memories, and subagent support; broader Cursor/Claude Code /import; Bedrock login; audio; stabilized Multi-agent V2; and secure inline visualization links.

• CLI 0.143.0–0.144.0: remote plugins are enabled by default with npm marketplace sources and local/remote versions; system proxy support covers macOS and Windows PAC/WPAD; codex remote-control pair generates manual pairing codes; MCP tool search is default and interactive/session auth is expanded; app approvals add a writes mode; reset credits show type/expiration and support explicit selection; Ultra warns about high multi-agent concurrency. The releases also harden retired-model compaction recovery, Windows writable-root deletion, terminal-control sanitization, and connector auth refresh.

Operating Model

Maturity Model

Contents