quickstart.md +324 −24
6 6
7## Setup7## Setup
8 8
9<script
10 is:inline
11 data-astro-rerun
12 set:html={String.raw`
13(() => {
14 const platform =
15 (navigator.userAgentData?.platform || navigator.platform || "").toLowerCase();
16 const isDesktopAppPlatform =
17 platform.includes("mac") ||
18 platform.includes("win") ||
19 /macintosh|mac os x|windows|win64|win32/i.test(navigator.userAgent || "");
20 if (!isDesktopAppPlatform) return;
21
22 const shouldPreferApp = () => {
23 try {
24 const url = new URL(window.location.href);
25 return !url.searchParams.get("setup");
26 } catch {
27 return true;
28 }
29 };
30
31 if (!shouldPreferApp()) return;
32
33 window.__tabsPreferred = window.__tabsPreferred || {};
34 window.__tabsPreferred.setup = "app";
35})();
36`}
37/>
38
39<Tabs
40 id="codex-quickstart-setup"
41 param="setup"
42 defaultTab="ide"
43 size="3xl"
44 block={true}
45 blockThreshold={170}
46 tabs={[
47 {
48 id: "app",
49 label: "App",
50 subtitle: "Recommended",
51 },
52 { id: "ide", label: "IDE extension", subtitle: "Codex in your IDE" },
53 { id: "cli", label: "CLI", subtitle: "Codex in your terminal" },
54 { id: "cloud", label: "Cloud", subtitle: "Codex in your browser" },
55 ]}
56>
57 <div slot="app">
9The Codex app is available on macOS and Windows.58The Codex app is available on macOS and Windows.
10 59
11Most Codex app features are available on both platforms. Platform-specific60Most Codex app features are available on both platforms. Platform-specific
12exceptions are noted in the relevant docs.61exceptions are noted in the relevant docs.
13 62
63<WorkflowSteps variant="headings">
141. Download and install the Codex app641. Download and install the Codex app
15 65
16 Download the Codex app for macOS or Windows. Choose the Intel build if you're using an Intel-based Mac.66 Download the Codex app for macOS or Windows. Choose the Intel build if you're using an Intel-based Mac.
17 67
1868 [Download for macOS (Apple Silicon)](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)[Download for macOS (Intel)](https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg) <CodexAppDownloadCta client:load className="mb-4" />
19
20 Need a different operating system?
21
22 [Download for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi)
23 69
70 <div class="text-sm">
24 [Get notified for Linux](https://openai.com/form/codex-app/)71 [Get notified for Linux](https://openai.com/form/codex-app/)
72 </div>
73
252. Open Codex and sign in742. Open Codex and sign in
26 75
27 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.76 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.
38 89
39 You can ask Codex anything about the project or your computer in general. Here are some examples:90 You can ask Codex anything about the project or your computer in general. Here are some examples:
40 91
4192- Tell me about this project <ExampleGallery>
4293- Build a classic Snake game in this repo. <ExampleTask
4394- Find and fix bugs in my codebase with minimal, high-confidence changes. client:load
95 id="intro"
96 prompt="Tell me about this project"
97 iconName="brain"
98 />
99 <ExampleTask
100 client:load
101 id="snake-game"
102 shortDescription="Build a classic Snake game in this repo."
103 prompt={[
104 "Build a classic Snake game in this repo.",
105 "",
106 "Scope & constraints:",
107 "- Implement ONLY the classic Snake loop: grid movement, growing snake, food spawn, score, game-over, restart.",
108 "- Reuse existing project tooling/frameworks; do NOT add new dependencies unless truly required.",
109 "- Keep UI minimal and consistent with the repo’s existing styles (no new design systems, no extra animations).",
110 "",
111 "Implementation plan:",
112 "1) Inspect the repo to find the right place to add a small interactive game (existing pages/routes/components).",
113 "2) Implement game state (snake positions, direction, food, score, tick timer) with deterministic, testable logic.",
114 "3) Render: simple grid + snake + food; support keyboard controls (arrow keys/WASD) and on-screen controls if mobile is present in the repo.",
115 "4) Add basic tests for the core game logic (movement, collisions, growth, food placement) if the repo has a test runner.",
116 "",
117 "Deliverables:",
118 "- A small set of files/changes with clear names.",
119 "- Short run instructions (how to start dev server + where to navigate).",
120 "- A brief checklist of what to manually verify (controls, pause/restart, boundaries).",
121 ].join("\n")}
122 iconName="gamepad"
123 />
124 <ExampleTask
125 client:load
126 id="fix-bugs"
127 shortDescription="Find and fix bugs in my codebase with minimal, high-confidence changes."
128 prompt={[
129 "Find and fix bugs in my codebase with minimal, high-confidence changes.",
130 "",
131 "Method (grounded + disciplined):",
132 "1) Reproduce: run tests/lint/build (or follow the existing repo scripts). If I provided an error, reproduce that exact failure.",
133 "2) Localize: identify the smallest set of files/lines involved (stack traces, failing tests, logs).",
134 "3) Fix: implement the minimal change that resolves the issue without refactors or unrelated cleanup.",
135 "4) Prove: add/update a focused test (or a tight repro) that fails before and passes after.",
136 "",
137 "Constraints:",
138 "- Do NOT invent errors or pretend to run commands you cannot run.",
139 "- No scope drift: no new features, no UI embellishments, no style overhauls.",
140 "- If information is missing, state what you can confirm from the repo and what remains unknown.",
141 "",
142 "Output:",
143 "- Summary (3–6 sentences max): what was broken, why, and the fix.",
144 "- Then ≤5 bullets: What changed, Where (paths), Evidence (tests/logs), Risks, Next steps.",
145 ].join("\n")}
146 iconName="search"
147 />
148 </ExampleGallery>
44 149
45 If you need more inspiration, explore [Codex use cases](https://developers.openai.com/codex/use-cases).150 If you need more inspiration, explore [Codex use cases](https://developers.openai.com/codex/use-cases).
46151 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices). If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).
152
153</WorkflowSteps>
47 154
48 [Learn more about the Codex app](https://developers.openai.com/codex/app)
49 155
156 </div>
157
158 <div slot="ide">
50Install the Codex extension for your IDE.159Install the Codex extension for your IDE.
51 160
161<WorkflowSteps variant="headings">
521. Install the Codex extension1621. Install the Codex extension
53 163
54 Download it for your editor:164 Download it for your editor:
66 178
67 Codex starts in Agent mode by default, which lets it read files, run commands, and write changes in your project directory.179 Codex starts in Agent mode by default, which lets it read files, run commands, and write changes in your project directory.
68 180
69181- Tell me about this project <ExampleGallery>
70182- Build a classic Snake game in this repo. <ExampleTask
71183- Find and fix bugs in my codebase with minimal, high-confidence changes. client:load
184 id="intro"
185 prompt="Tell me about this project"
186 iconName="brain"
187 />
188 <ExampleTask
189 client:load
190 id="snake-game"
191 shortDescription="Build a classic Snake game in this repo."
192 prompt={[
193 "Build a classic Snake game in this repo.",
194 "",
195 "Scope & constraints:",
196 "- Implement ONLY the classic Snake loop: grid movement, growing snake, food spawn, score, game-over, restart.",
197 "- Reuse existing project tooling/frameworks; do NOT add new dependencies unless truly required.",
198 "- Keep UI minimal and consistent with the repo’s existing styles (no new design systems, no extra animations).",
199 "",
200 "Implementation plan:",
201 "1) Inspect the repo to find the right place to add a small interactive game (existing pages/routes/components).",
202 "2) Implement game state (snake positions, direction, food, score, tick timer) with deterministic, testable logic.",
203 "3) Render: simple grid + snake + food; support keyboard controls (arrow keys/WASD) and on-screen controls if mobile is present in the repo.",
204 "4) Add basic tests for the core game logic (movement, collisions, growth, food placement) if the repo has a test runner.",
205 "",
206 "Deliverables:",
207 "- A small set of files/changes with clear names.",
208 "- Short run instructions (how to start dev server + where to navigate).",
209 "- A brief checklist of what to manually verify (controls, pause/restart, boundaries).",
210 ].join("\n")}
211 iconName="gamepad"
212 />
213 <ExampleTask
214 client:load
215 id="fix-bugs"
216 shortDescription="Find and fix bugs in my codebase with minimal, high-confidence changes."
217 prompt={[
218 "Find and fix bugs in my codebase with minimal, high-confidence changes.",
219 "",
220 "Method (grounded + disciplined):",
221 "1) Reproduce: run tests/lint/build (or follow the existing repo scripts). If I provided an error, reproduce that exact failure.",
222 "2) Localize: identify the smallest set of files/lines involved (stack traces, failing tests, logs).",
223 "3) Fix: implement the minimal change that resolves the issue without refactors or unrelated cleanup.",
224 "4) Prove: add/update a focused test (or a tight repro) that fails before and passes after.",
225 "",
226 "Constraints:",
227 "- Do NOT invent errors or pretend to run commands you cannot run.",
228 "- No scope drift: no new features, no UI embellishments, no style overhauls.",
229 "- If information is missing, state what you can confirm from the repo and what remains unknown.",
230 "",
231 "Output:",
232 "- Summary (3–6 sentences max): what was broken, why, and the fix.",
233 "- Then ≤5 bullets: What changed, Where (paths), Evidence (tests/logs), Risks, Next steps.",
234 ].join("\n")}
235 iconName="search"
236 />
237 </ExampleGallery>
238
724. Use Git checkpoints2394. Use Git checkpoints
73 240
74 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.241 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.
75242 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices). If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).
243
244 <CtaPillLink href="/codex/ide" label="Learn more about the Codex IDE extension" class="mt-8" />
245</WorkflowSteps>
246
76 247
77248 [Learn more about the Codex IDE extension](https://developers.openai.com/codex/ide) </div>
78 249
250 <div slot="cli">
79The Codex CLI is supported on macOS, Windows, and Linux.251The Codex CLI is supported on macOS, Windows, and Linux.
80 252
253<WorkflowSteps variant="headings">
811. Install the Codex CLI2541. Install the Codex CLI
82 255
83 Install with npm:256 Install with npm:
98 273
99 Once authenticated, you can ask Codex to perform tasks in the current directory.274 Once authenticated, you can ask Codex to perform tasks in the current directory.
100 275
101276- Tell me about this project <ExampleGallery>
102277- Build a classic Snake game in this repo. <ExampleTask
103278- Find and fix bugs in my codebase with minimal, high-confidence changes. client:load
279 id="intro"
280 prompt="Tell me about this project"
281 iconName="brain"
282 />
283 <ExampleTask
284 client:load
285 id="snake-game"
286 shortDescription="Build a classic Snake game in this repo."
287 prompt={[
288 "Build a classic Snake game in this repo.",
289 "",
290 "Scope & constraints:",
291 "- Implement ONLY the classic Snake loop: grid movement, growing snake, food spawn, score, game-over, restart.",
292 "- Reuse existing project tooling/frameworks; do NOT add new dependencies unless truly required.",
293 "- Keep UI minimal and consistent with the repo’s existing styles (no new design systems, no extra animations).",
294 "",
295 "Implementation plan:",
296 "1) Inspect the repo to find the right place to add a small interactive game (existing pages/routes/components).",
297 "2) Implement game state (snake positions, direction, food, score, tick timer) with deterministic, testable logic.",
298 "3) Render: simple grid + snake + food; support keyboard controls (arrow keys/WASD) and on-screen controls if mobile is present in the repo.",
299 "4) Add basic tests for the core game logic (movement, collisions, growth, food placement) if the repo has a test runner.",
300 "",
301 "Deliverables:",
302 "- A small set of files/changes with clear names.",
303 "- Short run instructions (how to start dev server + where to navigate).",
304 "- A brief checklist of what to manually verify (controls, pause/restart, boundaries).",
305 ].join("\n")}
306 iconName="gamepad"
307 />
308 <ExampleTask
309 client:load
310 id="fix-bugs"
311 shortDescription="Find and fix bugs in my codebase with minimal, high-confidence changes."
312 prompt={[
313 "Find and fix bugs in my codebase with minimal, high-confidence changes.",
314 "",
315 "Method (grounded + disciplined):",
316 "1) Reproduce: run tests/lint/build (or follow the existing repo scripts). If I provided an error, reproduce that exact failure.",
317 "2) Localize: identify the smallest set of files/lines involved (stack traces, failing tests, logs).",
318 "3) Fix: implement the minimal change that resolves the issue without refactors or unrelated cleanup.",
319 "4) Prove: add/update a focused test (or a tight repro) that fails before and passes after.",
320 "",
321 "Constraints:",
322 "- Do NOT invent errors or pretend to run commands you cannot run.",
323 "- No scope drift: no new features, no UI embellishments, no style overhauls.",
324 "- If information is missing, state what you can confirm from the repo and what remains unknown.",
325 "",
326 "Output:",
327 "- Summary (3–6 sentences max): what was broken, why, and the fix.",
328 "- Then ≤5 bullets: What changed, Where (paths), Evidence (tests/logs), Risks, Next steps.",
329 ].join("\n")}
330 iconName="search"
331 />
332 </ExampleGallery>
333
1044. Use Git checkpoints3344. Use Git checkpoints
105 335
106 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.336 Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed.
107337 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices). If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).
338</WorkflowSteps>
108 339
109340[Learn more about the Codex CLI](https://developers.openai.com/codex/cli) <CtaPillLink href="/codex/cli" label="Learn more about the Codex CLI" class="mt-8" />
110 341
342 </div>
343
344 <div slot="cloud">
111Use Codex in the cloud at [chatgpt.com/codex](https://chatgpt.com/codex).345Use Codex in the cloud at [chatgpt.com/codex](https://chatgpt.com/codex).
112 346
347<WorkflowSteps variant="headings">
1131. Open Codex in your browser3481. Open Codex in your browser
114 349
115 Go to [chatgpt.com/codex](https://chatgpt.com/codex). You can also delegate a task to Codex by tagging `@codex` in a GitHub pull request comment (requires signing in to ChatGPT).350 Go to [chatgpt.com/codex](https://chatgpt.com/codex). You can also delegate a task to Codex by tagging `@codex` in a GitHub pull request comment (requires signing in to ChatGPT).
120 357
121 Once your environment is ready, launch coding tasks from the [Codex interface](https://chatgpt.com/codex). You can monitor progress in real time by viewing logs, or let tasks run in the background.358 Once your environment is ready, launch coding tasks from the [Codex interface](https://chatgpt.com/codex). You can monitor progress in real time by viewing logs, or let tasks run in the background.
122 359
123360- Tell me about this project <ExampleGallery>
124361- Explain the top failure modes of my application's architecture. <ExampleTask
125362- Find and fix bugs in my codebase with minimal, high-confidence changes. client:load
363 id="intro"
364 prompt="Tell me about this project"
365 iconName="brain"
366 />
367 <ExampleTask
368 client:load
369 id="architecture-failure-modes"
370 shortDescription="Explain the top failure modes of my application's architecture."
371 prompt={[
372 "Explain the top failure modes of my application's architecture.",
373 "",
374 "Approach:",
375 "- Derive the architecture from repo evidence (services, DBs, queues, network calls, critical paths).",
376 "- Identify realistic failure modes (availability, data loss, latency, scaling, consistency, security, dependency outages).",
377 "",
378 "Output:",
379 "- 1 short overview paragraph.",
380 "- Then ≤5 bullets: Failure mode, Trigger, Symptoms, Detection, Mitigation.",
381 "- If key architecture details are missing, state what you inferred vs. what you confirmed.",
382 ].join("\n")}
383 iconName="brain"
384 />
385 <ExampleTask
386 client:load
387 id="fix-bugs"
388 shortDescription="Find and fix bugs in my codebase with minimal, high-confidence changes."
389 prompt={[
390 "Find and fix bugs in my codebase with minimal, high-confidence changes.",
391 "",
392 "Method (grounded + disciplined):",
393 "1) Reproduce: run tests/lint/build (or follow the existing repo scripts). If I provided an error, reproduce that exact failure.",
394 "2) Localize: identify the smallest set of files/lines involved (stack traces, failing tests, logs).",
395 "3) Fix: implement the minimal change that resolves the issue without refactors or unrelated cleanup.",
396 "4) Prove: add/update a focused test (or a tight repro) that fails before and passes after.",
397 "",
398 "Constraints:",
399 "- Do NOT invent errors or pretend to run commands you cannot run.",
400 "- No scope drift: no new features, no UI embellishments, no style overhauls.",
401 "- If information is missing, state what you can confirm from the repo and what remains unknown.",
402 "",
403 "Output:",
404 "- Summary (3–6 sentences max): what was broken, why, and the fix.",
405 "- Then ≤5 bullets: What changed, Where (paths), Evidence (tests/logs), Risks, Next steps.",
406 ].join("\n")}
407 iconName="search"
408 />
409 </ExampleGallery>
410
1264. Review changes and create a pull request4114. Review changes and create a pull request
127 412
128 When a task completes, review the proposed changes in the diff view. You can iterate on the results or create a pull request directly in your GitHub repository.413 When a task completes, review the proposed changes in the diff view. You can iterate on the results or create a pull request directly in your GitHub repository.
134 git checkout <branch-name>419 git checkout <branch-name>
135 ```420 ```
136 421
137422 [Learn more about Codex cloud](https://developers.openai.com/codex/cloud) <CtaPillLink href="/codex/cloud" label="Learn more about Codex cloud" class="mt-8" />
423</WorkflowSteps>
424
425 </div>
426</Tabs>
427
428<div class="h-6" aria-hidden="true"></div>
429
430## Next steps
431
432[<IconItem title="Learn more about the Codex app" className="mt-2">
433 <span slot="icon">
434 <OpenBook />
435 </span>
436 Use the Codex app to work with your local projects.
437 </IconItem>](https://developers.openai.com/codex/app)
438
439[<IconItem title="Migrate to Codex" className="mt-2">
440 <span slot="icon">
441 <CompareArrows />
442 </span>
443 Move supported instruction files, MCP server configuration, skills, and
444 subagents into Codex.
445 </IconItem>](https://developers.openai.com/codex/migrate)