workflows.md Codex Docs, 2026-03-18 00:36 UTC → 2026-05-13 00:57 UTC

24 24 

25### IDE extension workflow (fastest for local exploration)25### IDE extension workflow (fastest for local exploration)

26 26 

27<WorkflowSteps>

28 

271. Open the most relevant files.291. Open the most relevant files.

282. Select the code you care about (optional but recommended).302. Select the code you care about (optional but recommended).

293. Prompt Codex:313. Prompt Codex:

37 - one or two "gotchas" to watch for when changing this39 - one or two "gotchas" to watch for when changing this

38 ```40 ```

39 41 

42</WorkflowSteps>

43 

40Verification:44Verification:

41 45 

42- Ask for a diagram or checklist you can validate quickly:46- Ask for a diagram or checklist you can validate quickly:

47 51 

48### CLI workflow (good when you want a transcript + shell commands)52### CLI workflow (good when you want a transcript + shell commands)

49 53 

54<WorkflowSteps>

55 

501. Start an interactive session:561. Start an interactive session:

51 57 

52 ```bash58 ```bash

58 I need to understand the protocol used by this service. Read @foo.ts @schema.ts and explain the schema and request/response flow. Focus on required vs optional fields and backward compatibility rules.65 I need to understand the protocol used by this service. Read @foo.ts @schema.ts and explain the schema and request/response flow. Focus on required vs optional fields and backward compatibility rules.

59 ```66 ```

60 67 

68</WorkflowSteps>

69 

61Context notes:70Context notes:

62 71 

63- You can use `@` in the composer to insert file paths from the workspace, or `/mention` to attach a specific file.72- You can use `@` in the composer to insert file paths from the workspace, or `/mention` to attach a specific file.

70 79 

71### CLI workflow (tight loop with reproduction and verification)80### CLI workflow (tight loop with reproduction and verification)

72 81 

82<WorkflowSteps>

83 

731. Start Codex at the repo root:841. Start Codex at the repo root:

74 85 

75 ```bash86 ```bash

94 Start by reproducing the bug locally, then propose a patch and run checks.106 Start by reproducing the bug locally, then propose a patch and run checks.

95 ```107 ```

96 108 

109</WorkflowSteps>

110 

97Context notes:111Context notes:

98 112 

99- Supplied by you: the repro steps and constraints (these matter more than a high-level description).113- Supplied by you: the repro steps and constraints (these matter more than a high-level description).

110 124 

111### IDE extension workflow125### IDE extension workflow

112 126 

127<WorkflowSteps>

128 

1131. Open the file where you think the bug lives, plus its nearest caller.1291. Open the file where you think the bug lives, plus its nearest caller.

1142. Prompt Codex:1302. Prompt Codex:

115 131 

117 Find the bug causing "Saved" to show without persisting changes. After proposing the fix, tell me how to verify it in the UI.133 Find the bug causing "Saved" to show without persisting changes. After proposing the fix, tell me how to verify it in the UI.

118 ```134 ```

119 135 

136</WorkflowSteps>

137 

120---138---

121 139 

122## Write a test140## Write a test

125 143 

126### IDE extension workflow (selection-based)144### IDE extension workflow (selection-based)

127 145 

146<WorkflowSteps>

147 

1281. Open the file with the function.1481. Open the file with the function.

1292. Select the lines that define the function. Choose "Add to Codex Thread" from command palette to add these lines to the context.1492. Select the lines that define the function. Choose "Add to Codex Thread" from command palette to add these lines to the context.

1303. Prompt Codex:1503. Prompt Codex:

133 Write a unit test for this function. Follow conventions used in other tests.153 Write a unit test for this function. Follow conventions used in other tests.

134 ```154 ```

135 155 

156</WorkflowSteps>

157 

136Context notes:158Context notes:

137 159 

138- Supplied by "Add to Codex Thread" command: the selected lines (this is the "line number" scope), plus open files.160- Supplied by "Add to Codex Thread" command: the selected lines (this is the "line number" scope), plus open files.

139 161 

140### CLI workflow (path + line range described in prompt)162### CLI workflow (path + line range described in prompt)

141 163 

164<WorkflowSteps>

165 

1421. Start Codex:1661. Start Codex:

143 167 

144 ```bash168 ```bash

150 Add a test for the invert_list function in @transform.ts. Cover the happy path plus edge cases.175 Add a test for the invert_list function in @transform.ts. Cover the happy path plus edge cases.

151 ```176 ```

152 177 

178</WorkflowSteps>

179 

153---180---

154 181 

155## Prototype from a screenshot182## Prototype from a screenshot

158 185 

159### CLI workflow (image + prompt)186### CLI workflow (image + prompt)

160 187 

188<WorkflowSteps>

189 

1611. Save your screenshot locally (for example `./specs/ui.png`).1901. Save your screenshot locally (for example `./specs/ui.png`).

1622. Run Codex:1912. Run Codex:

163 192 

180 - README.md with instructions to run it locally211 - README.md with instructions to run it locally

181 ```212 ```

182 213 

214</WorkflowSteps>

215 

183Context notes:216Context notes:

184 217 

185- The image provides visual requirements, but you still need to specify the implementation constraints (framework, routing, component style).218- The image provides visual requirements, but you still need to specify the implementation constraints (framework, routing, component style).

195 228 

196### IDE extension workflow (image + existing files)229### IDE extension workflow (image + existing files)

197 230 

231<WorkflowSteps>

232 

1981. Attach the image in the Codex chat (drag-and-drop or paste).2331. Attach the image in the Codex chat (drag-and-drop or paste).

1992. Prompt Codex:2342. Prompt Codex:

200 235 

203 Follow design and visual patterns from other files in this project.238 Follow design and visual patterns from other files in this project.

204 ```239 ```

205 240 

241</WorkflowSteps>

242 

206---243---

207 244 

208## Iterate on UI with live updates245## Iterate on UI with live updates

211 248 

212### CLI workflow (run Vite, then iterate with small prompts)249### CLI workflow (run Vite, then iterate with small prompts)

213 250 

251<WorkflowSteps>

252 

2141. Start Codex:2531. Start Codex:

215 254 

216 ```bash255 ```bash

243 Keep the layout, but simplify colors and remove any redundant borders.286 Keep the layout, but simplify colors and remove any redundant borders.

244 ```287 ```

245 288 

289</WorkflowSteps>

290 

246Verification:291Verification:

247 292 

248- Review changes in the browser "live" as the code is updated.293- Review changes in the browser "live" as the code is updated.

257 302 

258### Local planning (IDE)303### Local planning (IDE)

259 304 

305<WorkflowSteps>

306 

2601. Make sure your current work is committed or at least stashed so you can compare changes cleanly.3071. Make sure your current work is committed or at least stashed so you can compare changes cleanly.

2612. Ask Codex to produce a refactor plan. If you have the `$plan` skill available, invoke it explicitly:3082. Ask Codex to produce a refactor plan. If you have the `$plan` skill available, invoke it explicitly:

262 309 

281 - include a rollback strategy329 - include a rollback strategy

282 ```330 ```

283 331 

332</WorkflowSteps>

333 

284Context notes:334Context notes:

285 335 

286- Planning works best when Codex can scan the current code locally (entrypoints, module boundaries, dependency graph hints).336- Planning works best when Codex can scan the current code locally (entrypoints, module boundaries, dependency graph hints).

287 337 

288### Cloud delegation (IDE → Cloud)338### Cloud delegation (IDE → Cloud)

289 339 

340<WorkflowSteps>

341 

2901. If you haven't already done so, set up a [Codex cloud environment](https://developers.openai.com/codex/cloud/environments).3421. If you haven't already done so, set up a [Codex cloud environment](https://developers.openai.com/codex/cloud/environments).

2912. Click on the cloud icon beneath the prompt composer and select your cloud environment.3432. Click on the cloud icon beneath the prompt composer and select your cloud environment.

2923. When you enter the next prompt, Codex creates a new thread in the cloud that carries over the existing thread context (including the plan and any local source changes).3443. When you enter the next prompt, Codex creates a new thread in the cloud that carries over the existing thread context (including the plan and any local source changes).

294 ```text346 ```text

295 Implement Milestone 1 from the plan.347 Implement Milestone 1 from the plan.

296 ```348 ```

349 

2974. Review the cloud diff, iterate if needed.3504. Review the cloud diff, iterate if needed.

351 

2985. Create a PR directly from the cloud or pull changes locally to test and finish up.3525. Create a PR directly from the cloud or pull changes locally to test and finish up.

353 

2996. Iterate on additional milestones of the plan.3546. Iterate on additional milestones of the plan.

300 355 

356</WorkflowSteps>

357 

301---358---

302 359 

303## Do a local code review360## Do a local code review

306 363 

307### CLI workflow (review your working tree)364### CLI workflow (review your working tree)

308 365 

366<WorkflowSteps>

367 

3091. Start Codex:3681. Start Codex:

310 369 

311 ```bash370 ```bash

322 /review Focus on edge cases and security issues383 /review Focus on edge cases and security issues

323 ```384 ```

324 385 

386</WorkflowSteps>

387 

325Verification:388Verification:

326 389 

327- Apply fixes based on review feedback, then rerun `/review` to confirm issues are resolved.390- Apply fixes based on review feedback, then rerun `/review` to confirm issues are resolved.

336 399 

337### GitHub workflow (comment-driven)400### GitHub workflow (comment-driven)

338 401 

402<WorkflowSteps>

403 

3391. Open the pull request on GitHub.4041. Open the pull request on GitHub.

3402. Leave a comment that tags Codex with explicit focus areas:4052. Leave a comment that tags Codex with explicit focus areas:

341 406 

348 @codex review for security vulnerabilities and security concerns414 @codex review for security vulnerabilities and security concerns

349 ```415 ```

350 416 

417</WorkflowSteps>

418 

351---419---

352 420 

353## Update documentation421## Update documentation

356 424 

357### IDE or CLI workflow (local edits + local validation)425### IDE or CLI workflow (local edits + local validation)

358 426 

427<WorkflowSteps>

428 

3591. Identify the doc file(s) to change and open them (IDE) or `@` mention them (IDE or CLI).4291. Identify the doc file(s) to change and open them (IDE) or `@` mention them (IDE or CLI).

3602. Prompt Codex with scope and validation requirements:4302. Prompt Codex with scope and validation requirements:

361 431 

362 ```text432 ```text

363 Update the "advanced features" documentation to provide authentication troubleshooting guidance. Verify that all links are valid.433 Update the "advanced features" documentation to provide authentication troubleshooting guidance. Verify that all links are valid.

364 ```434 ```

435 

3653. After Codex drafts the changes, review the documentation and iterate as needed.4363. After Codex drafts the changes, review the documentation and iterate as needed.

366 437 

438</WorkflowSteps>

439 

367Verification:440Verification:

368 441 

369- Read the rendered page.442- Read the rendered page.