Codex Training Hub

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

1. Download and install the Codex desktop app.
2. Open the app from your Applications folder.
3. Confirm the app launches to the onboarding screen.

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

1. In the Codex app, click Continue with ChatGPT.
2. Complete the browser sign-in flow with your ChatGPT account.
3. Return to the app and confirm you are signed in.

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.

4. In Codex, choose Select your project and pick the agents-md-repository folder so the chat input becomes available.

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

1. In the Codex app, open the model picker in the chat composer.
2. Choose gpt-5.4 and set the reasoning preset to Low before sending the next prompt.

Practice asking Codex for analysis without editing files.

1. In the project chat, ask: Explain what this repository is doing in short.
2. Send the prompt and confirm Codex responds in the chat thread.

Return to the recommended default model before continuing.

1. Open the model picker in the Codex app and select gpt-5.4, then set Medium reasoning.
2. Continue subsequent tasks with this model selected so everything runs on the recommended setup.

Run the following prompt to generate a visualization asset for the repo. If you have not completed the Get the reference repo task yet, do that first so you are working inside agents-md-repository.

1. Open or switch the Codex app project to agents-md-repository.

2. Start a new project chat in that project.

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

4. Review the proposed assets.html changes in the app diff view and verify the relationships before applying.

Have Codex modify the project by applying a patch.

1. Start a new task in the Codex app 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 proposed patch in the app diff before applying changes.

Practice attaching visuals and following up with styling tweaks.

1. Capture a screenshot of the Agents.md textarea (top-right of the app).
2. In the Codex app project chat, attach the image (or paste it) and add: Make inline background code chips orange.
3. Confirm Codex updates the UI styling based on the screenshot.

Learn how to jump back into an existing thread.

1. In the Codex app, open the conversation history / recent chats list for the current project.
2. Reopen the prior task you want to continue.
3. Ask the follow-up prompt (for example, “actually make that green”) and confirm Codex continues with the previous context.

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

1. Open ~/.codex/config.toml and add:

   [mcp_servers.openaiDeveloperDocs]
   url = "https://developers.openai.com/mcp"
   

2. Open ~/.codex/AGENTS.md (create it if needed) and add:

   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.
   

3. Restart the Codex app (or start a new project chat after restart) so the config is reloaded.

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

1. In a Codex app project chat, run /mcp to confirm the server connection is healthy and openaiDeveloperDocs appears.
2. If it fails, re-check ~/.codex/config.toml and the MCP setup instructions from https://developers.openai.com/codex/mcp, then restart the app and try again.

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

1. Start a new project chat in the Codex app.

2. Send:

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

Learn how to ask Codex for current information from the web.

1. Open a new Codex app chat for this project.
2. Ask Codex to add the “Latest News” footer box and explicitly say to use web search and include the article date and source.
3. Confirm the response uses current web results before making the edit.

Use Codex to add tests for an existing change and validate the result.

1. In the Codex app, reopen the “Latest News” task thread (or any coding thread in the same project).
2. Ask Codex to add or update tests for the touched files, keep the diff minimal, and run the appropriate validation command after the change.
3. Review the new tests and confirm Codex ran a repo check after editing.

Practice adding local context to Codex chats.

1. In the Codex app project chat, use the file/attachment picker (or drag and drop) to add a file for context.
2. Share a specific file such as src/app/page.tsx, then ask a question about that file.
3. Confirm Codex responds using the attached file 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. In the Codex app project chat, run /review, choose Review against a base branch, and select main.

3. Read the findings that flag the inflated total, then apply the suggested fix (remove the extra total++) and rerun if desired.

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.

Ask Codex about its own feature support while inside the Codex repo.

1. Clone the public repo: git clone https://github.com/openai/codex.git.
2. In the Codex app, select the codex folder as your project.
3. Start a new project chat and send this prompt Looking into codex-rs, tell me how much context is allocated to MCP tool call when we use Codex? As a reminder, you're in the Codex repo so you have access on how Codex is built..

Skills are reusable workflow packs. On the default setup, personal skills live in ~/.codex/skills, and anything you place there is available across the CLI, IDE, and app. If you use a custom CODEX_HOME, use $CODEX_HOME/skills instead.

1. Open the Skills & Apps sidebar.

   

2. Browse or search the list for any skills that look relevant to your work.

3. Ask Codex:

   Explain what the $skill-creator skill does and when I should use it.
   

4. Remember that any skill copied into ~/.codex/skills on the default setup should also appear here, not just in the terminal-based surfaces.

Create a simple skill named change-brief. If you want a team skill that travels with the current repo, put it under .codex/skills/ in the repo. For this exercise, create a personal global skill under ~/.codex/skills/change-brief on the default setup, or $CODEX_HOME/skills/change-brief if you use a custom CODEX_HOME, so it becomes available across repos and surfaces.

Start by asking Codex:

Use the $skill-creator skill to create a personal skill named change-brief under ~/.codex/skills/change-brief. The skill should inspect the current git diff or a pasted snippet and produce exactly four sections: What changed, Possible risks, What to test, and Follow-up questions. Keep it concise and deterministic. If a section has nothing to report, say "None."

This is what the generated skill folder should look like:

The skill should always produce these four sections:

• What changed
• Possible risks
• What to test
• Follow-up questions

If a section has nothing to report, it should say None..

This is what the skill output should look like:

1. Open Skills & Apps and locate skill-creator, then use the shared prompt above to create change-brief.

2. If the repo has no current diff, make a tiny one-line change so the skill has something to inspect.

3. Invoke the new skill by either selecting it from the Skills & Apps sidebar or typing $ and choosing change-brief.

4. Run one of these simple prompts:

   Run $change-brief
   

   or:

   Use $change-brief on the current diff
   

5. If the skill does not appear right away, restart the app project session and try again.

This workshop uses the built-in agent roster default, worker, explorer, and monitor. Start with the built-ins before you customize any agent roles or config files.

Ask Codex:

Use multiple explorer and monitor agents to investigate this codebase. Plan how you will distribute the work before you start.

1. Run the prompt above in the app chat.

2. If multi-agent behavior is not available in your current setup, enable it in ~/.codex/config.toml, restart the app project session, and rerun the prompt.

3. This surface may use agents under the hood, but it does not expose /agent.

4. The screenshot below is a CLI example of what agent visibility looks like there.

   

Advanced configuration: once the built-in flow works, you can customize roles and role-specific config files. For example, you might add a reviewer role like this:

[agents.reviewer]
description = "High-rigor reviewer for risky changes."
config_file = "./agents/reviewer.toml"

# ./agents/reviewer.toml
model = "gpt-5.4"
model_reasoning_effort = "high"
developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability."

You can also override the built-in explorer role with a dedicated config file:

[agents.explorer]
description = "Fast codebase explorer for read-heavy tasks."
config_file = "./agents/custom-explorer.toml"

# ./agents/custom-explorer.toml
model = "gpt-5.3-codex-spark"
sandbox_mode = "read-only"

Agents do not all have to use the same model. You can override an existing agent or add a new one with a role-specific config file.

For example, add a new reviewer agent in ~/.codex/config.toml like this:

[agents.reviewer]
description = "High-rigor reviewer for risky changes."
config_file = "./agents/reviewer.toml"

Then define the role-specific settings in ./agents/reviewer.toml:

# ./agents/reviewer.toml
model = "gpt-5.4"
model_reasoning_effort = "high"
developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability. Report any issues found in the code review grouped by categories"

Restart Codex after saving the config change so the updated agent definitions are loaded.

1. After you've added the reviewer example above to your config files, restart Codex.
2. Ask Codex to use your reviewer agent for a risky change and confirm that the custom role is available, with e.g: Using the reviewer subagent, make a review of the uncommitted changes

Worktrees are the safest way to keep parallel changes isolated. The app exposes this directly through Move to worktree (on the top-right of the Codex app), while the CLI and IDE rely on standard Git worktree commands. For further reading on the Git workflow itself, see git worktree.

1. Open the repo as a project in the app.

2. Start a task with uncommitted changes, then use the app's Move to worktree UI.

   

3. In the Check out locally field, choose an existing local branch to switch your current checkout to, such as main.

4. Confirm that the current branch and all uncommitted changes are being moved out of your current checkout and into a new local worktree that Codex creates on disk for that thread.

5. Continue the move, then open or switch into the new worktree-backed thread in the app.

6. If you want to understand the underlying Git workflow in more detail, read git worktree.

Strong warning: memories are currently experimental. Turn them on only if you are comfortable trying an in-progress feature and having Codex build a local memory workspace under ~/.codex/memories. Do not use them for secrets. On the default setup, the memory root is ~/.codex/memories. If you use a custom CODEX_HOME, the path is $CODEX_HOME/memories.

Memories work like this:

• In the background, sessions are consolidated into a local (as in, in your computer) memory workspace.
• Memories then influence future sessions by injecting a compact summary available for lookup.
• Codex can better carry forward durable preferences, recurring project context, and prior decisions across sessions.

Placeholder example of what ~/.codex/memories can look like after the feature has been enabled for a while:

~/.codex/memories/
  memory_summary.md
  MEMORY.md
  raw_memories.md
  rollout_summaries/
    2026-02-17T21-23-02-example-thread.md
    2026-02-19T09-11-48-example-thread.md
  skills/
    <skill-name>/
      SKILL.md
      ...

Filenames will vary. MEMORY.md, memory_summary.md, and skills/ are higher-level consolidation artifacts, so they may be absent or removed when the memory workspace has little or no retained content yet.

Example contents from ~/.codex/memories/memory_summary.md after memories have been enabled for a while:

## User Profile
This user uses Codex across the CLI, IDE, and app for hands-on engineering work. They prefer concise, actionable answers, like concrete test steps, and often return to the same repositories over multiple sessions.

The steps below turn memories on. Keep the warning above in mind before you enable them.

1. Open ~/.codex/config.toml and enable memories:

   [features]
   memories = true
   

2. Restart the app project session.

3. Use Codex normally for a while. Memories run asynchronously in the background, so do not expect them to affect the next prompt immediately.

4. After you have used Codex with memories enabled for a while, inspect ~/.codex/memories/ in a terminal or Finder and open memory_summary.md to compare what you see with the examples above.