OpenAI - Codex Docs Changes 2026-04-18 18:18 UTC → 2026-05-01 18:29 UTC

24- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.24- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.

25- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.25- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.

26 26 

27In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.27In the `Auto` preset (for example, `--sandbox workspace-write --ask-for-approval on-request`), Codex can read files, make edits, and run commands in the working directory automatically.

28 28 

29Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.29Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.

30 30 

73- `<writable_root>/.codex` is protected as read-only when it exists as a directory.73- `<writable_root>/.codex` is protected as read-only when it exists as a directory.

74- Protection is recursive, so everything under those paths is read-only.74- Protection is recursive, so everything under those paths is read-only.

75 75 

76### Deny reads with filesystem profiles

77 

78Named permission profiles can also deny reads for exact paths or glob patterns.

79This is useful when a workspace should stay writable but specific sensitive

80files, such as local environment files, must stay unreadable:

81 

82```toml

83default_permissions = "workspace"

84 

85[permissions.workspace.filesystem]

86":project_roots" = { "." = "write", "**/*.env" = "none" }

87glob_scan_max_depth = 3

88```

89 

90Use `"none"` for paths or globs that Codex shouldn't read. The sandbox policy

91evaluates globs for local macOS and Linux command execution. On platforms that

92pre-expand glob matches before the sandbox starts, set `glob_scan_max_depth` for

93unbounded `**` patterns, or list explicit depths such as `*.env`, `*/*.env`, and

94`*/*/*.env`.

95 

76### Run without approval prompts96### Run without approval prompts

77 97 

78You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).98You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).

83 103 

84For a middle ground, `approval_policy = { granular = { ... } }` lets you keep specific approval prompt categories interactive while automatically rejecting others. The granular policy covers sandbox approvals, execpolicy-rule prompts, MCP prompts, `request_permissions` prompts, and skill-script approvals.104For a middle ground, `approval_policy = { granular = { ... } }` lets you keep specific approval prompt categories interactive while automatically rejecting others. The granular policy covers sandbox approvals, execpolicy-rule prompts, MCP prompts, `request_permissions` prompts, and skill-script approvals.

85 105 

86Set `approvals_reviewer = "guardian_subagent"` to route eligible approval reviews through the Guardian reviewer subagent instead of prompting the user directly. Admin requirements can constrain this with `allowed_approvals_reviewers`.106### Automatic approval reviews

107 

108By default, approval requests route to you:

109 

110```toml

111approvals_reviewer = "user"

112```

113 

114Automatic approval reviews apply when approvals are interactive, such as

115`approval_policy = "on-request"` or a granular approval policy. Set

116`approvals_reviewer = "auto_review"` to route eligible approval requests

117through a reviewer agent before Codex runs the request:

118 

119```toml

120approval_policy = "on-request"

121approvals_reviewer = "auto_review"

122```

123 

124The reviewer evaluates only actions that already need approval, such as sandbox

125escalations, network requests, `request_permissions` prompts, or side-effecting

126app and MCP tool calls. Actions that stay inside the sandbox continue without an

127extra review step.

128 

129The reviewer policy checks for data exfiltration, credential probing, persistent

130security weakening, and destructive actions. Low-risk and medium-risk actions

131can proceed when policy allows them. The policy denies critical-risk actions.

132High-risk actions require enough user authorization and no matching deny rule.

133Timeouts, parse failures, and review errors fail closed.

134 

135The [default reviewer policy](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md)

136is in the open-source Codex repository. Enterprises can replace its

137tenant-specific section with `guardian_policy_config` in managed requirements.

138Local `[auto_review].policy` text is also supported, but managed requirements

139take precedence. For setup details, see

140[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).

141 

142In the Codex app, these reviews appear as automatic review items with a status such

143as Reviewing, Approved, Denied, Stopped, or Timed out. They can also include a

144risk level for the reviewed request.

145 

146Automatic review uses extra model calls, so it can add to Codex usage. Admins

147can constrain it with `allowed_approvals_reviewers`.

87 148 

88### Common sandbox and approval combinations149### Common sandbox and approval combinations

89 150 

90| Intent | Flags | Effect |151| Intent | Flags | Effect |

91| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |152| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |

92| Auto (preset) | *no flags needed* or `--full-auto` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |153| Auto (preset) | *no flags needed* or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

93| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |154| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |

94| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Codex can only read files; never asks for approval. |155| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Codex can only read files; never asks for approval. |

95| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |156| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |

96| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | [Elevated Risk](https://help.openai.com/articles/20001061) No sandbox; no approvals *(not recommended)* |157| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | [Elevated Risk](https://help.openai.com/articles/20001061) No sandbox; no approvals *(not recommended)* |

97 158 

98`--full-auto` is a convenience alias for `--sandbox workspace-write --ask-for-approval on-request`.159For non-interactive runs, use `codex exec --sandbox workspace-write`; Codex keeps older `codex exec --full-auto` invocations as a deprecated compatibility path and prints a warning.

99 160 

100With `--ask-for-approval untrusted`, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.161With `--ask-for-approval untrusted`, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.

101 162 

141 202 

142```bash203```bash

143# macOS204# macOS

144codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...205codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...

145# Linux206# Linux

146codex sandbox linux [--full-auto] [COMMAND]...207codex sandbox linux [--permissions-profile <name>] [COMMAND]...

208# Windows

209codex sandbox windows [--permissions-profile <name>] [COMMAND]...

147```210```

148 211 

149The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).212The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).

153Codex enforces the sandbox differently depending on your OS:216Codex enforces the sandbox differently depending on your OS:

154 217 

155- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.218- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.

156- **Linux** uses the `bwrap` pipeline plus `seccomp` by default. `use_legacy_landlock` is available when you need the older path. In managed proxy mode, the default `bwrap` pipeline routes egress through a proxy-only bridge and fails closed if it can’t build valid local proxy routes.219- **Linux** uses `bwrap` plus `seccomp` by default.

157- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux 2 (WSL2)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). WSL1 was supported through Codex `0.114`; starting in `0.115`, the Linux sandbox moved to `bwrap`, so WSL1 is no longer supported. When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.220- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux 2 (WSL2)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). WSL1 was supported through Codex `0.114`; starting in `0.115`, the Linux sandbox moved to `bwrap`, so WSL1 is no longer supported. When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.

158 221 

159If you use the Codex IDE extension on Windows, it supports WSL2 directly. Set the following in your VS Code settings to keep the agent inside WSL2 whenever it's available:222If you use the Codex IDE extension on Windows, it supports WSL2 directly. Set the following in your VS Code settings to keep the agent inside WSL2 whenever it's available:

176 239 

177See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.240See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.

178 241 

179When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.242When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration blocks the namespace, setuid `bwrap`, or `seccomp` operations that Codex needs.

180 243 

181In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.244In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.

182 245 

246### Run Codex in Dev Containers

247 

248If your host cannot run the Linux sandbox directly, or if your organization already standardizes on containerized development, run Codex with Dev Containers and let Docker provide the outer isolation boundary. This works with Visual Studio Code Dev Containers and compatible tools.

249 

250Use the [Codex secure devcontainer example](https://github.com/openai/codex/tree/main/.devcontainer) as a reference implementation. The example installs Codex, common development tools, `bubblewrap`, and firewall-based outbound controls.

251 

252Devcontainers provide substantial protection, but they do not prevent every

253 attack. If you run Codex with `--sandbox danger-full-access` or

254 `--dangerously-bypass-approvals-and-sandbox` inside the container, a malicious

255 project can exfiltrate anything available inside the devcontainer, including

256 Codex credentials. Use this pattern only with trusted repositories, and

257 monitor Codex activity as you would in any other elevated environment.

258 

259The reference implementation includes:

260 

261- an Ubuntu 24.04 base image with Codex and common development tools installed;

262- an allowlist-driven firewall profile for outbound access;

263- VS Code settings and extension recommendations for reopening the workspace in a container;

264- persistent mounts for command history and Codex configuration;

265- `bubblewrap`, so Codex can still use its Linux sandbox when the container grants the needed capabilities.

266 

267To try it:

268 

2691. Install Visual Studio Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).

2702. Copy the Codex example `.devcontainer` setup into your repository, or start from the Codex repository directly.

2713. In VS Code, run **Dev Containers: Open Folder in Container…** and select `.devcontainer/devcontainer.secure.json`.

2724. After the container starts, open a terminal and run `codex`.

273 

274You can also start the container from the CLI:

275 

276```bash

277devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

278```

279 

280The example has three main pieces:

281 

282- `.devcontainer/devcontainer.secure.json` controls container settings, capabilities, mounts, environment variables, and VS Code extensions.

283- `.devcontainer/Dockerfile.secure` defines the Ubuntu-based image and installed tools.

284- `.devcontainer/init-firewall.sh` applies the outbound network policy.

285 

286The reference firewall is intentionally a starting point. If you depend on domain allowlisting for isolation, implement DNS rebinding and DNS refresh protections that fit your environment, such as TTL-aware refreshes or a DNS-aware firewall.

287 

288Inside the container, choose one of these modes:

289 

290- Keep Codex's Linux sandbox enabled if the Dev Container profile grants the capabilities needed for `bwrap` to create the inner sandbox.

291- If the container is your intended security boundary, run Codex with `--sandbox danger-full-access` inside the container so Codex does not try to create a second sandbox layer.

292 

183## Version control293## Version control

184 294 

185Codex works best with a version control workflow:295Codex works best with a version control workflow:

12 12 

13The Codex app is available on macOS and Windows.13The Codex app is available on macOS and Windows.

14 14 

15Most Codex app features are available on both platforms. Platform-specific

16exceptions are noted in the relevant docs.

17 

151. Download and install the Codex app181. Download and install the Codex app

16 19 

17 Download the Codex app for Windows or macOS. Choose the Intel build if you’re using an Intel-based Mac.20 Download the Codex app for macOS or Windows. Choose the Intel build if you're using an Intel-based Mac.

18 21 

19 [Download for macOS (Apple Silicon)](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)[Download for macOS (Intel)](https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg)22 [Download for macOS (Apple Silicon)](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)[Download for macOS (Intel)](https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg)

20 23 

63 66 

64Run commands in each thread and launch repeatable project actions.](https://developers.openai.com/codex/app/features#integrated-terminal)[### In-app browser67Run commands in each thread and launch repeatable project actions.](https://developers.openai.com/codex/app/features#integrated-terminal)[### In-app browser

65 68 

66Open unauthenticated local or public pages and comment on rendered output.](https://developers.openai.com/codex/app/browser)[### Image generation69Open rendered pages, leave comments, or let Codex operate local browser flows.](https://developers.openai.com/codex/app/browser)[### Image generation

67 70 

68Generate or edit images in a thread while you work on the surrounding code and assets.](https://developers.openai.com/codex/app/features#image-generation)[### Automations71Generate or edit images in a thread while you work on the surrounding code and assets.](https://developers.openai.com/codex/app/features#image-generation)[### Automations

69 72 

12Supported transports:12Supported transports:

13 13 

14- `stdio` (`--listen stdio://`, default): newline-delimited JSON (JSONL).14- `stdio` (`--listen stdio://`, default): newline-delimited JSON (JSONL).

15- `websocket` (`--listen ws://IP:PORT`, experimental): one JSON-RPC message per WebSocket text frame.15- `websocket` (`--listen ws://IP:PORT`, experimental and unsupported): one JSON-RPC message per WebSocket text frame.

16- `off` (`--listen off`): don't expose a local transport.

17 

18When you run with `--listen ws://IP:PORT`, the same listener also serves basic HTTP health probes:

19 

20- `GET /readyz` returns `200 OK` once the listener accepts new connections.

21- `GET /healthz` returns `200 OK` when the request doesn't include an `Origin` header.

22- Requests with an `Origin` header are rejected with `403 Forbidden`.

23 

24WebSocket transport is experimental and unsupported. Loopback listeners such as `ws://127.0.0.1:PORT` are appropriate for localhost and SSH port-forwarding workflows. Non-loopback WebSocket listeners currently allow unauthenticated connections by default during rollout, so configure WebSocket auth before exposing one remotely.

25 

26Supported WebSocket auth flags:

27 

28- `--ws-auth capability-token --ws-token-file /absolute/path`

29- `--ws-auth capability-token --ws-token-sha256 HEX`

30- `--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path`

31 

32For signed bearer tokens, you can also set `--ws-issuer`, `--ws-audience`, and `--ws-max-clock-skew-seconds`. Clients present the credential as `Authorization: Bearer <token>` during the WebSocket handshake, and app-server enforces auth before JSON-RPC `initialize`.

33 

34Prefer `--ws-token-file` over passing raw bearer tokens on the command line. Use `--ws-token-sha256` only when the client keeps the raw high-entropy token in a separate local secret store; the hash is only a verifier, and clients still need the original token.

16 35 

17In WebSocket mode, app-server uses bounded queues. When request ingress is full, the server rejects new requests with JSON-RPC error code `-32001` and message `"Server overloaded; retry later."` Clients should retry with an exponentially increasing delay and jitter.36In WebSocket mode, app-server uses bounded queues. When request ingress is full, the server rejects new requests with JSON-RPC error code `-32001` and message `"Server overloaded; retry later."` Clients should retry with an exponentially increasing delay and jitter.

18 37 

199- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.218- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.

200- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread.219- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread.

201- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.220- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.

202- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filters. Returned `thread` objects include runtime `status`.221- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, and `searchTerm` filters. Returned `thread` objects include runtime `status`.

222- `thread/turns/list` - page through a stored thread's turn history without resuming it.

203- `thread/loaded/list` - list the thread ids currently loaded in memory.223- `thread/loaded/list` - list the thread ids currently loaded in memory.

204- `thread/name/set` - set or update a thread's user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.224- `thread/name/set` - set or update a thread's user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.

225- `thread/goal/set` - set the goal for a loaded thread (experimental; requires `capabilities.experimentalApi`); emits `thread/goal/updated`.

226- `thread/goal/get` - read the current goal for a loaded thread (experimental; requires `capabilities.experimentalApi`).

227- `thread/goal/clear` - clear the goal for a loaded thread (experimental; requires `capabilities.experimentalApi`); emits `thread/goal/cleared`.

228- `thread/metadata/update` - patch SQLite-backed stored thread metadata; currently supports persisted `gitInfo`.

205- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.229- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.

206- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread and emits `thread/closed`.230- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread after a no-subscriber inactivity grace period and emits `thread/closed`.

207- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.231- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.

208- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.232- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.

209- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.233- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.

211- `thread/backgroundTerminals/clean` - stop all running background terminals for a thread (experimental; requires `capabilities.experimentalApi`).235- `thread/backgroundTerminals/clean` - stop all running background terminals for a thread (experimental; requires `capabilities.experimentalApi`).

212- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.236- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.

213- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."237- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."

238- `thread/inject_items` - append raw Responses API items to a loaded thread's model-visible history without starting a user turn.

214- `turn/steer` - append user input to the active in-flight turn for a thread; returns the accepted `turnId`.239- `turn/steer` - append user input to the active in-flight turn for a thread; returns the accepted `turnId`.

215- `turn/interrupt` - request cancellation of an in-flight turn; success is `{}` and the turn ends with `status: "interrupted"`.240- `turn/interrupt` - request cancellation of an in-flight turn; success is `{}` and the turn ends with `status: "interrupted"`.

216- `review/start` - kick off the Codex reviewer for a thread; emits `enteredReviewMode` and `exitedReviewMode` items.241- `review/start` - kick off the Codex reviewer for a thread; emits `enteredReviewMode` and `exitedReviewMode` items.

218- `command/exec/write` - write `stdin` bytes to a running `command/exec` session or close `stdin`.243- `command/exec/write` - write `stdin` bytes to a running `command/exec` session or close `stdin`.

219- `command/exec/resize` - resize a running PTY-backed `command/exec` session.244- `command/exec/resize` - resize a running PTY-backed `command/exec` session.

220- `command/exec/terminate` - stop a running `command/exec` session.245- `command/exec/terminate` - stop a running `command/exec` session.

246- `command/exec/outputDelta` (notify) - emitted for base64-encoded stdout/stderr chunks from a streaming `command/exec` session.

221- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.247- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.

248- `modelProvider/capabilities/read` - read provider capability bounds for model/provider combinations (experimental; requires `capabilities.experimentalApi`).

222- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.249- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.

250- `experimentalFeature/enablement/set` - patch in-memory runtime enablement for supported feature keys such as `apps` and `plugins`.

223- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).251- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).

224- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).252- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).

225- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace errors, featured plugin ids, and the development-only `forceRemoteSync` option.253- `skills/changed` (notify) - emitted when watched local skill files change.

226- `plugin/read` - read one plugin by marketplace path and plugin name, including bundled skills, apps, and MCP server names.254- `marketplace/add` - add a remote plugin marketplace and persist it into the user's marketplace config.

227- `plugin/install` - install a plugin from a marketplace path.255- `marketplace/upgrade` - refresh a configured Git marketplace, or all configured Git marketplaces when you omit the marketplace name.

256- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace load errors, featured plugin ids, and local, Git, or remote plugin source metadata.

257- `plugin/read` - read one plugin by marketplace path or remote marketplace name and plugin name, including bundled skills, apps, and MCP server names when those details are available.

258- `plugin/install` - install a plugin from a marketplace path or remote marketplace name.

228- `plugin/uninstall` - uninstall an installed plugin.259- `plugin/uninstall` - uninstall an installed plugin.

229- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.260- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.

230- `skills/config/write` - enable or disable skills by path.261- `skills/config/write` - enable or disable skills by path.

233- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.264- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.

234- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination). Use `detail: "full"` for full data or `detail: "toolsAndAuthOnly"` to omit resources.265- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination). Use `detail: "full"` for full data or `detail: "toolsAndAuthOnly"` to omit resources.

235- `mcpServer/resource/read` - read a single MCP resource through an initialized MCP server.266- `mcpServer/resource/read` - read a single MCP resource through an initialized MCP server.

267- `mcpServer/tool/call` - call a tool on a thread's configured MCP server.

268- `mcpServer/startupStatus/updated` (notify) - emitted when a configured MCP server's startup status changes for a loaded thread.

236- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.269- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.

237- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).270- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).

238- `config/read` - fetch the effective configuration on disk after resolving configuration layering.271- `config/read` - fetch the effective configuration on disk after resolving configuration layering.

239- `externalAgentConfig/detect` - detect external-agent artifacts that can be migrated with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).272- `externalAgentConfig/detect` - detect external-agent artifacts that can be migrated with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).

240- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home).273- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home). Supported item types include config, skills, `AGENTS.md`, plugins, MCP server config, subagents, hooks, commands, and sessions; plugin imports emit `externalAgentConfig/import/completed`.

241- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.274- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.

242- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.275- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.

243- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).276- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).

244- `fs/readFile`, `fs/writeFile`, `fs/createDirectory`, `fs/getMetadata`, `fs/readDirectory`, `fs/remove`, and `fs/copy` - operate on absolute filesystem paths through the app-server v2 filesystem API.277- `fs/readFile`, `fs/writeFile`, `fs/createDirectory`, `fs/getMetadata`, `fs/readDirectory`, `fs/remove`, `fs/copy`, `fs/watch`, `fs/unwatch`, and `fs/changed` (notify) - operate on absolute filesystem paths through the app-server v2 filesystem API.

278 

279Plugin summaries include a `source` union. Local plugins return

280`{ "type": "local", "path": ... }`, Git-backed marketplace entries return

281`{ "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }`,

282and remote catalog entries return `{ "type": "remote" }`. For remote-only

283catalog entries, `PluginMarketplaceEntry.path` can be `null`; pass

284`remoteMarketplaceName` instead of `marketplacePath` when reading or installing

285those plugins.

245 286 

246## Models287## Models

247 288 

310## Threads351## Threads

311 352 

312- `thread/read` reads a stored thread without subscribing to it; set `includeTurns` to include turns.353- `thread/read` reads a stored thread without subscribing to it; set `includeTurns` to include turns.

313- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filtering.354- `thread/turns/list` pages through a stored thread's turn history without resuming it.

355- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, and `searchTerm` filtering.

314- `thread/loaded/list` returns the thread IDs currently in memory.356- `thread/loaded/list` returns the thread IDs currently in memory.

315- `thread/archive` moves the thread's persisted JSONL log into the archived directory.357- `thread/archive` moves the thread's persisted JSONL log into the archived directory.

316- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed`.358- `thread/metadata/update` patches stored thread metadata, currently including persisted `gitInfo`.

359- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed` after an inactivity grace period.

317- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.360- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.

318- `thread/compact/start` triggers compaction and returns `{}` immediately.361- `thread/compact/start` triggers compaction and returns `{}` immediately.

319- `thread/rollback` drops the last N turns from the in-memory context and records a rollback marker in the thread's persisted JSONL log.362- `thread/rollback` drops the last N turns from the in-memory context and records a rollback marker in the thread's persisted JSONL log.

363- `thread/inject_items` appends raw Responses API items to a loaded thread's model-visible history without starting a user turn.

320 364 

321### Start or resume a thread365### Start or resume a thread

322 366 

387 431 

388Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.432Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.

389 433 

434### List thread turns

435 

436Use `thread/turns/list` to page a stored thread's turn history without resuming it. Results default to newest-first so clients can fetch older turns with `nextCursor`. The response also includes `backwardsCursor`; pass it as `cursor` with `sortDirection: "asc"` to fetch turns newer than the first item from the earlier page.

437 

438```json

439{ "method": "thread/turns/list", "id": 20, "params": {

440 "threadId": "thr_123",

441 "limit": 50,

442 "sortDirection": "desc"

443} }

444{ "id": 20, "result": {

445 "data": [],

446 "nextCursor": "older-turns-cursor-or-null",

447 "backwardsCursor": "newer-turns-cursor-or-null"

448} }

449```

450 

390### List threads (with pagination & filters)451### List threads (with pagination & filters)

391 452 

392`thread/list` lets you render a history UI. Results default to newest-first by `createdAt`. Filters apply before pagination. Pass any combination of:453`thread/list` lets you render a history UI. Results default to newest-first by `createdAt`. Filters apply before pagination. Pass any combination of:

398- `sourceKinds` - restrict results to specific thread sources. When omitted or `[]`, the server defaults to interactive sources only: `cli` and `vscode`.459- `sourceKinds` - restrict results to specific thread sources. When omitted or `[]`, the server defaults to interactive sources only: `cli` and `vscode`.

399- `archived` - when `true`, list archived threads only. When `false` or omitted, list non-archived threads (default).460- `archived` - when `true`, list archived threads only. When `false` or omitted, list non-archived threads (default).

400- `cwd` - restrict results to threads whose session current working directory exactly matches this path.461- `cwd` - restrict results to threads whose session current working directory exactly matches this path.

462- `searchTerm` - search stored thread summaries and metadata before pagination.

401 463 

402`sourceKinds` accepts the following values:464`sourceKinds` accepts the following values:

403 465 

431 493 

432When `nextCursor` is `null`, you have reached the final page.494When `nextCursor` is `null`, you have reached the final page.

433 495 

496### Update stored thread metadata

497 

498Use `thread/metadata/update` to patch stored thread metadata without resuming the thread. Today this supports persisted `gitInfo`; omitted fields are left unchanged, and explicit `null` clears a stored value.

499 

500```json

501{ "method": "thread/metadata/update", "id": 21, "params": {

502 "threadId": "thr_123",

503 "gitInfo": { "branch": "feature/sidebar-pr" }

504} }

505{ "id": 21, "result": {

506 "thread": {

507 "id": "thr_123",

508 "gitInfo": { "sha": null, "branch": "feature/sidebar-pr", "originUrl": null }

509 }

510} }

511```

512 

434### Track thread status changes513### Track thread status changes

435 514 

436`thread/status/changed` is emitted whenever a loaded thread's runtime status changes. The payload includes `threadId` and the new `status`.515`thread/status/changed` is emitted whenever a loaded thread's runtime status changes. The payload includes `threadId` and the new `status`.

462- `notSubscribed` when the connection wasn't subscribed to that thread.541- `notSubscribed` when the connection wasn't subscribed to that thread.

463- `notLoaded` when the thread isn't loaded.542- `notLoaded` when the thread isn't loaded.

464 543 

465If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.544If this was the last subscriber, the server keeps the thread loaded until it has no subscribers and no thread activity for 30 minutes. When the grace period expires, app-server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.

466 545 

467```json546```json

468{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }547{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }

469{ "id": 22, "result": { "status": "unsubscribed" } }548{ "id": 22, "result": { "status": "unsubscribed" } }

549```

550 

551If the thread later expires:

552 

553```json

470{ "method": "thread/status/changed", "params": {554{ "method": "thread/status/changed", "params": {

471 "threadId": "thr_123",555 "threadId": "thr_123",

472 "status": { "type": "notLoaded" }556 "status": { "type": "notLoaded" }

615{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }699{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }

616```700```

617 701 

702### Inject items into a thread

703 

704Use `thread/inject_items` to append prebuilt Responses API items to a loaded thread's prompt history without starting a user turn. These items are persisted to the rollout and included in subsequent model requests.

705 

706```json

707{ "method": "thread/inject_items", "id": 31, "params": {

708 "threadId": "thr_123",

709 "items": [

710 {

711 "type": "message",

712 "role": "assistant",

713 "content": [{ "type": "output_text", "text": "Previously computed context." }]

714 }

715 ]

716} }

717{ "id": 31, "result": {} }

718```

719 

618### Steer an active turn720### Steer an active turn

619 721 

620Use `turn/steer` to append more user input to the active in-flight turn.722Use `turn/steer` to append more user input to the active in-flight turn.

796- `elevated` - run the elevated Windows sandbox setup path.898- `elevated` - run the elevated Windows sandbox setup path.

797- `unelevated` - run the legacy setup/preflight path.899- `unelevated` - run the legacy setup/preflight path.

798 900 

901## Filesystem

902 

903The v2 filesystem APIs operate on absolute paths. Use `fs/watch` when a client needs to invalidate UI state after a file or directory changes.

904 

905```json

906{ "method": "fs/watch", "id": 54, "params": {

907 "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",

908 "path": "/Users/me/project/.git/HEAD"

909} }

910{ "id": 54, "result": { "path": "/Users/me/project/.git/HEAD" } }

911{ "method": "fs/changed", "params": {

912 "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",

913 "changedPaths": ["/Users/me/project/.git/HEAD"]

914} }

915{ "method": "fs/unwatch", "id": 55, "params": {

916 "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1"

917} }

918{ "id": 55, "result": {} }

919```

920 

921Watching a file emits `fs/changed` for that file path, including updates delivered by replace or rename operations.

922 

799## Events923## Events

800 924 

801Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `thread/archived`, `thread/unarchived`, `thread/closed`, `thread/status/changed`, `turn/*`, `item/*`, and `serverRequest/resolved` notifications.925Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `thread/archived`, `thread/unarchived`, `thread/closed`, `thread/status/changed`, `turn/*`, `item/*`, and `serverRequest/resolved` notifications.

1016} }1140} }

1017```1141```

1018 1142 

1143The server also emits `skills/changed` notifications when watched local skill files change. Treat this as an invalidation signal and rerun `skills/list` with your current params when needed.

1144 

1019To enable or disable a skill by path:1145To enable or disable a skill by path:

1020 1146 

1021```json1147```json

1222{ "id": 64, "result": {} }1348{ "id": 64, "result": {} }

1223```1349```

1224 1350 

1225Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, and `MCP_SERVER_CONFIG`. Detection returns only items that still have work to do. For example, AGENTS migration is skipped when `AGENTS.md` already exists and is non-empty, and skill imports don’t overwrite existing skill directories.1351When a request includes plugin imports, the server emits `externalAgentConfig/import/completed` after the import finishes. This notification may arrive immediately after the response or after background remote imports complete.

1352 

1353Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, `PLUGINS`,

1354and `MCP_SERVER_CONFIG`. For `PLUGINS` items, `details.plugins` lists each

1355`marketplaceName` and the `pluginNames` Codex can try to migrate. Detection

1356returns only items that still have work to do. For example, Codex skips AGENTS

1357migration when `AGENTS.md` already exists and is non-empty, and skill imports

1358don't overwrite existing skill directories.

1359 

1360When detecting plugins from `.claude/settings.json`, Codex reads configured

1361marketplace sources from `extraKnownMarketplaces`. If `enabledPlugins` contains

1362plugins from `claude-plugins-official` but the marketplace source is missing,

1363Codex infers `anthropics/claude-plugins-official` as the source.

1226 1364 

1227## Auth endpoints1365## Auth endpoints

1228 1366 

1229The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.1367The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, inspect ChatGPT rate limits, and notify workspace owners about depleted credits or usage limits.

1230 1368 

1231### Authentication modes1369### Authentication modes

1232 1370 

1233Codex supports three authentication modes. `account/updated.authMode` shows the active mode, and `account/read` also reports it.1371Codex supports these authentication modes. `account/updated.authMode` shows the active mode and includes the current ChatGPT `planType` when available. `account/read` also reports account and plan details.

1234 1372 

1235- **API key (`apikey`)** - the caller supplies an OpenAI API key and Codex stores it for API requests.1373- **API key (`apikey`)** - the caller supplies an OpenAI API key with `type: "apiKey"`, and Codex stores it for API requests.

1236- **ChatGPT managed (`chatgpt`)** - Codex owns the ChatGPT OAuth flow, persists tokens, and refreshes them automatically.1374- **ChatGPT managed (`chatgpt`)** - Codex owns the ChatGPT OAuth flow, persists tokens, and refreshes them automatically. Start with `type: "chatgpt"` for the browser flow or `type: "chatgptDeviceCode"` for the device-code flow.

1237- **ChatGPT external tokens (`chatgptAuthTokens`)** - a host app supplies `idToken` and `accessToken` directly. Codex stores these tokens in memory, and the host app must refresh them when asked.1375- **ChatGPT external tokens (`chatgptAuthTokens`)** - experimental and intended for host apps that already own the user's ChatGPT auth lifecycle. The host app supplies an `accessToken`, `chatgptAccountId`, and optional `chatgptPlanType` directly, and must refresh the token when asked.

1238 1376 

1239### API overview1377### API overview

1240 1378 

1241- `account/read` - fetch current account info; optionally refresh tokens.1379- `account/read` - fetch current account info; optionally refresh tokens.

1242- `account/login/start` - begin login (`apiKey`, `chatgpt`, or `chatgptAuthTokens`).1380- `account/login/start` - begin login (`apiKey`, `chatgpt`, `chatgptDeviceCode`, or experimental `chatgptAuthTokens`).

1243- `account/login/completed` (notify) - emitted when a login attempt finishes (success or error).1381- `account/login/completed` (notify) - emitted when a login attempt finishes (success or error).

1244- `account/login/cancel` - cancel a pending ChatGPT login by `loginId`.1382- `account/login/cancel` - cancel a pending managed ChatGPT login by `loginId`.

1245- `account/logout` - sign out; triggers `account/updated`.1383- `account/logout` - sign out; triggers `account/updated`.

1246- `account/updated` (notify) - emitted whenever auth mode changes (`authMode`: `apikey`, `chatgpt`, `chatgptAuthTokens`, or `null`).1384- `account/updated` (notify) - emitted whenever auth mode changes (`authMode`: `apikey`, `chatgpt`, `chatgptAuthTokens`, or `null`) and includes `planType` when available.

1247- `account/chatgptAuthTokens/refresh` (server request) - request fresh externally managed ChatGPT tokens after an authorization error.1385- `account/chatgptAuthTokens/refresh` (server request) - request fresh externally managed ChatGPT tokens after an authorization error.

1248- `account/rateLimits/read` - fetch ChatGPT rate limits.1386- `account/rateLimits/read` - fetch ChatGPT rate limits.

1249- `account/rateLimits/updated` (notify) - emitted whenever a user's ChatGPT rate limits change.1387- `account/rateLimits/updated` (notify) - emitted whenever a user's ChatGPT rate limits change.

1388- `account/sendAddCreditsNudgeEmail` - ask ChatGPT to email a workspace owner about depleted credits or a reached usage limit.

1250- `mcpServer/oauthLogin/completed` (notify) - emitted after a `mcpServer/oauth/login` flow finishes; payload includes `{ name, success, error? }`.1389- `mcpServer/oauthLogin/completed` (notify) - emitted after a `mcpServer/oauth/login` flow finishes; payload includes `{ name, success, error? }`.

1390- `mcpServer/startupStatus/updated` (notify) - emitted when a configured MCP server's startup status changes for a loaded thread; payload includes `{ name, status, error }`.

1251 1391 

1252### 1) Check auth state1392### 1) Check auth state

1253 1393 

1319 ```1459 ```

1320 1460 

1321 ```json1461 ```json

1322 { "method": "account/updated", "params": { "authMode": "apikey" } }1462 {

1463 "method": "account/updated",

1464 "params": { "authMode": "apikey", "planType": null }

1465 }

1323 ```1466 ```

1324 1467 

1325### 3) Log in with ChatGPT (browser flow)1468### 3) Log in with ChatGPT (browser flow)

1351 ```1494 ```

1352 1495 

1353 ```json1496 ```json

1354 { "method": "account/updated", "params": { "authMode": "chatgpt" } }1497 {

1498 "method": "account/updated",

1499 "params": { "authMode": "chatgpt", "planType": "plus" }

1500 }

1501 ```

1502 

1503### 3b) Log in with ChatGPT (device-code flow)

1504 

1505Use this flow when your client owns the sign-in ceremony or when a browser callback is brittle.

1506 

15071. Start:

1508 

1509 ```json

1510 {

1511 "method": "account/login/start",

1512 "id": 4,

1513 "params": { "type": "chatgptDeviceCode" }

1514 }

1515 ```

1516 

1517 ```json

1518 {

1519 "id": 4,

1520 "result": {

1521 "type": "chatgptDeviceCode",

1522 "loginId": "<uuid>",

1523 "verificationUrl": "https://auth.openai.com/codex/device",

1524 "userCode": "ABCD-1234"

1525 }

1526 }

1527 ```

15282. Show `verificationUrl` and `userCode` to the user; the frontend owns the UX.

15293. Wait for notifications:

1530 

1531 ```json

1532 {

1533 "method": "account/login/completed",

1534 "params": { "loginId": "<uuid>", "success": true, "error": null }

1535 }

1536 ```

1537 

1538 ```json

1539 {

1540 "method": "account/updated",

1541 "params": { "authMode": "chatgpt", "planType": "plus" }

1542 }

1355 ```1543 ```

1356 1544 

1357### 3b) Log in with externally managed ChatGPT tokens (`chatgptAuthTokens`)1545### 3c) Log in with externally managed ChatGPT tokens (`chatgptAuthTokens`)

1358 1546 

1359Use this mode when a host application owns the user’s ChatGPT auth lifecycle and supplies tokens directly.1547Use this experimental mode only when a host application owns the user's ChatGPT auth lifecycle and supplies tokens directly. Clients must set `capabilities.experimentalApi = true` during `initialize` before using this login type.

1360 1548 

13611. Send:15491. Send:

1362 1550 

1366 "id": 7,1554 "id": 7,

1367 "params": {1555 "params": {

1368 "type": "chatgptAuthTokens",1556 "type": "chatgptAuthTokens",

1369 "idToken": "<jwt>",1557 "accessToken": "<jwt>",

1370 "accessToken": "<jwt>"1558 "chatgptAccountId": "org-123",

1559 "chatgptPlanType": "business"

1371 }1560 }

1372 }1561 }

1373 ```1562 ```

1388 ```json1577 ```json

1389 {1578 {

1390 "method": "account/updated",1579 "method": "account/updated",

1391 "params": { "authMode": "chatgptAuthTokens" }1580 "params": { "authMode": "chatgptAuthTokens", "planType": "business" }

1392 }1581 }

1393 ```1582 ```

1394 1583 

1400 "id": 8,1589 "id": 8,

1401 "params": { "reason": "unauthorized", "previousAccountId": "org-123" }1590 "params": { "reason": "unauthorized", "previousAccountId": "org-123" }

1402}1591}

1403{ "id": 8, "result": { "idToken": "<jwt>", "accessToken": "<jwt>" } }1592{ "id": 8, "result": { "accessToken": "<jwt>", "chatgptAccountId": "org-123", "chatgptPlanType": "business" } }

1404```1593```

1405 1594 

1406The server retries the original request after a successful refresh response. Requests time out after about 10 seconds.1595The server retries the original request after a successful refresh response. Requests time out after about 10 seconds.

1417```json1606```json

1418{ "method": "account/logout", "id": 5 }1607{ "method": "account/logout", "id": 5 }

1419{ "id": 5, "result": {} }1608{ "id": 5, "result": {} }

1420{ "method": "account/updated", "params": { "authMode": null } }1609{ "method": "account/updated", "params": { "authMode": null, "planType": null } }

1421```1610```

1422 1611 

1423### 6) Rate limits (ChatGPT)1612### 6) Rate limits (ChatGPT)

1429 "limitId": "codex",1618 "limitId": "codex",

1430 "limitName": null,1619 "limitName": null,

1431 "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },1620 "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },

1432 "secondary": null1621 "secondary": null,

1622 "rateLimitReachedType": null

1433 },1623 },

1434 "rateLimitsByLimitId": {1624 "rateLimitsByLimitId": {

1435 "codex": {1625 "codex": {

1436 "limitId": "codex",1626 "limitId": "codex",

1437 "limitName": null,1627 "limitName": null,

1438 "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },1628 "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },

1439 "secondary": null1629 "secondary": null,

1630 "rateLimitReachedType": null

1440 },1631 },

1441 "codex_other": {1632 "codex_other": {

1442 "limitId": "codex_other",1633 "limitId": "codex_other",

1443 "limitName": "codex_other",1634 "limitName": "codex_other",

1444 "primary": { "usedPercent": 42, "windowDurationMins": 60, "resetsAt": 1730950800 },1635 "primary": { "usedPercent": 42, "windowDurationMins": 60, "resetsAt": 1730950800 },

1445 "secondary": null1636 "secondary": null,

1637 "rateLimitReachedType": null

1446 }1638 }

1447 }1639 }

1448} }1640} }

1463- `usedPercent` is current usage within the quota window.1655- `usedPercent` is current usage within the quota window.

1464- `windowDurationMins` is the quota window length.1656- `windowDurationMins` is the quota window length.

1465- `resetsAt` is a Unix timestamp (seconds) for the next reset.1657- `resetsAt` is a Unix timestamp (seconds) for the next reset.

1658- `planType` is included when the backend returns the ChatGPT plan associated with a bucket.

1659- `credits` is included when the backend returns remaining workspace credit details.

1660- `rateLimitReachedType` identifies the backend-classified limit state when one has been reached.

1661 

1662### 7) Notify a workspace owner about a limit

1663 

1664Use `account/sendAddCreditsNudgeEmail` to ask ChatGPT to email a workspace owner when credits are depleted or a usage limit has been reached.

1665 

1666```json

1667{ "method": "account/sendAddCreditsNudgeEmail", "id": 7, "params": { "creditType": "credits" } }

1668{ "id": 7, "result": { "status": "sent" } }

1669```

1670 

1671Use `creditType: "credits"` when workspace credits are depleted, or `creditType: "usage_limit"` when the workspace usage limit has been reached. If the owner was already notified recently, the response status is `cooldown_active`.

20 20 

21![Codex app showing a browser comment on a local web app preview](/images/codex/app/in-app-browser-light.webp)21![Codex app showing a browser comment on a local web app preview](/images/codex/app/in-app-browser-light.webp)

22 22 

23## Browser use

24 

25Browser use lets Codex operate the in-app browser directly. Use it for local

26development servers and file-backed previews when Codex needs to click, type,

27inspect rendered state, take screenshots, or verify a fix in the page.

28 

29To use it, install and enable the Browser plugin. Then ask Codex to use the

30browser in your task, or reference it directly with `@Browser`. The app keeps

31browser use inside the in-app browser and lets you manage allowed and blocked

32websites from settings.

33 

34Example:

35 

36```text

37Use the browser to open http://localhost:3000/settings, reproduce the layout

38bug, and fix only the overflowing controls.

39```

40 

41Codex asks before using a website unless you've allowed it. Removing a site from

42the allowed list means Codex asks again before using it; removing a site from the

43blocked list means Codex can ask again instead of treating it as blocked.

44 

23## Preview a page45## Preview a page

24 46 

251. Start your app's development server in the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or with a [local environment action](https://developers.openai.com/codex/app/local-environments#actions).471. Start your app's development server in the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or with a [local environment action](https://developers.openai.com/codex/app/local-environments#actions).

3The Codex app is a focused desktop experience for working on Codex threads in parallel,3The Codex app is a focused desktop experience for working on Codex threads in parallel,

4with built-in worktree support, automations, and Git functionality.4with built-in worktree support, automations, and Git functionality.

5 5 

6Most Codex app features are available on both macOS and Windows.

7The sections below note platform-specific exceptions.

8 

6---9---

7 10 

8## Multitask across projects11## Multitask across projects

143Use browser comments to mark specific elements or areas on a page, then ask146Use browser comments to mark specific elements or areas on a page, then ask

144Codex to address that feedback.147Codex to address that feedback.

145 148 

149When you want Codex to operate the page directly, use

150[browser use](https://developers.openai.com/codex/app/browser#browser-use) for local development servers and

151file-backed pages. You can manage the Browser plugin, allowed websites, and

152blocked websites from settings.

153 

146![Codex app showing a browser comment on a local web app preview](/images/codex/app/in-app-browser-light.webp)154![Codex app showing a browser comment on a local web app preview](/images/codex/app/in-app-browser-light.webp)

147 155 

148## Computer use156## Computer use

222opening separate projects or using worktrees rather than asking Codex to roam230opening separate projects or using worktrees rather than asking Codex to roam

223outside the project root.231outside the project root.

224 232 

233If [automatic review](https://developers.openai.com/codex/agent-approvals-security#automatic-approval-reviews)

234is available in your workspace, you can choose it from the permissions selector.

235It keeps the same sandbox boundary but routes eligible approval requests through

236the configured review policy instead of waiting for you.

237 

225For a high-level overview, see [sandboxing](https://developers.openai.com/codex/concepts/sandboxing). For238For a high-level overview, see [sandboxing](https://developers.openai.com/codex/concepts/sandboxing). For

226configuration details, see the239configuration details, see the

227[agent approvals & security documentation](https://developers.openai.com/codex/agent-approvals-security).240[agent approvals & security documentation](https://developers.openai.com/codex/agent-approvals-security).

247 260 

248You can ask in natural language or explicitly invoke the image generation skill by including `$imagegen` in your prompt.261You can ask in natural language or explicitly invoke the image generation skill by including `$imagegen` in your prompt.

249 262 

250Built-in image generation uses `gpt-image-1.5`, counts toward your general Codex usage limits, and uses included limits 3-5x faster on average than similar turns without image generation, depending on image quality and size. For details, see [Pricing](https://developers.openai.com/codex/pricing#image-generation-usage-limits). For prompting tips and model details, see the [image generation guide](https://developers.openai.com/api/docs/guides/image-generation).263Built-in image generation uses `gpt-image-2`, counts toward your general Codex usage limits, and uses included limits 3-5x faster on average than similar turns without image generation, depending on image quality and size. For details, see [Pricing](https://developers.openai.com/codex/pricing#image-generation-usage-limits). For prompting tips and model details, see the [image generation guide](https://developers.openai.com/api/docs/guides/image-generation).

251 264 

252For larger batches of image generation, set `OPENAI_API_KEY` in your environment variables and ask Codex to generate images through the API so API pricing applies instead.265For larger batches of image generation, set `OPENAI_API_KEY` in your environment variables and ask Codex to generate images through the API so API pricing applies instead.

253 266 

30 30 

31![Codex app Appearance settings showing theme selection, color controls, and font options](/images/codex/app/theme-selection-light.webp)31![Codex app Appearance settings showing theme selection, color controls, and font options](/images/codex/app/theme-selection-light.webp)

32 32 

33### Codex pets

34 

35 Codex pets are optional animated companions for the app. In **Settings**,

36choose **Pets** to select a built-in pet or refresh custom pets from your

37local Codex home. Type `/pet` in the composer, use **Wake Pet** or **Tuck Away Pet** in Settings, or

38 press <kbd>Cmd+K</kbd> or <kbd>Ctrl+K</kbd> and run the same commands to

39 toggle the floating overlay.

40 

41 The overlay keeps active Codex work visible while you use other apps. It

42 shows the active thread, reflects whether Codex is running, waiting for

43 input, or ready for review, and pairs that state with a short progress

44 prompt so you can glance at what changed without reopening the thread.

45 

461/8

47 

48CodexI found a tiny loose thread in settings. Want me to tug it?

49 

50To create your own pet, install the `hatch-pet` skill:

51 

52```text

53$skill-installer hatch-pet

54```

55 

56Reload skills from the command menu. Press <kbd>Cmd+K</kbd> or <kbd>Ctrl+K</kbd>,

57choose **Force Reload Skills**, then ask the skill to create a pet:

58 

59```text

60$hatch-pet create a new pet inspired by my recent projects

61```

62 

33## Git63## Git

34 64 

35Use Git settings to standardize branch naming and choose whether Codex uses force65Use Git settings to standardize branch naming and choose whether Codex uses force

43also apply to the Codex CLI and IDE extension because the MCP configuration lives in73also apply to the Codex CLI and IDE extension because the MCP configuration lives in

44`config.toml`. See the [Model Context Protocol docs](https://developers.openai.com/codex/mcp) for details.74`config.toml`. See the [Model Context Protocol docs](https://developers.openai.com/codex/mcp) for details.

45 75 

76## Browser use

77 

78Use these settings to install or enable the bundled Browser plugin and manage

79allowed and blocked websites. Codex asks before using a website unless you've

80allowed it. Removing a site from the blocked list lets Codex ask

81again before using it in the browser.

82 

83See [In-app browser](https://developers.openai.com/codex/app/browser) for browser preview, comment, and

84browser use workflows.

85 

46## Computer Use86## Computer Use

47 87 

48On macOS, check your Computer Use settings to review desktop-app access and related88On macOS, check your Computer Use settings to review desktop-app access and related

49preferences after setup. To revoke system-level access, update Screen Recording89preferences after setup. To revoke system-level access, update Screen Recording

50or Accessibility permissions in macOS Privacy & Security settings. The feature90or Accessibility permissions in macOS Privacy & Security settings. The feature

51isn’t available in the European Economic Area, the United Kingdom, or Switzerland91isn't available in the EEA, the United Kingdom, or Switzerland at launch.

52at launch.

53 92 

54## Personalization93## Personalization

55 94 

2 2 

3The [Codex app for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi) gives you one interface for3The [Codex app for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi) gives you one interface for

4working across projects, running parallel agent threads, and reviewing results.4working across projects, running parallel agent threads, and reviewing results.

5The Windows app supports core workflows such as worktrees, automations, Git

6functionality, the in-app browser, artifact previews, plugins, and skills.

5It runs natively on Windows using PowerShell and the7It runs natively on Windows using PowerShell and the

6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to8[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to

7run in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl).9run in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl).

43 43 

44 npm i -g @openai/codex@latestCopy44 npm i -g @openai/codex@latestCopy

45 45 

46The Codex CLI is available on macOS and Linux. Windows support is46The Codex CLI is available on macOS, Windows, and Linux. On Windows, run Codex

47experimental. For the best Windows experience, use Codex in a WSL2 workspace47 natively in PowerShell with the Windows sandbox, or use WSL2 when you need a

48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).48Linux-native environment. For setup details, see the

49[Windows setup guide](https://developers.openai.com/codex/windows).

49 50 

50If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).51If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

51 52 

22- Watch Codex explain its plan before making a change, and approve or reject steps inline.22- Watch Codex explain its plan before making a change, and approve or reject steps inline.

23- Read syntax-highlighted markdown code blocks and diffs in the TUI, then use `/theme` to preview and save a preferred theme.23- Read syntax-highlighted markdown code blocks and diffs in the TUI, then use `/theme` to preview and save a preferred theme.

24- Use `/clear` to wipe the terminal and start a fresh chat, or press <kbd>Ctrl</kbd>+<kbd>L</kbd> to clear the screen without starting a new conversation.24- Use `/clear` to wipe the terminal and start a fresh chat, or press <kbd>Ctrl</kbd>+<kbd>L</kbd> to clear the screen without starting a new conversation.

25- Use `/copy` to copy the latest completed Codex output. If a turn is still running, Codex copies the most recent finished output instead of in-progress text.25- Use `/copy` or press <kbd>Ctrl</kbd>+<kbd>O</kbd> to copy the latest completed Codex output. If a turn is still running, Codex copies the most recent finished output instead of in-progress text.

26- Press <kbd>Tab</kbd> while Codex is running to queue follow-up text, slash commands, or `!` shell commands for the next turn.

26- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.27- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.

28- Press <kbd>Ctrl</kbd>+<kbd>R</kbd> to search prompt history from the composer, then press <kbd>Enter</kbd> to accept a match or <kbd>Esc</kbd> to cancel.

27- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.29- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.

28 30 

29## Resuming conversations31## Resuming conversations

105 107 

106## Models and reasoning108## Models and reasoning

107 109 

108For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the110For most tasks in Codex, `gpt-5.5` is the recommended model when it is

109industry-leading coding capabilities of `gpt-5.3-codex` to OpenAI’s flagship111available. It is OpenAI's newest frontier model for complex coding, computer

110frontier model, combining frontier coding performance with stronger reasoning,112use, knowledge work, and research workflows, with stronger planning, tool use,

111native computer use, and broader professional workflows. For extra fast tasks,113and follow-through on multi-step tasks. If `gpt-5.5` is not yet available,

112ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in114continue using `gpt-5.4`. For extra fast tasks, ChatGPT Pro subscribers have

113research preview.115access to the GPT-5.3-Codex-Spark model in research preview.

114 116 

115Switch models mid-session with the `/model` command, or specify one when launching the CLI.117Switch models mid-session with the `/model` command, or specify one when launching the CLI.

116 118 

117```bash119```bash

118codex --model gpt-5.4120codex --model gpt-5.5

119```121```

120 122 

121[Learn more about the models available in Codex](https://developers.openai.com/codex/models).123[Learn more about the models available in Codex](https://developers.openai.com/codex/models).

160 162 

161You can ask in natural language or explicitly invoke the image generation skill by including `$imagegen` in your prompt.163You can ask in natural language or explicitly invoke the image generation skill by including `$imagegen` in your prompt.

162 164 

163Built-in image generation uses `gpt-image-1.5`, counts toward your general Codex usage limits, and uses included limits 3-5x faster on average than similar turns without image generation, depending on image quality and size. For details, see [Pricing](https://developers.openai.com/codex/pricing#image-generation-usage-limits). For prompting tips and model details, see the [image generation guide](https://developers.openai.com/api/docs/guides/image-generation).165Built-in image generation uses `gpt-image-2`, counts toward your general Codex usage limits, and uses included limits 3-5x faster on average than similar turns without image generation, depending on image quality and size. For details, see [Pricing](https://developers.openai.com/codex/pricing#image-generation-usage-limits). For prompting tips and model details, see the [image generation guide](https://developers.openai.com/api/docs/guides/image-generation).

164 166 

165For larger batches of image generation, set `OPENAI_API_KEY` in your environment variables and ask Codex to generate images through the API so API pricing applies instead.167For larger batches of image generation, set `OPENAI_API_KEY` in your environment variables and ask Codex to generate images through the API so API pricing applies instead.

166 168 

252 254 

253## Slash commands255## Slash commands

254 256 

255Slash commands give you quick access to specialized workflows like `/review`, `/fork`, or your own reusable prompts. Codex ships with a curated set of built-ins, and you can create custom ones for team-specific tasks or personal shortcuts.257Slash commands give you quick access to specialized workflows like `/review`, `/fork`, `/side`, or your own reusable prompts. Codex ships with a curated set of built-ins, and you can create custom ones for team-specific tasks or personal shortcuts.

256 258 

257See the [slash commands guide](https://developers.openai.com/codex/guides/slash-commands) to browse the catalog of built-ins, learn how to author custom commands, and understand where they live on disk.259See the [slash commands guide](https://developers.openai.com/codex/guides/slash-commands) to browse the catalog of built-ins, learn how to author custom commands, and understand where they live on disk.

258 260 

271## Tips and shortcuts273## Tips and shortcuts

272 274 

273- Type `@` in the composer to open a fuzzy file search over the workspace root; press <kbd>Tab</kbd> or <kbd>Enter</kbd> to drop the highlighted path into your message.275- Type `@` in the composer to open a fuzzy file search over the workspace root; press <kbd>Tab</kbd> or <kbd>Enter</kbd> to drop the highlighted path into your message.

274- Press `Enter` while Codex is running to inject new instructions into the current turn, or press `Tab` to queue a follow-up prompt for the next turn.276- Press <kbd>Enter</kbd> while Codex is running to inject new instructions into the current turn, or press <kbd>Tab</kbd> to queue follow-up input for the next turn. Queued input can be a normal prompt, a slash command such as `/review`, or a `!` shell command. Codex parses queued slash commands when they run.

275- Prefix a line with `!` to run a local shell command (for example, `!ls`). Codex treats the output like a user-provided command result and still applies your approval and sandbox settings.277- Prefix a line with `!` to run a local shell command (for example, `!ls`). Codex treats the output like a user-provided command result and still applies your approval and sandbox settings.

276- Tap <kbd>Esc</kbd> twice while the composer is empty to edit your previous user message. Continue pressing <kbd>Esc</kbd> to walk further back in the transcript, then hit <kbd>Enter</kbd> to fork from that point.278- Tap <kbd>Esc</kbd> twice while the composer is empty to edit your previous user message. Continue pressing <kbd>Esc</kbd> to walk further back in the transcript, then hit <kbd>Enter</kbd> to fork from that point.

277- Launch Codex from any directory using `codex --cd <path>` to set the working root without running `cd` first. The active path appears in the TUI header.279- Launch Codex from any directory using `codex --cd <path>` to set the working root without running `cd` first. The active path appears in the TUI header.

20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |

21| `--disable` | `feature` | Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable. |21| `--disable` | `feature` | Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable. |

22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |

23| `--full-auto` | `boolean` | Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`. |

24| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |23| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |

25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |24| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |

26| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |25| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |

118 117 

119Key118Key

120 119 

121`--full-auto`

122 

123Type / Values

124 

125`boolean`

126 

127Details

128 

129Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`.

130 

131Key

132 

133`--image, -i`120`--image, -i`

134 121 

135Type / Values122Type / Values

262| Key | Maturity | Details |249| Key | Maturity | Details |

263| --- | --- | --- |250| --- | --- | --- |

264| [`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive) | Stable | Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments. |251| [`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive) | Stable | Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments. |

265| [`codex app`](https://developers.openai.com/codex/cli/reference#codex-app) | Stable | Launch the Codex desktop app on macOS, optionally opening a specific workspace path. |252| [`codex app`](https://developers.openai.com/codex/cli/reference#codex-app) | Stable | Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open. |

266| [`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server) | Experimental | Launch the Codex app server for local development or debugging. |253| [`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server) | Experimental | Launch the Codex app server for local development or debugging. |

267| [`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply) | Stable | Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`. |254| [`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply) | Stable | Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`. |

268| [`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud) | Experimental | Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`. |255| [`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud) | Experimental | Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`. |

269| [`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion) | Stable | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. |256| [`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion) | Stable | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. |

270| [`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2) | Experimental | Debug app-server by sending a single V2 message through the built-in test client. |257| [`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2) | Experimental | Debug app-server by sending a single V2 message through the built-in test client. |

258| [`codex debug models`](https://developers.openai.com/codex/cli/reference#codex-debug-models) | Experimental | Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog. |

271| [`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec) | Stable | Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions. |259| [`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec) | Stable | Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions. |

272| [`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy) | Experimental | Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked. |260| [`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy) | Experimental | Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked. |

273| [`codex features`](https://developers.openai.com/codex/cli/reference#codex-features) | Stable | List feature flags and persistently enable or disable them in `config.toml`. |261| [`codex features`](https://developers.openai.com/codex/cli/reference#codex-features) | Stable | List feature flags and persistently enable or disable them in `config.toml`. |

276| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |264| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |

277| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |265| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |

278| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |266| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |

267| [`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace) | Experimental | Add, upgrade, or remove plugin marketplaces from Git or local sources. |

279| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |268| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |

280| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes. |269| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes. |

270| [`codex update`](https://developers.openai.com/codex/cli/reference#codex-update) | Stable | Check for and apply a Codex CLI update when the installed release supports self-update. |

281 271 

282Key272Key

283 273 

301 291 

302Details292Details

303 293 

304Launch the Codex desktop app on macOS, optionally opening a specific workspace path.294Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.

305 295 

306Key296Key

307 297 

365 355 

366Key356Key

367 357 

358[`codex debug models`](https://developers.openai.com/codex/cli/reference#codex-debug-models)

359 

360Maturity

361 

362Experimental

363 

364Details

365 

366Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog.

367 

368Key

369 

368[`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec)370[`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec)

369 371 

370Maturity372Maturity

461 463 

462Key464Key

463 465 

466[`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace)

467 

468Maturity

469 

470Experimental

471 

472Details

473 

474Add, upgrade, or remove plugin marketplaces from Git or local sources.

475 

476Key

477 

464[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)478[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)

465 479 

466Maturity480Maturity

481 495 

482Details496Details

483 497 

484Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes.498Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.

499 

500Key

501 

502[`codex update`](https://developers.openai.com/codex/cli/reference#codex-update)

503 

504Maturity

505 

506Stable

507 

508Details

509 

510Check for and apply a Codex CLI update when the installed release supports self-update.

485 511 

486Expand to view all512Expand to view all

487 513 

489 515 

490### `codex` (interactive)516### `codex` (interactive)

491 517 

492Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing and `--full-auto` to let Codex run most commands without prompts.518Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing. For low-friction local work, use `--sandbox workspace-write --ask-for-approval on-request`.

493 519 

494Use `--remote ws://host:port` or `--remote wss://host:port` to connect the TUI to an app server started with `codex app-server --listen ws://IP:PORT`. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication. See [Codex CLI features](https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server) for setup examples and authentication guidance.520Use `--remote ws://host:port` or `--remote wss://host:port` to connect the TUI to an app server started with `codex app-server --listen ws://IP:PORT`. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication. See [Codex CLI features](https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server) for setup examples and authentication guidance.

495 521 

595 621 

596### `codex app`622### `codex app`

597 623 

598Launch Codex Desktop from the terminal on macOS and optionally open a specific workspace path.624Launch Codex Desktop from the terminal on macOS or Windows. On macOS, Codex can open a specific workspace path; on Windows, Codex prints the path to open.

599 625 

600| Key | Type / Values | Details |626| Key | Type / Values | Details |

601| --- | --- | --- |627| --- | --- | --- |

602| `--download-url` | `url` | Advanced override for the Codex desktop DMG download URL used during install. |628| `--download-url` | `url` | Advanced override for the Codex desktop installer URL used during install. |

603| `PATH` | `path` | Workspace path to open in Codex Desktop (`codex app` is available on macOS only). |629| `PATH` | `path` | Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path. |

604 630 

605Key631Key

606 632 

612 638 

613Details639Details

614 640 

615Advanced override for the Codex desktop DMG download URL used during install.641Advanced override for the Codex desktop installer URL used during install.

616 642 

617Key643Key

618 644 

624 650 

625Details651Details

626 652 

627Workspace path to open in Codex Desktop (`codex app` is available on macOS only).653Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.

628 654 

629`codex app` installs/opens the desktop app on macOS, then opens the provided workspace path. This subcommand is macOS-only.655`codex app` opens an installed Codex Desktop app, or starts the installer when

656the app is missing. On macOS, Codex opens the provided workspace path; on

657Windows, it prints the path to open after installation.

630 658 

631### `codex debug app-server send-message-v2`659### `codex debug app-server send-message-v2`

632 660 

650 678 

651This debug flow initializes with `experimentalApi: true`, starts a thread, sends a turn, and streams server notifications. Use it to reproduce and inspect app-server protocol behavior locally.679This debug flow initializes with `experimentalApi: true`, starts a thread, sends a turn, and streams server notifications. Use it to reproduce and inspect app-server protocol behavior locally.

652 680 

681### `codex debug models`

682 

683Print the raw model catalog Codex sees as JSON.

684 

685| Key | Type / Values | Details |

686| --- | --- | --- |

687| `--bundled` | `boolean` | Skip refresh and print only the model catalog bundled with the current Codex binary. |

688 

689Key

690 

691`--bundled`

692 

693Type / Values

694 

695`boolean`

696 

697Details

698 

699Skip refresh and print only the model catalog bundled with the current Codex binary.

700 

701Use `--bundled` when you want to inspect only the catalog bundled with the current binary, without refreshing from the remote models endpoint.

702 

653### `codex apply`703### `codex apply`

654 704 

655Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.705Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.

857| `--color` | `always | never | auto` | Control ANSI color in stdout. |907| `--color` | `always | never | auto` | Control ANSI color in stdout. |

858| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |908| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |

859| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |909| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |

860| `--full-auto` | `boolean` | Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals). |910| `--full-auto` | `boolean` | Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used. |

911| `--ignore-rules` | `boolean` | Do not load user or project execpolicy `.rules` files for this run. |

912| `--ignore-user-config` | `boolean` | Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`. |

861| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |913| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |

862| `--json, --experimental-json` | `boolean` | Print newline-delimited JSON events instead of formatted text. |914| `--json, --experimental-json` | `boolean` | Print newline-delimited JSON events instead of formatted text. |

863| `--model, -m` | `string` | Override the configured model for this run. |915| `--model, -m` | `string` | Override the configured model for this run. |

929 981 

930Details982Details

931 983 

932Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals).984Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.

985 

986Key

987 

988`--ignore-rules`

989 

990Type / Values

991 

992`boolean`

993 

994Details

995 

996Do not load user or project execpolicy `.rules` files for this run.

997 

998Key

999 

1000`--ignore-user-config`

1001 

1002Type / Values

1003 

1004`boolean`

1005 

1006Details

1007 

1008Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.

933 1009 

934Key1010Key

935 1011 

1381 1457 

1382OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).1458OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).

1383 1459 

1460### `codex plugin marketplace`

1461 

1462Manage plugin marketplace sources that Codex can browse and install from.

1463 

1464| Key | Type / Values | Details |

1465| --- | --- | --- |

1466| `add <source>` | `[--ref REF] [--sparse PATH]` | Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. `--sparse` is supported only for Git sources and can be repeated. |

1467| `remove <marketplace-name>` | | Remove a configured plugin marketplace. |

1468| `upgrade [marketplace-name]` | | Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided. |

1469 

1470Key

1471 

1472`add <source>`

1473 

1474Type / Values

1475 

1476`[--ref REF] [--sparse PATH]`

1477 

1478Details

1479 

1480Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. `--sparse` is supported only for Git sources and can be repeated.

1481 

1482Key

1483 

1484`remove <marketplace-name>`

1485 

1486Details

1487 

1488Remove a configured plugin marketplace.

1489 

1490Key

1491 

1492`upgrade [marketplace-name]`

1493 

1494Details

1495 

1496Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided.

1497 

1498`codex plugin marketplace add` accepts GitHub shorthand such as `owner/repo` or

1499`owner/repo@ref`, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace

1500root directories. Use `--ref` to pin a Git ref, and repeat `--sparse PATH` to

1501use a sparse checkout for Git-backed marketplace repositories.

1502 

1384### `codex mcp-server`1503### `codex mcp-server`

1385 1504 

1386Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.1505Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.

1485 1604 

1486| Key | Type / Values | Details |1605| Key | Type / Values | Details |

1487| --- | --- | --- |1606| --- | --- | --- |

1607| `--allow-unix-socket` | `path` | Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths. |

1608| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |

1488| `--config, -c` | `key=value` | Pass configuration overrides into the sandboxed run (repeatable). |1609| `--config, -c` | `key=value` | Pass configuration overrides into the sandboxed run (repeatable). |

1489| `--full-auto` | `boolean` | Grant write access to the current workspace and `/tmp` without approvals. |1610| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |

1611| `--log-denials` | `boolean` | Capture macOS sandbox denials with `log stream` while the command runs and print them after exit. |

1612| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |

1490| `COMMAND...` | `var-args` | Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded. |1613| `COMMAND...` | `var-args` | Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded. |

1491 1614 

1492Key1615Key

1493 1616 

1617`--allow-unix-socket`

1618 

1619Type / Values

1620 

1621`path`

1622 

1623Details

1624 

1625Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths.

1626 

1627Key

1628 

1629`--cd, -C`

1630 

1631Type / Values

1632 

1633`DIR`

1634 

1635Details

1636 

1637Working directory used for profile resolution and command execution. Requires `--permissions-profile`.

1638 

1639Key

1640 

1494`--config, -c`1641`--config, -c`

1495 1642 

1496Type / Values1643Type / Values

1503 1650 

1504Key1651Key

1505 1652 

1506`--full-auto`1653`--include-managed-config`

1654 

1655Type / Values

1656 

1657`boolean`

1658 

1659Details

1660 

1661Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.

1662 

1663Key

1664 

1665`--log-denials`

1507 1666 

1508Type / Values1667Type / Values

1509 1668 

1511 1670 

1512Details1671Details

1513 1672 

1514Grant write access to the current workspace and `/tmp` without approvals.1673Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.

1674 

1675Key

1676 

1677`--permissions-profile`

1678 

1679Type / Values

1680 

1681`NAME`

1682 

1683Details

1684 

1685Apply a named permissions profile from the active configuration stack.

1515 1686 

1516Key1687Key

1517 1688 

1529 1700 

1530| Key | Type / Values | Details |1701| Key | Type / Values | Details |

1531| --- | --- | --- |1702| --- | --- | --- |

1703| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |

1532| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |1704| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |

1533| `--full-auto` | `boolean` | Grant write access to the current workspace and `/tmp` inside the Landlock sandbox. |1705| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |

1706| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |

1534| `COMMAND...` | `var-args` | Command to execute under Landlock + seccomp. Provide the executable after `--`. |1707| `COMMAND...` | `var-args` | Command to execute under Landlock + seccomp. Provide the executable after `--`. |

1535 1708 

1536Key1709Key

1537 1710 

1711`--cd, -C`

1712 

1713Type / Values

1714 

1715`DIR`

1716 

1717Details

1718 

1719Working directory used for profile resolution and command execution. Requires `--permissions-profile`.

1720 

1721Key

1722 

1538`--config, -c`1723`--config, -c`

1539 1724 

1540Type / Values1725Type / Values

1547 1732 

1548Key1733Key

1549 1734 

1550`--full-auto`1735`--include-managed-config`

1551 1736 

1552Type / Values1737Type / Values

1553 1738 

1555 1740 

1556Details1741Details

1557 1742 

1558Grant write access to the current workspace and `/tmp` inside the Landlock sandbox.1743Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.

1744 

1745Key

1746 

1747`--permissions-profile`

1748 

1749Type / Values

1750 

1751`NAME`

1752 

1753Details

1754 

1755Apply a named permissions profile from the active configuration stack.

1559 1756 

1560Key1757Key

1561 1758 

1569 1766 

1570Command to execute under Landlock + seccomp. Provide the executable after `--`.1767Command to execute under Landlock + seccomp. Provide the executable after `--`.

1571 1768 

1769#### Windows

1770 

1771| Key | Type / Values | Details |

1772| --- | --- | --- |

1773| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |

1774| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |

1775| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |

1776| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |

1777| `COMMAND...` | `var-args` | Command to execute under the native Windows sandbox. Provide the executable after `--`. |

1778 

1779Key

1780 

1781`--cd, -C`

1782 

1783Type / Values

1784 

1785`DIR`

1786 

1787Details

1788 

1789Working directory used for profile resolution and command execution. Requires `--permissions-profile`.

1790 

1791Key

1792 

1793`--config, -c`

1794 

1795Type / Values

1796 

1797`key=value`

1798 

1799Details

1800 

1801Configuration overrides applied before launching the sandbox (repeatable).

1802 

1803Key

1804 

1805`--include-managed-config`

1806 

1807Type / Values

1808 

1809`boolean`

1810 

1811Details

1812 

1813Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.

1814 

1815Key

1816 

1817`--permissions-profile`

1818 

1819Type / Values

1820 

1821`NAME`

1822 

1823Details

1824 

1825Apply a named permissions profile from the active configuration stack.

1826 

1827Key

1828 

1829`COMMAND...`

1830 

1831Type / Values

1832 

1833`var-args`

1834 

1835Details

1836 

1837Command to execute under the native Windows sandbox. Provide the executable after `--`.

1838 

1839### `codex update`

1840 

1841Check for and apply a Codex CLI update when the installed release supports self-update. Debug builds print a message telling you to install a release build instead.

1842 

1572## Flag combinations and safety tips1843## Flag combinations and safety tips

1573 1844 

1574- Set `--full-auto` for unattended local work, but avoid combining it with `--dangerously-bypass-approvals-and-sandbox` unless you are inside a dedicated sandbox VM.1845- Use `--sandbox workspace-write` for unattended local work that can stay inside the workspace, and avoid `--dangerously-bypass-approvals-and-sandbox` unless you are inside a dedicated sandbox VM.

1575- When you need to grant Codex write access to more directories, prefer `--add-dir` rather than forcing `--sandbox danger-full-access`.1846- When you need to grant Codex write access to more directories, prefer `--add-dir` rather than forcing `--sandbox danger-full-access`.

1576- Pair `--json` with `--output-last-message` in CI to capture machine-readable progress and a final natural-language summary.1847- Pair `--json` with `--output-last-message` in CI to capture machine-readable progress and a final natural-language summary.

1577 1848 

16Codex ships with the following commands. Open the slash popup and start typing16Codex ships with the following commands. Open the slash popup and start typing

17the command name to filter the list.17the command name to filter the list.

18 18 

19When a task is already running, you can type a slash command and press `Tab` to

20queue it for the next turn. Codex parses queued slash commands when they run, so

21command menus and errors appear after the current turn finishes. Slash

22completion still works before you queue the command.

23 

19| Command | Purpose | When to use it |24| Command | Purpose | When to use it |

20| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |25| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |

21| [`/permissions`](#update-permissions-with-permissions) | Set what Codex can do without asking first. | Relax or tighten approval requirements mid-session, such as switching between Auto and Read Only. |26| [`/permissions`](#update-permissions-with-permissions) | Set what Codex can do without asking first. | Relax or tighten approval requirements mid-session, such as switching between Auto and Read Only. |

25| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |30| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |

26| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a fresh start. |31| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a fresh start. |

27| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |32| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |

28| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. |33| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |

29| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |34| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |

30| [`/exit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI (same as `/quit`). | Alternative spelling; both commands exit the session. |35| [`/exit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI (same as `/quit`). | Alternative spelling; both commands exit the session. |

31| [`/experimental`](#toggle-experimental-features-with-experimental) | Toggle experimental features. | Enable optional features such as subagents from the CLI. |36| [`/experimental`](#toggle-experimental-features-with-experimental) | Toggle experimental features. | Enable optional features such as subagents from the CLI. |

32| [`/feedback`](#send-feedback-with-feedback) | Send logs to the Codex maintainers. | Report issues or share diagnostics with support. |37| [`/feedback`](#send-feedback-with-feedback) | Send logs to the Codex maintainers. | Report issues or share diagnostics with support. |

33| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |38| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |

34| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |39| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |

35| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session. |40| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session; add `verbose` for server details. |

36| [`/mention`](#highlight-files-with-mention) | Attach a file to the conversation. | Point Codex at specific files or folders you want it to inspect next. |41| [`/mention`](#highlight-files-with-mention) | Attach a file to the conversation. | Point Codex at specific files or folders you want it to inspect next. |

37| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |42| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |

38| [`/fast`](#toggle-fast-mode-with-fast) | Toggle Fast mode for GPT-5.4. | Turn Fast mode on or off, or check whether the current thread is using it. |43| [`/fast`](#toggle-fast-mode-with-fast) | Toggle Fast mode for supported models. | Turn Fast mode on or off, or check whether the current thread is using it. |

39| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |44| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |

40| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |45| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |

41| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |46| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |

42| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |47| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |

43| [`/fork`](#fork-the-current-conversation-with-fork) | Fork the current conversation into a new thread. | Branch the active session to explore a new approach without losing the current transcript. |48| [`/fork`](#fork-the-current-conversation-with-fork) | Fork the current conversation into a new thread. | Branch the active session to explore a new approach without losing the current transcript. |

49| [`/side`](#start-a-side-conversation-with-side) | Start an ephemeral side conversation. | Ask a focused follow-up without disrupting the main thread's transcript. |

44| [`/resume`](#resume-a-saved-conversation-with-resume) | Resume a saved conversation from your session list. | Continue work from a previous CLI session without starting over. |50| [`/resume`](#resume-a-saved-conversation-with-resume) | Resume a saved conversation from your session list. | Continue work from a previous CLI session without starting over. |

45| [`/new`](#start-a-new-conversation-with-new) | Start a new conversation inside the same CLI session. | Reset the chat context without leaving the CLI when you want a fresh prompt in the same repo. |51| [`/new`](#start-a-new-conversation-with-new) | Start a new conversation inside the same CLI session. | Reset the chat context without leaving the CLI when you want a fresh prompt in the same repo. |

46| [`/quit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI. | Leave the session immediately. |52| [`/quit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI. | Leave the session immediately. |