Codex Training Hub

Install Codex on your chosen surface before you dive into the workshop.

1. Choose an install method:
   • Homebrew: brew install --cask codex
   • npm: npm i -g @openai/codex
   • Manual download: grab the latest binary from https://github.com/openai/codex/releases and add it to your PATH.

Confirm you are on the expected release before continuing.

1. Run codex --version; expect at least codex-cli 0.53.0 (baseline when this workshop was written—update if you're behind).

Make sure Codex is signed in with the same ChatGPT account you use on the web.

1. Run codex login.
2. Your browser opens to complete sign-in; approve and return to the terminal once it confirms success.

Pull down the sample repository you'll use throughout the exercises.

1. Clone the repo with git clone https://github.com/openai/agents.md.git agents-md-repository (or download the ZIP from https://github.com/openai/agents.md and rename the folder to agents-md-repository).

2. Open a separate terminal for the dev server and launch it:

   cd agents-md-repository
   npm install
   npm run dev
   

3. Leave that terminal running; you'll use a different shell window for Codex commands.

Tune Codex to the low reasoning before prompting. When you finish testing.

1. Run codex, type /model, highlight gpt-5.3-codex, press Enter, then select the Low reasoning.

Practice asking Codex for analysis without editing files.

1. With the low reasoning model active, ask: Explain what this repository is doing in short.

Return to the recommended default model before continuing.

1. Start or resume a session, run /model, and pick gpt-5.3-codex, then confirm Medium reasoning—best blend of depth and quality.
2. Keep this as the default before moving on so follow-up tasks use the best model.

Run the following prompt to generate a visualization asset for the repo.

1. Start a Codex session.

2. Send:

   Create a small HTML page in assets.html that shows how files are related to each others. I want a nice looking assets.html that explain those concepts.
   

3. Review the proposed asset to ensure the relationships are accurate before applying the patch.

Have Codex modify the project by applying a patch.

1. Start a new task and send:

   Can you implement, next to the "Explore Examples" and "View on Github" buttons a button to download and another one to copy the page as markdown?
   

2. Review the diff Codex proposes before applying.

Practice attaching visuals and following up with styling tweaks.

1. Capture a screenshot of the Agents.md textarea (top-right of the app).
2. Paste the image directly (ctrl+v on Mac or ctrl+maj+v on Windows) or reference it with @agents-textarea.png, then add: Make inline background code chips orange.
3. Verify Codex updates the UI styling based on the screenshot.

Learn how to jump back into an existing thread.

1. Run codex resume.
2. Search for the task titled “chip code/background orange”.
3. Reopen it and ask, “actually make that green”.
4. Confirm Codex replays the context and updates the color.

Note: you can run codex resume <session_id> directly at the end of a session, as shown when you exit the CLI.

Add the OpenAI developer documentation MCP server so Codex can fetch up-to-date API and SDK details while you work.

1. Register the server:

   codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
   

2. Verify registration:

   codex mcp list
   codex mcp get openaiDeveloperDocs
   

3. Add the global guidance (create the file if it doesn't exist):

   mkdir -p ~/.codex
   echo "When questions involve OpenAI APIs, SDKs, Codex, or other OpenAI products, use the OpenAI developer documentation MCP server as the source of truth and avoid web search unless the MCP server cannot answer." >> ~/.codex/AGENTS.md
   

Verify Codex can reach the OpenAI developer documentation MCP server before you rely on it.

1. In a Codex chat, run /mcp to confirm the server connection is healthy and openaiDeveloperDocs appears.
2. If it fails, re-check the config.toml entry or the CLI flags from https://developers.openai.com/codex/mcp.

Practice using the OpenAI Docs MCP to answer a Voice API question.

1. Start a new chat and send:

   How do I implement the OpenAI Voice API over WebSockets? Share a minimal example and link to the relevant doc.
   

Use search to jump back to prior work.

1. Run:

   codex --search "Add a small 'Latest News' footer box that links to a current article about Next.js 15. Include a date and source."
   

   

2. Pick the matching task from the results and reopen it if you need the history.

Automate test generation prompts for future sessions.

1. Save your standard ask:

   1. Create a directory at ~/.codex/prompts to store saved commands (make it if it does not exist).

   2. Create ~/.codex/prompts/add-tests.md containing:

      Generate unit tests for the touched files. Use the project’s existing test runner and conventions. Keep diffs minimal and runnable locally.
      

2. Resume the “Latest News” task (use codex resume and type to search) and run /add-tests to invoke the new command.

Practice adding local context to Codex chats.

1. Type @ and choose a file to attach, or reference it directly such as @src/app/page.tsx.
2. Rely on @file when you need context.

Use /review to inspect a small regression you introduce on purpose.

1. In your repo, open pages/index.tsx and scroll to the getStaticProps loop that builds contributorsByRepo. Inside that loop, right before the contributorsByRepo[fullName] = { avatars, total } assignment, add one line:

   total++;
   

   Leave everything else unchanged so the counter quietly creeps up by one.

2. Start a fresh Codex CLI session in the repo and run:

   /review
   

   Choose Review against a base branch and select at main.

3. Let Codex run the review and read the findings that flag the inflated total.

Bookmark the go-to references for deeper Codex work.

1. Open the product hub at https://developers.openai.com/codex for docs, demos, and release notes.
2. Explore the Codex SDK: https://developers.openai.com/codex/sdk.
3. Review the GitHub Action wiring guide: https://developers.openai.com/codex/sdk#github-action.
4. Track updates via the changelog: https://developers.openai.com/codex/changelog.