OpenAI - Codex Docs Changes 2026-02-24 06:27 UTC → 2026-03-03 00:35 UTC

1# Codex app

2 

3The Codex app is a focused desktop experience for working on Codex threads in parallel, with built-in worktree support, automations, and Git functionality.

4 

5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what’s included](https://developers.openai.com/codex/pricing).

6 

7![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)

8 

9## Getting started

10 

11The Codex app is available on macOS (Apple Silicon).

12 

131. Download and install the Codex app

14 

15 The Codex app is currently only available for macOS.

16 

17 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

18 

19 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)

202. Open Codex and sign in

21 

22 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.

23 

24 If you sign in with an OpenAI API key, some functionality such as [cloud threads](https://developers.openai.com/codex/prompting#threads) might not be available.

253. Select a project

26 

27 Choose a project folder that you want Codex to work in.

28 

29If you used the Codex app, CLI, or IDE Extension before you’ll see past projects that you worked on.

30 

314. Send your first message

32 

33 After choosing the project, make sure **Local** is selected to have Codex work on your machine and send your first message to Codex.

34 

35 You can ask Codex anything about the project or your computer in general. Here are some examples:

36 

37- Tell me about this project

38- Build a classic Snake game in this repo.

39- Find and fix bugs in my codebase with minimal, high-confidence changes.

40 

41 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).

42 

43---

44 

45## Work with the Codex app

46 

47[### Multitask across projects

48 

49Run multiple tasks in parallel and switch quickly between them.](https://developers.openai.com/codex/app/features#multitask-across-projects)[### Built-in Git tools

50 

51Review diffs, comment inline, stage or revert chunks, and commit without leaving the app.](https://developers.openai.com/codex/app/features#built-in-git-tools)[### Worktrees for parallel tasks

52 

53Isolate changes of multiple Codex threads using built-in Git worktree support.](https://developers.openai.com/codex/app/worktrees)[### Skills support

54 

55Give your Codex agent additional capabilities and reuse skills across App, CLI, and IDE Extension.](https://developers.openai.com/codex/app/features#skills-support)[### Automations

56 

57Pair skills with automations to automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives runs if there’s nothing to report.](https://developers.openai.com/codex/app/automations)[### Built-in terminal

58 

59Open a terminal per thread to test your changes, run dev servers, scripts, and custom commands.](https://developers.openai.com/codex/app/features#integrated-terminal)[### Local environments

60 

61Define worktree setup scripts and common project actions for easy access.](https://developers.openai.com/codex/app/local-environments)[### Sync with the IDE extension

62 

63Share Auto Context and active threads across app and IDE sessions.](https://developers.openai.com/codex/app/features#sync-with-the-ide-extension)[### MCP support

64 

65Connect your Codex agent to additional services using MCP.](https://developers.openai.com/codex/app/features#mcp-support)

66 

67---

68 

69Need help? Visit the [troubleshooting guide](https://developers.openai.com/codex/app/troubleshooting).

104 104 

105### Example agent roles105### Example agent roles

106 106 

107Below is an example that overrides the definitions for the built-in `default` and `explorer` agent roles and defines a new `reviewer` role.107The best role definitions are narrow and opinionated. Give each role one clear job, a tool surface that matches that job, and instructions that keep it from drifting into adjacent work.

108 108 

109Example `~/.codex/config.toml`:109#### Example 1: PR review team

110 

111This pattern splits review into three focused roles:

112 

113- `explorer` maps the codebase and gathers evidence.

114- `reviewer` looks for correctness, security, and test risks.

115- `docs_researcher` checks framework or API documentation through a dedicated MCP server.

116 

117Project config (`.codex/config.toml`):

110 118 

111```119```

112[agents.default]120[agents]

113description = "General-purpose helper."121max_threads = 6

122max_depth = 1

123 

124[agents.explorer]

125description = "Read-only codebase explorer for gathering evidence before changes are proposed."

126config_file = "agents/explorer.toml"

114 127 

115[agents.reviewer]128[agents.reviewer]

116description = "Find security, correctness, and test risks in code."129description = "PR reviewer focused on correctness, security, and missing tests."

117config_file = "agents/reviewer.toml"130config_file = "agents/reviewer.toml"

118 131 

119[agents.explorer]132[agents.docs_researcher]

120description = "Fast codebase explorer for read-heavy tasks."133description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

121config_file = "agents/custom-explorer.toml"134config_file = "agents/docs-researcher.toml"

135```

136 

137`agents/explorer.toml`:

138 

139```

140model = "gpt-5.3-codex-spark"

141model_reasoning_effort = "medium"

142sandbox_mode = "read-only"

143developer_instructions = """

144Stay in exploration mode.

145Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.

146Prefer fast search and targeted file reads over broad scans.

147"""

122```148```

123 149 

124Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):150`agents/reviewer.toml`:

125 151 

126```152```

127model = "gpt-5.3-codex"153model = "gpt-5.3-codex"

128model_reasoning_effort = "high"154model_reasoning_effort = "high"

129developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability."155sandbox_mode = "read-only"

156developer_instructions = """

157Review code like an owner.

158Prioritize correctness, security, behavior regressions, and missing test coverage.

159Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.

160"""

130```161```

131 162 

132Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):163`agents/docs-researcher.toml`:

133 164 

134```165```

135model = "gpt-5.3-codex-spark"166model = "gpt-5.3-codex-spark"

136model_reasoning_effort = "medium"167model_reasoning_effort = "medium"

137sandbox_mode = "read-only"168sandbox_mode = "read-only"

169developer_instructions = """

170Use the docs MCP server to confirm APIs, options, and version-specific behavior.

171Return concise answers with links or exact references when available.

172Do not make code changes.

173"""

174 

175[mcp_servers.openaiDeveloperDocs]

176url = "https://developers.openai.com/mcp"

177```

178 

179This setup works well for prompts like:

180 

181```

182Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

183```

184 

185#### Example 2: frontend integration debugging team

186 

187This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.

188 

189Project config (`.codex/config.toml`):

190 

191```

192[agents]

193max_threads = 6

194max_depth = 1

195 

196[agents.explorer]

197description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

198config_file = "agents/explorer.toml"

199 

200[agents.browser_debugger]

201description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."

202config_file = "agents/browser-debugger.toml"

203 

204[agents.worker]

205description = "Implementation-focused agent for small, targeted fixes after the issue is understood."

206config_file = "agents/worker.toml"

207```

208 

209`agents/explorer.toml`:

210 

211```

212model = "gpt-5.3-codex-spark"

213model_reasoning_effort = "medium"

214sandbox_mode = "read-only"

215developer_instructions = """

216Map the code that owns the failing UI flow.

217Identify entry points, state transitions, and likely files before the worker starts editing.

218"""

219```

220 

221`agents/browser-debugger.toml`:

222 

223```

224model = "gpt-5.3-codex"

225model_reasoning_effort = "high"

226sandbox_mode = "workspace-write"

227developer_instructions = """

228Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.

229Use browser tooling for screenshots, console output, and network evidence.

230Do not edit application code.

231"""

232 

233[mcp_servers.chrome_devtools]

234url = "http://localhost:3000/mcp"

235startup_timeout_sec = 20

236```

237 

238`agents/worker.toml`:

239 

240```

241model = "gpt-5.3-codex"

242model_reasoning_effort = "medium"

243developer_instructions = """

244Own the fix once the issue is reproduced.

245Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.

246"""

247 

248[[skills.config]]

249path = "/Users/me/.agents/skills/docs-editor/SKILL.md"

250enabled = false

251```

252 

253This setup works well for prompts like:

254 

255```

256Investigate why the settings modal fails to save. Have browser_debugger reproduce it, explorer trace the responsible code path, and worker implement the smallest fix once the failure mode is clear.

138```257```