quickstart.md Codex Docs, 2026-03-11 00:31 UTC → 2026-05-07 20:02 UTC

1# Quickstart1# Quickstart

2 2 

3ChatGPT 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.3Every 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 

13The Codex app is available on macOS (Apple Silicon).9<script

14 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">

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 

17 Download the Codex app for Windows or macOS.66 Download the Codex app for macOS or Windows. Choose the Intel build if you're using an Intel-based Mac.

18 67 

19 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)68 <CodexAppDownloadCta client:load className="mb-4" />

20 69 

70 <div class="text-sm">

21 [Get notified for Linux](https://openai.com/form/codex-app/)71 [Get notified for Linux](https://openai.com/form/codex-app/)

72 </div>

73 

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.

35 89 

36 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:

37 91 

38- Tell me about this project92 <ExampleGallery>

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

40- Find and fix bugs in my codebase with minimal, high-confidence changes.94 client:load

41 95 id="intro"

42 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).96 prompt="Tell me about this project"

43 If you’re new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).97 iconName="brain"

44 98 />

45 [Learn more about the Codex app](https://developers.openai.com/codex/app)99 <ExampleTask

46 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

66- Tell me about this project181 <ExampleGallery>

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

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

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.

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

243

244 <CtaPillLink href="/codex/ide" label="Learn more about the Codex IDE extension" class="mt-8" />

245</WorkflowSteps>

246 

73 247 

74 [Learn more about the Codex IDE extension](https://developers.openai.com/codex/ide)248 </div>

75 249 

250 <div slot="cli">

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

77 252 

253<WorkflowSteps variant="headings">

781. Install the Codex CLI2541. Install the Codex CLI

79 255 

80 Install with npm:256 Install with npm:

95 273 

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

97 275 

98- Tell me about this project276 <ExampleGallery>

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

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

1014. Use Git checkpoints3344. Use Git checkpoints

102 335 

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

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

105 339 

106[Learn more about the Codex CLI](https://developers.openai.com/codex/cli)340 <CtaPillLink href="/codex/cli" label="Learn more about the Codex CLI" class="mt-8" />

107 341 

342 </div>

343 

344 <div slot="cloud">

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

109 346 

347<WorkflowSteps variant="headings">

1101. Open Codex in your browser3481. Open Codex in your browser

111 349 

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

117 357 

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

119 359 

120- Tell me about this project360 <ExampleGallery>

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

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

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

124 412 

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

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

132 ```420 ```

133 421 

134 [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>

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)