quickstart.md +336 −30
1# Quickstart1# Quickstart
2 2
33ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Using Codex with your ChatGPT subscription gives you access to the latest Codex models and features.Every ChatGPT plan includes Codex.
4 4
5You can also use Codex with API credits by signing in with an OpenAI API key.5You can also use Codex with API credits by signing in with an OpenAI API key.
6 6
7For a limited time, **try Codex for free in ChatGPT Free and Go**, or enjoy
8**2x Codex rate limits** with Plus, Pro, Business and Enterprise
9subscriptions.
10
11## Setup7## Setup
12 8
139The Codex app is available on macOS (Apple Silicon).<script
1410 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">
58The Codex app is available on macOS and Windows.
59
60Most Codex app features are available on both platforms. Platform-specific
61exceptions are noted in the relevant docs.
62
63<WorkflowSteps variant="headings">
151. Download and install the Codex app641. Download and install the Codex app
16 65
1766 The Codex app is currently only available for macOS. Download the Codex app for macOS or Windows. Choose the Intel build if you're using an Intel-based Mac.
67
68 <CodexAppDownloadCta client:load className="mb-4" />
18 69
1970 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg) <div class="text-sm">
71 [Get notified for Linux](https://openai.com/form/codex-app/)
72 </div>
20 73
21 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)
222. Open Codex and sign in742. Open Codex and sign in
23 75
24 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.
36 89
37 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:
38 91
3992- Tell me about this project <ExampleGallery>
4093- Build a classic Snake game in this repo. <ExampleTask
4194- Find and fix bugs in my codebase with minimal, high-confidence changes. client:load
4295 id="intro"
4396 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore). prompt="Tell me about this project"
4497 iconName="brain"
4598 [Learn more about the Codex app](https://developers.openai.com/codex/app) />
4699 <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>
149
150 If you need more inspiration, explore [Codex use cases](https://developers.openai.com/codex/use-cases).
151 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).
152
153</WorkflowSteps>
154
155
156 </div>
157
158 <div slot="ide">
47Install the Codex extension for your IDE.159Install the Codex extension for your IDE.
48 160
161<WorkflowSteps variant="headings">
491. Install the Codex extension1621. Install the Codex extension
50 163
51 Download it for your editor:164 Download it for your editor:
63 178
64 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.
65 180
66181- Tell me about this project <ExampleGallery>
67182- Build a classic Snake game in this repo. <ExampleTask
68183- 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
694. Use Git checkpoints2394. Use Git checkpoints
70 240
71 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.
242 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
72 247
73248 [Learn more about the Codex IDE extension](https://developers.openai.com/codex/ide) </div>
74 249
250 <div slot="cli">
75The Codex CLI is supported on macOS, Windows, and Linux.251The Codex CLI is supported on macOS, Windows, and Linux.
76 252
253<WorkflowSteps variant="headings">
771. Install the Codex CLI2541. Install the Codex CLI
78 255
79 Install with npm:256 Install with npm:
94 273
95 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.
96 275
97276- Tell me about this project <ExampleGallery>
98277- Build a classic Snake game in this repo. <ExampleTask
99278- 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
1004. Use Git checkpoints3344. Use Git checkpoints
101 335
102 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.
337 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).
338</WorkflowSteps>
103 339
104340[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" />
105 341
342 </div>
343
344 <div slot="cloud">
106Use 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).
107 346
347<WorkflowSteps variant="headings">
1081. Open Codex in your browser3481. Open Codex in your browser
109 349
110 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).
115 357
116 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.
117 359
118360- Tell me about this project <ExampleGallery>
119361- Explain the top failure modes of my application's architecture. <ExampleTask
120362- 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
1214. Review changes and create a pull request4114. Review changes and create a pull request
122 412
123 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.
129 git checkout <branch-name>419 git checkout <branch-name>
130 ```420 ```
131 421
132422 [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)