workflows.md +60 −2
1# Workflows1# Workflows
2 2
3Development usage patterns with Codex
4
5Codex works best when you treat it like a teammate with explicit context and a clear definition of "done."3Codex works best when you treat it like a teammate with explicit context and a clear definition of "done."
6This page gives end-to-end workflow examples for the Codex IDE extension, the Codex CLI, and Codex cloud.4This page gives end-to-end workflow examples for the Codex IDE extension, the Codex CLI, and Codex cloud.
7 5
26 24
27### IDE extension workflow (fastest for local exploration)25### IDE extension workflow (fastest for local exploration)
28 26
27<WorkflowSteps>
28
291. Open the most relevant files.291. Open the most relevant files.
302. Select the code you care about (optional but recommended).302. Select the code you care about (optional but recommended).
313. Prompt Codex:313. Prompt Codex:
39 - one or two "gotchas" to watch for when changing this39 - one or two "gotchas" to watch for when changing this
40 ```40 ```
41 41
42</WorkflowSteps>
43
42Verification:44Verification:
43 45
44- Ask for a diagram or checklist you can validate quickly:46- Ask for a diagram or checklist you can validate quickly:
49 51
50### CLI workflow (good when you want a transcript + shell commands)52### CLI workflow (good when you want a transcript + shell commands)
51 53
54<WorkflowSteps>
55
521. Start an interactive session:561. Start an interactive session:
53 57
54 ```bash58 ```bash
60 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.
61 ```66 ```
62 67
68</WorkflowSteps>
69
63Context notes:70Context notes:
64 71
65- 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.
72 79
73### CLI workflow (tight loop with reproduction and verification)80### CLI workflow (tight loop with reproduction and verification)
74 81
82<WorkflowSteps>
83
751. Start Codex at the repo root:841. Start Codex at the repo root:
76 85
77 ```bash86 ```bash
96 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.
97 ```107 ```
98 108
109</WorkflowSteps>
110
99Context notes:111Context notes:
100 112
101- 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).
112 124
113### IDE extension workflow125### IDE extension workflow
114 126
127<WorkflowSteps>
128
1151. 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.
1162. Prompt Codex:1302. Prompt Codex:
117 131
119 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.
120 ```134 ```
121 135
136</WorkflowSteps>
137
122---138---
123 139
124## Write a test140## Write a test
127 143
128### IDE extension workflow (selection-based)144### IDE extension workflow (selection-based)
129 145
146<WorkflowSteps>
147
1301. Open the file with the function.1481. Open the file with the function.
1312. 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.
1323. Prompt Codex:1503. Prompt Codex:
135 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.
136 ```154 ```
137 155
156</WorkflowSteps>
157
138Context notes:158Context notes:
139 159
140- 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.
141 161
142### CLI workflow (path + line range described in prompt)162### CLI workflow (path + line range described in prompt)
143 163
164<WorkflowSteps>
165
1441. Start Codex:1661. Start Codex:
145 167
146 ```bash168 ```bash
152 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.
153 ```176 ```
154 177
178</WorkflowSteps>
179
155---180---
156 181
157## Prototype from a screenshot182## Prototype from a screenshot
160 185
161### CLI workflow (image + prompt)186### CLI workflow (image + prompt)
162 187
188<WorkflowSteps>
189
1631. Save your screenshot locally (for example `./specs/ui.png`).1901. Save your screenshot locally (for example `./specs/ui.png`).
1642. Run Codex:1912. Run Codex:
165 192
182 - README.md with instructions to run it locally211 - README.md with instructions to run it locally
183 ```212 ```
184 213
214</WorkflowSteps>
215
185Context notes:216Context notes:
186 217
187- 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).
197 228
198### IDE extension workflow (image + existing files)229### IDE extension workflow (image + existing files)
199 230
231<WorkflowSteps>
232
2001. 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).
2012. Prompt Codex:2342. Prompt Codex:
202 235
205 Follow design and visual patterns from other files in this project.238 Follow design and visual patterns from other files in this project.
206 ```239 ```
207 240
241</WorkflowSteps>
242
208---243---
209 244
210## Iterate on UI with live updates245## Iterate on UI with live updates
213 248
214### CLI workflow (run Vite, then iterate with small prompts)249### CLI workflow (run Vite, then iterate with small prompts)
215 250
251<WorkflowSteps>
252
2161. Start Codex:2531. Start Codex:
217 254
218 ```bash255 ```bash
245 Keep the layout, but simplify colors and remove any redundant borders.286 Keep the layout, but simplify colors and remove any redundant borders.
246 ```287 ```
247 288
289</WorkflowSteps>
290
248Verification:291Verification:
249 292
250- Review changes in the browser "live" as the code is updated.293- Review changes in the browser "live" as the code is updated.
259 302
260### Local planning (IDE)303### Local planning (IDE)
261 304
305<WorkflowSteps>
306
2621. 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.
2632. 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:
264 309
283 - include a rollback strategy329 - include a rollback strategy
284 ```330 ```
285 331
332</WorkflowSteps>
333
286Context notes:334Context notes:
287 335
288- 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).
289 337
290### Cloud delegation (IDE → Cloud)338### Cloud delegation (IDE → Cloud)
291 339
340<WorkflowSteps>
341
2921. 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).
2932. 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.
2943. 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).
296 ```text346 ```text
297 Implement Milestone 1 from the plan.347 Implement Milestone 1 from the plan.
298 ```348 ```
349
2994. Review the cloud diff, iterate if needed.3504. Review the cloud diff, iterate if needed.
351
3005. 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
3016. Iterate on additional milestones of the plan.3546. Iterate on additional milestones of the plan.
302 355
356</WorkflowSteps>
357
303---358---
304 359
305## Do a local code review360## Do a local code review
308 363
309### CLI workflow (review your working tree)364### CLI workflow (review your working tree)
310 365
366<WorkflowSteps>
367
3111. Start Codex:3681. Start Codex:
312 369
313 ```bash370 ```bash
324 /review Focus on edge cases and security issues383 /review Focus on edge cases and security issues
325 ```384 ```
326 385
386</WorkflowSteps>
387
327Verification:388Verification:
328 389
329- 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.
338 399
339### GitHub workflow (comment-driven)400### GitHub workflow (comment-driven)
340 401
402<WorkflowSteps>
403
3411. Open the pull request on GitHub.4041. Open the pull request on GitHub.
3422. Leave a comment that tags Codex with explicit focus areas:4052. Leave a comment that tags Codex with explicit focus areas:
343 406
350 @codex review for security vulnerabilities and security concerns414 @codex review for security vulnerabilities and security concerns
351 ```415 ```
352 416
417</WorkflowSteps>
418
353---419---
354 420
355## Update documentation421## Update documentation
358 424
359### IDE or CLI workflow (local edits + local validation)425### IDE or CLI workflow (local edits + local validation)
360 426
427<WorkflowSteps>
428
3611. 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).
3622. Prompt Codex with scope and validation requirements:4302. Prompt Codex with scope and validation requirements:
363 431
364 ```text432 ```text
365 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.
366 ```434 ```
435
3673. 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.
368 437
438</WorkflowSteps>
439
369Verification:440Verification:
370 441
371- Read the rendered page.442- Read the rendered page.