cli/features.md Codex Docs, 2026-03-06 00:38 UTC → 2026-04-24 18:20 UTC

20 20 

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

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 color 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

44 46 

45Each 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.

46 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 Codex terminal UI from another machine. This is useful when the code, credentials, or execution environment live on a remote host, but you want the local interactive TUI experience.

52 

53Start the app server on the machine that should own the workspace and run commands:

54 

55```bash

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

57```

58 

59Then connect from the machine running the TUI:

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, for example:

66 

67```bash

68codex app-server --listen ws://0.0.0.0:4500

69```

70 

71`--remote` accepts explicit `ws://host:port` and `wss://host:port` addresses only. For plain WebSocket connections, prefer local-host addresses or SSH port forwarding. If you expose the listener beyond the local host, configure authentication before real remote use and put authenticated non-local connections behind TLS.

72 

73Codex supports these WebSocket authentication modes for remote TUI connections:

74 

75- **No WebSocket auth**: Best for local-host listeners or SSH port-forwarded connections. Codex can start non-local listeners without auth, but logs a warning and the startup banner reminds you to configure auth before real remote use.

76- **Capability token**: Store a shared token in a file on the app-server host, start the server with `--ws-auth capability-token --ws-token-file /abs/path/to/token`, then set the same token in an environment variable on the TUI host and pass `--remote-auth-token-env <ENV_VAR>`.

77- **Signed bearer token**: Store an HMAC shared secret in a file on the app-server host, start the server with `--ws-auth signed-bearer-token --ws-shared-secret-file /abs/path/to/secret`, and have the TUI send a signed JWT bearer token through `--remote-auth-token-env <ENV_VAR>`. The shared secret must be at least 32 bytes. Signed tokens use HS256 and must include `exp`; Codex also validates `nbf`, `iss`, and `aud` when those claims or server options are present.

78 

79To create a capability token on the app-server host, generate a random token file with permissions that only your user can read:

80 

81```bash

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

83install -d -m 700 "$(dirname "$TOKEN_FILE")"

84openssl rand -base64 32 > "$TOKEN_FILE"

85chmod 600 "$TOKEN_FILE"

86```

87 

88Treat the token file like a password, and regenerate it if it leaks.

89 

90Then start the app server with that token file. For example, with a capability token behind a TLS proxy:

91 

92```bash

93# Remote host

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

95codex app-server \

96 --listen ws://0.0.0.0:4500 \

97 --ws-auth capability-token \

98 --ws-token-file "$TOKEN_FILE"

99 

100# TUI host

101export CODEX_REMOTE_AUTH_TOKEN="$(ssh devbox 'cat ~/.codex/codex-app-server-token')"

102codex --remote wss://codex-devbox.example.com:4500 \

103 --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN

104```

105 

106The TUI sends remote auth tokens as `Authorization: Bearer <token>` during the WebSocket handshake. Codex only sends those tokens over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`, so put non-local remote listeners behind TLS if clients need to authenticate over the network.

107 

47## Models and reasoning108## Models and reasoning

48 109 

49For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the industry-leading coding capabilities of `gpt-5.3-codex` to OpenAI’s flagship frontier model, combining frontier coding performance with stronger reasoning, native computer use, and broader professional workflows. For extra fast tasks, ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in research preview.110For most tasks in Codex, `gpt-5.5` is the recommended model when it is

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

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

113and follow-through on multi-step tasks. If `gpt-5.5` is not yet available,

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

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

50 116 

51Switch 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.

52 118 

53```bash119```bash

54codex --model gpt-5.4120codex --model gpt-5.5

55```121```

56 122 

57[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).

68 134 

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

70 136 

71## Multi-agents (experimental)137## Subagents

72 138 

73Use 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).139Use 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).

140 

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

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

143tokens than comparable single-agent runs.

74 144 

75## Image inputs145## Image inputs

76 146 

86 156 

87Codex 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.157Codex 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.

88 158 

159## Image generation

160 

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

162 

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

164 

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

166 

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.

168 

89## Syntax highlighting and themes169## Syntax highlighting and themes

90 170 

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

105 185 

106## Web search186## Web search

107 187 

108Codex 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.188Codex 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.

109 189 

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

111 191 

193## Tips and shortcuts273## Tips and shortcuts

194 274 

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

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

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

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

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