Codex Cheatsheet

A reference page — look things up, don't read it end to end. Concept definitions live in the Codex Glossary; task recipes live in the Codex Cookbook.

All commands, flags, and config keys below are traceable to the official documentation at learn.chatgpt.com/docs (the docs moved off developers.openai.com/codex/*, which now 308-redirects). Anything not verifiable there is either omitted or explicitly marked.

Decision table: which mode do I want?

Situation	Do this	Why
Reading or reviewing code, must not change anything	codex --sandbox read-only	Mechanically impossible to write
Everyday development	Default workspace-write	Writes limited to the workspace
Running in CI, nobody to answer prompts	codex --ask-for-approval never exec "..."	Never blocks on approval
Working in a subdirectory of a monorepo	codex --cd services/api	Keeps attention scoped
Need a directory outside the workspace	codex --add-dir ../shared-lib	Repeatable flag
Need genuinely fresh web information	codex --search	Live fetch instead of the cached index
Task result is nondeterministic	codex cloud exec --env <ID> --attempts 3	Run several times, pick the best
Two separate identities / CI isolation	CODEX_HOME=/path codex ...	Isolates config, sessions, and logs
Switching between two config setups	codex --profile work	Switches config only
Reviewing before a release	/review in the TUI	Diff against the base branch
Config seems to have no effect	/debug-config	Prints the layers actually in effect
Isolated env, parallel attempts, or dispatch from GitHub / Linear / Slack	Codex Cloud · codex cloud exec --env <ID>	Hosted machines, not the laptop
Task is the file or selection already open	IDE extension	Editor context is already attached
Phone must steer / approve a local session	Remote	The connected computer runs the work
Find / confirm / fix vulns in a repo you own	Codex Security	Plugin, CLI/SDK, or Cloud
Host a page without a deploy stack	Sites	Save a version before deploy
Act on a signed-in Chrome tab	Chrome extension · @Chrome	Not @Browser, not the cloud browser
Embed Codex in a product (threads, approvals, events)	App Server	JSON-RPC; not the same as Remote pairing
Call local Codex from code	Codex SDK	TS @openai/codex-sdk / Python openai-codex
CI without installing the CLI yourself	GitHub Action	openai/codex-action@v1
Operate a desktop GUI	Computer Use	Desktop Work / Codex; Windows takes the foreground
Localhost preview or stay out of Chrome	Browser · @Browser	Separate ChatGPT browser profile
Talk instead of type (desktop / iOS Remote)	Voice	Separate rolling Voice allowance
macOS activity as memories / timeline	Computer History	Off by default; needs Memories
Hardware keys for desktop chats	Codex Micro	Work Louder collaboration; not a Codex surface

Glossary index

One line per term. Full definitions are in the Glossary — this table is a lookup aid, not a second definition list.

Term	One-liner	Definition
AGENTS.md	Natural-language project briefing, auto-loaded each run	→
Rules	Structured constraints, trust-gated	→
Sandbox	Hard boundary on file and network access	→
Approval policy	Whether Codex asks before acting	→
Trust level	Whether project-level .codex/ loads at all	→
Profile	Named config bundle, selected with --profile	→
MCP	Protocol for connecting external tools and data	→
Skills	Packaged reusable workflows	→
Hooks	Commands forced to run at lifecycle events	→
Plugins	Distribution format bundling MCP / Skills / Hooks	→
Subagents	Delegated agents, spawned only on request	→
Memories	Cross-session recall of preferences	→
Compaction	Lossy compression of older context	→
Web search mode	disabled / cached / indexed / live enum	→
codex exec	One-shot non-interactive run	→
requirements.toml	Admin policy that narrows what's selectable	→
Chat / Work / Codex	Three ways of working in one app	→
ChatGPT Work	Knowledge-work agent that finishes a reviewable file	→
Sites	ChatGPT-hosted websites and apps (public beta)	→
Codex Cloud	Parallel coding jobs / hosted review in a hosted env	→
IDE extension	Codex beside the open file / selection	→
Remote	Phone steers a paired Mac / Windows host	→
Codex Security	AppSec agent: plugin + CLI/SDK + cloud	→
Chrome extension	Drive signed-in Chrome tabs	→
Computer Use	See and operate desktop GUIs	→
Browser	Built-in desktop browser or Work cloud browser	→
Voice	Live talk in Chat / Work / Codex (desktop; iOS Remote)	→
Computer History	macOS activity → memories and a timeline	→
Codex SDK	Programmatic local threads (TS / Python)	→
GitHub Action	Official openai/codex-action@v1	→
App Server	JSON-RPC used by rich clients and codex --remote	→
Codex Micro	Work Louder hardware for desktop chats	→
Atlas	Standalone browser stopped 2026-08-09	→

Command reference

Starting and running

codex                                   # start an interactive session
codex "explain this codebase to me"     # start with an initial prompt
codex --model gpt-5.6 "..."             # pick the model for this run
codex --cd services/payments "..."      # set the working directory
codex --add-dir ../shared-lib "..."     # add another directory (repeatable)
codex --sandbox read-only "..."         # analysis only, no writes
codex --ask-for-approval never "..."    # never ask for approval
codex --approve-for-me "..."            # auto-reviewed approvals (0.147.0+)
codex --search "..."                    # live web search (bare flag, no argument)
codex --yolo "..."                      # full access; also flips search to live
codex --profile work "..."              # use a named profile
codex -c model_reasoning_effort=high    # override a single config key

Non-interactive / automation

codex exec "run the test suite and fix any failures"
codex exec --json "summarize recent changes"
codex exec resume --last "now add tests for that function"
codex --ask-for-approval never exec "update the changelog"
CODEX_HOME=$(pwd)/.codex codex exec "list active instruction sources"

codex exec logging defaults to RUST_LOG=error.

Sessions

codex resume                  # pick from a session list
codex resume --last           # resume the most recent
codex resume <SESSION_ID>     # resume a specific session
codex resume --all            # list all sessions
codex unarchive <SESSION>     # restore an archived session
codex fork                    # fork a session

Session records: ~/.codex/sessions/. Session IDs come from the picker, /status, or that directory.

Auth and status

codex login
codex login status            # exits 0 when saved credentials are present
codex doctor                  # local diagnostic report
codex logout

There is no codex status subcommand in the official CLI reference. Use /status inside the TUI for the current session.

Images

codex -i screenshot.png "why does this layout break?"
codex --image img1.png,img2.jpg "these two shots show the same bug"

PNG and JPEG are supported.

MCP

codex mcp                     # manage MCP servers from the CLI

Codex can also run as an MCP server — see MCP Server.

Feature flags

codex features list
codex features enable <flag>
codex features disable <flag>

These write to $CODEX_HOME/config.toml and do not accept --profile.

Remote and cloud

codex app-server --listen ws://127.0.0.1:4500     # serve on the machine holding the code
codex --remote ws://127.0.0.1:4500                 # connect from elsewhere
codex remote-control
codex cloud                                        # cloud UI (Ctrl+O reveals environment IDs)
codex cloud exec --env <ENV_ID> "..."
codex cloud exec --env <ENV_ID> --attempts 3 "..."  # 1-4 attempts

--remote accepts ws://, wss://, and unix://. Bearer tokens are only sent over wss:// or local-only ws://. Auth options: --ws-auth capability-token with --ws-token-file / --ws-token-sha256, or --ws-auth signed-bearer-token with --ws-shared-secret-file (plus optional --ws-issuer, --ws-audience, --ws-max-clock-skew-seconds). The client side can read a token from --remote-auth-token-env CODEX_REMOTE_TOKEN.

Shell completion

codex completion bash
codex completion zsh
codex completion fish

If zsh reports command not found: compdef, add autoload -Uz compinit && compinit to your .zshrc before sourcing completions.

Debug logging

codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log

Setting log_dir also enables the plaintext codex-tui.log. Tracing honors RUST_LOG.

Slash commands

Grouped by purpose. The full list is in the official reference.

Group	Commands
Permissions & sandbox	/permissions, /approve, /sandbox-add-read-dir (Windows-native only)
Session lifecycle	/new, /clear, /compact, /fork, /resume, /archive, /delete, /stop (alias /clean), /exit, /quit
Inspect	/status, /usage, /diff, /debug-config, /ps (needs unified_exec), /mcp (/mcp verbose)
Model & behavior	/model, /fast, /plan, /goal (max 4,000 chars), /personality, /raw
Extensions	/agent, /apps, /plugins, /hooks, /skills, /memories
Editing & review	/review, /init, /import, /mention, /copy
Appearance	/theme, /statusline, /title, /keymap, /vim, /ide
Misc	/feedback, /logout, /experimental

/usage accepts daily, weekly, and cumulative. /debug-config prints the config layer order plus allowed_approval_policies, allowed_sandbox_modes, mcp_servers, rules, enforce_residency, and experimental_network. /import migrates a Claude Code or Cursor setup and works in the local TUI only. Personalities are friendly, pragmatic, and none.

Keyboard reference (TUI)

Key	Action
@	Fuzzy file search across the workspace root
! prefix	Run a shell command under the current approval/sandbox settings
$app-slug	Mention a connector app
Tab	Queue a follow-up message
Esc Esc	On an empty composer, edit the previous message (Enter forks from there)
Up / Down	Draft history
Ctrl+R	Search prompt history
Ctrl+G	Open $VISUAL / $EDITOR
Ctrl+L	Clear the screen
Ctrl+O	Copy the last output (same as /copy)
Ctrl+C	Interrupt / exit

Config quick reference

Config lives at ~/.codex/config.toml (user level). Profiles are $CODEX_HOME/<name>.config.toml.

Permissions and sandbox

approval_policy = "on-request"     # untrusted | on-request | never | { granular = { ... } }
sandbox_mode = "workspace-write"   # read-only | workspace-write | danger-full-access

[sandbox_workspace_write]
writable_roots = ["/tmp/build"]
network_access = false
exclude_slash_tmp = false
exclude_tmpdir_env_var = false

[projects."/path/to/repo"]
trust_level = "trusted"            # trusted | untrusted

approval_policy = "on-failure" is deprecated. Granular form: { granular = { sandbox_approval, rules, mcp_elicitations, request_permissions, skill_approval } }.

Model

model = "gpt-5.6"
model_reasoning_effort = "medium"   # minimal | low | medium | high | xhigh (Responses API only)
model_reasoning_summary = "auto"    # auto | concise | detailed | none
model_verbosity = "medium"          # low | medium | high
model_context_window = 200000
model_auto_compact_token_limit = 150000
review_model = "gpt-5.6"

Web search

web_search = "cached"     # disabled | cached | indexed | live  (default "cached")

indexed permits external web access only when the search index gates the request. --search (bare flag) is the same as live. --yolo / full-access defaults search to live.

The legacy feature flags features.web_search, features.web_search_cached, and features.web_search_request are deprecated — use the top-level web_search enum.

MCP servers

# STDIO
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]
startup_timeout_sec = 10
tool_timeout_sec = 60

# Streaming HTTP
[mcp_servers.internal-api]
url = "https://mcp.example.com/sse"
bearer_token_env_var = "INTERNAL_API_TOKEN"
enabled = true
default_tools_approval_mode = "prompt"   # auto | prompt | approve
enabled_tools = ["search", "read"]

mcp_servers is a table keyed by server id. There is no name key and no type key, and it is not an array of tables.

Context and instruction files

project_doc_max_bytes = 65536                                # default 32 KiB
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

Environment variables passed to commands

[shell_environment_policy]
inherit = "core"            # all | core | none
include_only = ["PATH", "HOME", "LANG"]
exclude = ["AWS_*", "*_SECRET"]
set = { CI = "1" }
ignore_default_excludes = false

This is the mechanism for controlling which environment variables reach spawned commands.

Subagents

[agents]
max_depth = 1
max_threads = 6
job_max_runtime_seconds = 1800

[agents.reviewer]
description = "read-only adversarial reviewer"
config_file = "reviewer.config.toml"

Hooks

[[hooks.PostToolUse]]
[[hooks.PostToolUse.hooks]]
type = "command"
command = ["pnpm", "lint", "--fix"]
command_windows = ["pnpm.cmd", "lint", "--fix"]

Events: PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SubagentStart, SubagentStop, UserPromptSubmit, Stop. Only command hooks execute today.

Feature flags and misc

[features]
memories = false        # off by default
multi_agent = true
hooks = true
fast_mode = true
undo = false

personality = "pragmatic"      # none | friendly | pragmatic
commit_attribution = "Codex <noreply@openai.com>"
hide_agent_reasoning = false
log_dir = "~/.codex/log"

[history]
persistence = "save-all"       # save-all | none

[tui]
vim_mode_default = false
theme = "dark"

Profiles

# ~/.codex/work.config.toml
model = "gpt-5.6"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

codex --profile work

Keys that project-level config cannot override

When these appear in .codex/config.toml, they are ignored:

openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, otel

System requirements

Item	Requirement
macOS	12 or later
Linux	Ubuntu 20.04+ / Debian 10+
Windows	Windows 11 via WSL2
Git	2.23 or later (optional)
RAM	4 GB minimum, 8 GB recommended

Source: openai/codex docs/install.md

Common problems

Symptom	Likely cause	What to do
.codex/config.toml has no effect	Project not trusted, or the key can't be set at project scope	Set projects.<path>.trust_level = "trusted"; check the ignored-keys list; run /debug-config
Provider or base-URL setting ignored	Project scope can't override machine-local provider keys	Move it to ~/.codex/config.toml
AGENTS.md guidance ignored	Combined size hit project_doc_max_bytes (32 KiB), or an AGENTS.override.md shadowed it	Trim the file or raise the limit; check for override files
Codex keeps stopping to ask	approval_policy too strict for the context	--ask-for-approval never for automation, or /permissions in the TUI
Codex modifies files during a review	Sandbox allows writes	--sandbox read-only
Web results feel stale	web_search defaults to cached	Use bare --search, or set web_search = "live"
Output quality degrades mid-session	Context is saturated or was compacted	/clear for a new task, or /compact then continue
[[mcp_servers]] fails to parse	Wrong TOML shape	Use [mcp_servers.<id>]
compdef: command not found in zsh	compinit not loaded	Add autoload -Uz compinit && compinit
Managed permission profiles not enforced	Client on 0.137.0 or earlier	Upgrade to 0.138.0+
Need to see what instructions loaded	—	codex --ask-for-approval never "Summarize the current instructions." or enable log_dir

Templates

Minimal AGENTS.md

# Project conventions

## Tooling
- Package manager: pnpm. Do not use npm or yarn.
- Tests: `pnpm test`. Type check: `pnpm typecheck`.

## Boundaries
- Do not modify `legacy/` — it is being decommissioned.
- Schema changes must also update `types/db.ts`.

## Verification
- Run `pnpm test` and `pnpm typecheck` after any change and report the output.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Everyday config.toml

model = "gpt-5.6"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[sandbox_workspace_write]
network_access = false

[projects."/Users/you/work/my-repo"]
trust_level = "trusted"

Read-only reviewer profile

# ~/.codex/review.config.toml
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "never"

codex --profile review "review the uncommitted changes and list only real defects"

CI invocation

codex --ask-for-approval never exec --json \
  "run the test suite; if anything fails, fix it and re-run until green"

Quality sources

The links below are what this tutorial is maintained against. When something here disagrees with them, they win.

Official documentation

Source	Use it for
Codex docs root	Entry point for everything below
Quickstart	Install through first run
Config Reference	The authority on every config key, plus requirements.toml
Environment Variables	CODEX_HOME and friends
Permissions	Approval policy and permission profiles
Sandboxing	Sandbox modes
AGENTS.md	Instruction-chain discovery and merge order
Rules	Structured constraints
Subagents	The [agents] section
MCP	Connecting external tools
MCP Server	Codex as an MCP server
Hooks	Lifecycle events
Plugins	Packaging and distribution
Skills	Authoring skills
Slash commands	The authoritative command list
CLI	CLI surface
IDE Extension	Editor surface
Non-interactive Mode	codex exec
App Server	Remote control
Codex SDK	Programmatic use
GitHub Action	CI integration
Models	Model list and reasoning effort
Prompting	Prompting guidance
Memories	Cross-session memory
Pricing	The only source for plans and quotas — figures change, so read it there
Use ChatGPT	Chat / Work / Codex
Get started with Work	ChatGPT Work
Codex cloud	Hosted coding environments
What's new	Weekly capability changes, including Sol hosted review
Evolving Atlas	Official Atlas retirement
Best practices	Official prompting and workflow guidance
Import	Migrate from Claude Code or Cursor
Sites	Publishing sites
Glossary	Official term list

The docs use a ?surface=cli|app|ide selector. If a page looks like it's describing a different product, check which surface is active.

Release tracking

Source	Use it for
Changelog	What shipped
Feature Maturity	Which features are experimental
openai/codex releases	Version numbers and binaries
openai/codex issues	Known bugs and workarounds
docs/install.md	System requirements and building from source

Stable releases land roughly weekly (0.145.0 → 0.146.0 → 0.147.0), with daily 0.x.0-alpha.N prereleases. Re-verify version-sensitive claims at least every two weeks.

gh release list --repo openai/codex --exclude-pre-releases --limit 5

Related pages

• Codex Glossary — what the concepts mean and why
• Codex Cookbook — task-oriented recipes
• Codex CLI — installation through core features
• Project Integration — wiring Codex into a real project
• Learning Map — the full path