quickstart.md Codex Docs, 2026-05-02 06:45 UTC → 2026-05-14 07:00 UTC

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 

18 [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)68 <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 

41- Tell me about this project92 <ExampleGallery>

42- Build a classic Snake game in this repo.93 <ExampleTask

43- Find and fix bugs in my codebase with minimal, high-confidence changes.94 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).

46 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).151 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

152 

153</WorkflowSteps>

47 154 

155 

156 </div>

157 

158 <div slot="ide">

48Install the Codex extension for your IDE.159Install the Codex extension for your IDE.

49 160 

161<WorkflowSteps variant="headings">

501. Install the Codex extension1621. Install the Codex extension

51 163 

52 Download it for your editor:164 Download it for your editor:

64 178 

65 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.

66 180

67- Tell me about this project181 <ExampleGallery>

68- Build a classic Snake game in this repo.182 <ExampleTask

69- Find and fix bugs in my codebase with minimal, high-confidence changes.183 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 

704. Use Git checkpoints2394. Use Git checkpoints

71 240 

72 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.

73 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).242 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

74 243

75 [Learn more about the Codex IDE extension](https://developers.openai.com/codex/ide)244 <CtaPillLink href="/codex/ide" label="Learn more about the Codex IDE extension" class="mt-8" />

245</WorkflowSteps>

76 246 

247 

248 </div>

249 

250 <div slot="cli">

77The Codex CLI is supported on macOS, Windows, and Linux.251The Codex CLI is supported on macOS, Windows, and Linux.

78 252 

253<WorkflowSteps variant="headings">

791. Install the Codex CLI2541. Install the Codex CLI

80 255 

81 Install with npm:256 Install with npm:

96 273 

97 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.

98 275 

99- Tell me about this project276 <ExampleGallery>

100- Build a classic Snake game in this repo.277 <ExampleTask

101- Find and fix bugs in my codebase with minimal, high-confidence changes.278 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 

1024. Use Git checkpoints3344. Use Git checkpoints

103 335 

104 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.

105 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).337 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

338</WorkflowSteps>

339 

340 <CtaPillLink href="/codex/cli" label="Learn more about the Codex CLI" class="mt-8" />

106 341 

107[Learn more about the Codex CLI](https://developers.openai.com/codex/cli)342 </div>

108 343 

344 <div slot="cloud">

109Use 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).

110 346 

347<WorkflowSteps variant="headings">

1111. Open Codex in your browser3481. Open Codex in your browser

112 349 

113 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).

118 357 

119 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.

120 359 

121- Tell me about this project360 <ExampleGallery>

122- Explain the top failure modes of my application's architecture.361 <ExampleTask

123- Find and fix bugs in my codebase with minimal, high-confidence changes.362 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 

1244. Review changes and create a pull request4114. Review changes and create a pull request

125 412 

126 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.

132 git checkout <branch-name>419 git checkout <branch-name>

133 ```420 ```

134 421 

135 [Learn more about Codex cloud](https://developers.openai.com/codex/cloud)422 <CtaPillLink href="/codex/cloud" label="Learn more about Codex cloud" class="mt-8" />

423</WorkflowSteps>

136 424 

137## Next steps425 </div>

426</Tabs>

138 427 

139[Learn more about the Codex app428<div class="h-6" aria-hidden="true"></div>

140 429 

141Use the Codex app to work with your local projects.](https://developers.openai.com/codex/app)430## Next steps

142[Migrate to Codex

143 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>

144 Move supported instruction files, MCP server configuration, skills, and443 Move supported instruction files, MCP server configuration, skills, and

145subagents into Codex.](https://developers.openai.com/codex/migrate)444 subagents into Codex.

445 </IconItem>](https://developers.openai.com/codex/migrate)