cli/features.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-18 22:01 UTC

1# Codex CLI features1# Codex CLI features

2 2 

3Overview of functionality in the Codex terminal client

4 

5Codex supports workflows beyond chat. Use this guide to learn what each one unlocks and when to use it.3Codex supports workflows beyond chat. Use this guide to learn what each one unlocks and when to use it.

6 4 

7## Running in interactive mode5## Running in interactive mode

22 20 

23- Send prompts, code snippets, or screenshots (see [image inputs](#image-inputs)) directly into the composer.21- Send prompts, code snippets, or screenshots (see [image inputs](#image-inputs)) directly into the composer.

24- 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.

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` 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.

25- 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.

26- 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.

27 30 

28## Resuming conversations31## Resuming conversations

43 46 

44Each resumed run keeps the original transcript, plan history, and approvals, so Codex can use prior context while you supply new instructions. Override the working directory with `--cd` or add extra roots with `--add-dir` if you need to steer the environment before resuming.47Each resumed run keeps the original transcript, plan history, and approvals, so Codex can use prior context while you supply new instructions. Override the working directory with `--cd` or add extra roots with `--add-dir` if you need to steer the environment before resuming.

45 48 

49## Connect the TUI to a remote app server

50 

51Remote TUI mode lets you run the Codex app server on one machine and use the

52Codex terminal UI from another machine. Start the app server with a WebSocket

53listener:

54 

55```bash

56codex app-server --listen ws://127.0.0.1:4500

57```

58 

59Then connect the TUI to that endpoint:

60 

61```bash

62codex --remote ws://127.0.0.1:4500

63```

64 

65For access from another machine, bind the app server to a reachable interface

66and configure WebSocket auth before remote use:

67 

68```bash

69TOKEN_FILE="$HOME/.codex/app-server-token"

70openssl rand -base64 32 > "$TOKEN_FILE"

71chmod 600 "$TOKEN_FILE"

72codex app-server --listen ws://0.0.0.0:4500 --ws-auth capability-token --ws-token-file "$TOKEN_FILE"

73```

74 

75`--remote` accepts explicit `ws://host:port` and `wss://host:port` addresses.

76Plain WebSocket connections are appropriate for localhost and SSH

77port-forwarding workflows. For non-local clients, use WebSocket auth and put the

78connection behind TLS.

79 

80Codex supports these WebSocket authentication modes:

81 

82- Capability token: start the server with `--ws-auth capability-token` and

83 either `--ws-token-file /absolute/path` or `--ws-token-sha256 HEX`.

84- Signed bearer token: start the server with

85 `--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path`, plus

86 optional `--ws-issuer`, `--ws-audience`, and `--ws-max-clock-skew-seconds`.

87 

88The TUI sends the remote auth token as an `Authorization: Bearer <token>` header

89during the WebSocket handshake. Codex only accepts remote auth tokens over

90`wss://` URLs or loopback `ws://` URLs.

91 

92```bash

93export CODEX_REMOTE_TOKEN="$(cat "$TOKEN_FILE")"

94codex --remote wss://remote-host:4500 --remote-auth-token-env CODEX_REMOTE_TOKEN

95```

96 

97For SSH remote projects in the Codex app, use

98[Remote connections](https://developers.openai.com/codex/remote-connections). For managed remote-control

99clients, `codex remote-control` starts an app-server process with

100remote-control support enabled.

101 

46## Models and reasoning102## Models and reasoning

47 103 

48For most coding tasks in Codex, `gpt-5.3-codex` is the go-to model. It’s available for ChatGPT-authenticated Codex sessions in the Codex app, CLI, IDE extension, and Codex Cloud. For extra fast tasks, ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in research preview.104For most tasks in Codex, `gpt-5.5` is the recommended model when it's

105available. It's OpenAI's newest frontier model for complex coding, computer

106use, knowledge work, and research workflows, with stronger planning, tool use,

107and follow-through on multi-step tasks. If `gpt-5.5` isn't yet available,

108continue using `gpt-5.4`. For extra fast tasks, ChatGPT Pro subscribers have

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

49 110 

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

51 112 

52```bash113```bash

53codex --model gpt-5.3-codex114codex --model gpt-5.5

54```115```

55 116 

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

67 128 

68`codex features enable <feature>` and `codex features disable <feature>` write to `~/.codex/config.toml`. If you launch Codex with `--profile`, Codex stores the change in that profile rather than the root configuration.129`codex features enable <feature>` and `codex features disable <feature>` write to `~/.codex/config.toml`. If you launch Codex with `--profile`, Codex stores the change in that profile rather than the root configuration.

69 130 

70## Multi-agents (experimental)131## Subagents

71 132 

72Use Codex multi-agent workflows to parallelize larger tasks. For setup, role configuration (`[agents]` in `config.toml`), and examples, see [Multi-agents](https://developers.openai.com/codex/multi-agent).133Use Codex subagent workflows to parallelize larger tasks. For setup, role configuration (`[agents]` in `config.toml`), and examples, see [Subagents](https://developers.openai.com/codex/subagents).

134 

135Codex only spawns subagents when you explicitly ask it to. Because each

136subagent does its own model and tool work, subagent workflows consume more

137tokens than comparable single-agent runs.

73 138 

74## Image inputs139## Image inputs

75 140 

85 150 

86Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.151Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.

87 152 

153## Image generation

154 

155Ask Codex to generate or edit images directly in the CLI. This works well for assets such as icons, banners, illustrations, sprite sheets, and placeholder art. If you want Codex to transform or extend an existing asset, attach a reference image with your prompt.

156 

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

158 

159Built-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).

160 

161For 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.

162 

163## Syntax highlighting and themes

164 

165The TUI syntax-highlights fenced markdown code blocks and file diffs so code is easier to scan during reviews and debugging.

166 

167Use `/theme` to open the theme picker, preview themes live, and save your selection to `tui.theme` in `~/.codex/config.toml`. You can also add custom `.tmTheme` files under `$CODEX_HOME/themes` and select them in the picker.

168 

88## Running local code review169## Running local code review

89 170 

90Type `/review` in the CLI to open Codex's review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree. By default it uses the current session model; set `review_model` in `config.toml` to override.171Type `/review` in the CLI to open Codex's review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree. By default it uses the current session model; set `review_model` in `config.toml` to override.

98 179 

99## Web search180## Web search

100 181 

101Codex ships with a first-party web search tool. For local tasks in the Codex CLI, Codex enables web search by default and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security), web search defaults to live results. To fetch the most recent data, pass `--search` for a single run or set `web_search = "live"` in [Config basics](https://developers.openai.com/codex/config-basic). You can also set `web_search = "disabled"` to turn the tool off.182Codex ships with a first-party web search tool. For local tasks in the Codex CLI, Codex enables web search by default and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/agent-approvals-security), web search defaults to live results. To fetch the most recent data, pass `--search` for a single run or set `web_search = "live"` in [Config basics](https://developers.openai.com/codex/config-basic). You can also set `web_search = "disabled"` to turn the tool off.

102 183 

103You'll see `web_search` items in the transcript or `codex exec --json` output whenever Codex looks something up.184You'll see `web_search` items in the transcript or `codex exec --json` output whenever Codex looks something up.

104 185 

167 248 

168## Slash commands249## Slash commands

169 250 

170Slash 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.251Slash 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.

171 252 

172See 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.253See 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.

173 254 

186## Tips and shortcuts267## Tips and shortcuts

187 268 

188- 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.269- 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.

189- 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.270- 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.

190- 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.271- 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.

191- 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.272- 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.

192- 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.273- 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.

193- Expose more writable roots with `--add-dir` (for example, `codex --cd apps/frontend --add-dir ../backend --add-dir ../shared`) when you need to coordinate changes across more than one project.274- Expose more writable roots with `--add-dir` (for example, `codex --cd apps/frontend --add-dir ../backend --add-dir ../shared`) when you need to coordinate changes across more than one project.

194- Make sure your environment is already set up before launching Codex so it doesn't spend tokens probing what to activate. For example, source your Python virtual environment (or other language environments), start any required daemons, and export the environment variables you expect to use ahead of time.275- Make sure your environment is already set up before launching Codex so it doesn't spend tokens probing what to activate. For example, source your Python virtual environment (or other language environments), start any required daemons, and export the environment variables you expect to use ahead of time.

195 

196[Previous

197 

198Overview](https://developers.openai.com/codex/cli)[Next

199 

200Command Line Options](https://developers.openai.com/codex/cli/reference)