quickstart diff — Spybara

quickstart.md +324 −24

Details

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;

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 };

31 if (!shouldPreferApp()) return;

33 window.__tabsPreferred = window.__tabsPreferred || {};

34 window.__tabsPreferred.setup = "app";

35})();

36`}

37/>

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

~~20 Need a different operating system?~~

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

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 project~~92 <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

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

~~69- Tell me about this project~~181 <ExampleGallery>

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

~~71- 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

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.

~~75 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

76 247

~~77 [Learn more about the Codex IDE extension](https://developers.openai.com/codex/ide)~~248 </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

101- Tell me about this project276 <ExampleGallery>

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

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

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.

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

108 339

109[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" />

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

123- Tell me about this project360 <ExampleGallery>

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

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

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

137 [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)

quickstart.md Codex Docs, 2026-04-29 00:50 UTC → 2026-05-07 20:02 UTC