OpenAI Codex: A Step-by-Step Guide With 3 Practical Examples

TL;DR

• OpenAI Codex is a cloud-based software engineering agent available inside ChatGPT (Plus, Pro, Team, and Enterprise plans)

• Connect Codex to a GitHub repo, then assign it tasks: fixing bugs, applying patches, generating tests, or explaining code

• Each task runs in an isolated sandbox; Codex opens a pull request you review before merging

• Use an AGENTS.md file to define coding conventions that Codex will follow on every task

• Codex also runs in the terminal via the Codex CLI and as a VS Code extension

What Is OpenAI’s Codex?

OpenAI Codex is a cloud-based software engineering agent that can write and edit code, run tests, fix bugs, and even propose pull requests. Each task is executed in its own sandboxed environment.

Codex is powered by OpenAI's latest frontier models, and it is built for safety, testability, and developer productivity. You can guide Codex using AGENTS.md files or interact with it directly in ChatGPT’s sidebar.

With Codex CLI, you can bring these capabilities directly into your terminal as well.

Codex access options at a glance:

Setting Up OpenAI's Codex

Setting up Codex takes just a few minutes. Here’s a step-by-step walkthrough to get you started.

Step 1: Locating the Codex tool

Start by logging in to ChatGPT. On the left side toolbar, look for Codex. At launch, Codex rolled out to ChatGPT Pro, Business, and Enterprise users. It is now included across all plans (although Free and Go access are very limited).

Step 2: Getting started with Codex

Click on Codex, and it will take you to another tab for initial setup. Click on “Get Started” and follow the authentication procedure as shown in the next step.

Step 3: Multi-factor authentication

Click “Set up MFA to continue” and scan the QR code using your favorite authentication app (like Google Authenticator or Authy). Enter the code to verify and you’re done!

Step 4: Connect to GitHub

Once multi-factor authentication is done, we connect Codex to GitHub.

Step 4.1: Authorize the GitHub connector

“Connect to GitHub” will take you to a pop-up to authorize the GitHub connector. Read through the pop-up and Authorize.

Step 4.2: Adding your GitHub account

Once GitHub is connected, we need to add our account. Under the GitHub organization tab, select “Add a GitHub account.” 

This will take you to another pop-up to “Install and Authorize.” Click to authorize, and all your repositories will appear on the ChatGPT interface. You can also authorize only selected repositories.

Step 4.3: Creating an environment

Choose the repository you want to work on and click “Create environment.”

This will take you to “Data Controls.” Codex is still in active development, and you may see an optional prompt to allow your data to be used for model improvement. You can turn this off and proceed.

Now your environment is ready to be explored. Codex allows users to start tasks in parallel with pre-picked tasks.

Simply click on “Start tasks” or choose tasks according to your requirements. This will take you to an interface where you can ask questions or ask the agent to code a feature for you.

Once all tasks are ready, select the task you’d like to work on, or work on multiple tasks in parallel.

Step 5: AGENTS.md file (optional)

The AGENTS.md file is a special configuration file introduced by OpenAI for use with the Codex platform, specifically designed to help guide AI agents as they work within your codebase. You can think of it as a developer manual for AI teammates, much similar to a README.md, but focused on instructions for autonomous agents. Here is an example AGENTS.md file:

# AGENTS.md

## Code Style
- Use Black for Python formatting.
- Avoid abbreviations in variable names.

## Testing
- Run pytest tests/ before finalizing a PR.
- All commits must pass lint checks via flake8.

## PR Instructions
- Title format: [Fix] Short description
- Include a one-line summary and a "Testing Done" section

When Codex runs a task on your codebase, it:

• Searches for AGENTS.md files whose scope includes the file(s) it is modifying.
• Applies the instructions in those files to format, test, and document its changes.
• Prioritizes deeper nested instructions when multiple files apply (like a cascading config).

For a broader look at building systems that take action across tools and APIs, see our OpenAI Agents SDK tutorial.

OpenAI’s Codex: Three Practical Examples

Let’s explore how Codex can help you in real-world development using three examples I ran on a repository.

Example 1: Basic fixes and typos

Codex sometimes breaks a single request into subtasks, like fixing typos, improving a README, or writing tests, all within the same workspace.

You can start a new task within an existing task based on the initial review, request changes to the existing codebase, or ask questions via the textbox. To extend the task or fix something new, click “Code” and start a new subtask directly.

Once satisfied with the changes, click “Push,” which will create a new pull request. After a few seconds, you can click “View Pull Request” to access the pull request and merge it into the main.

Example 2: Codebase explanation

Next, I used Codex for a non-editing task: exploring the codebase and asking what I could do next. This is especially useful if you're new to a project, trying to onboard quickly, or just stuck trying to understand how a certain function works.

Codex navigated the project and provided a clean, beginner-friendly breakdown of the codebase’s structure. Instead of just listing files, Codex grouped them by purpose:

• It highlighted that qwen3_demo.py is the main script, launching two Gradio-based interfaces—one for reasoning mode switching and another for multilingual translation.
• It identified qwen3_demo.ipynb as an interactive notebook alternative.
• It pointed out test_qwen3_demo.py for unit testing and README.md for documentation and video walkthroughs.

Beyond that, Codex also listed “Key Points to Know,” like dependencies (Ollama CLI), the role of the _run_ollama function, and tips for extending the interface. It even suggested next steps, such as exploring model versioning, improving the UI, and adding error handling.

Example 3: Find and fix a bug

Codex can scan the entire codebase, identify a bug, propose a fix, and show you a preview of the changes. This process resembles code change reviews on GitHub.

You can review the logs to understand the background process for the changes made by clicking “Logs.”

Codex returns a summary of changes made, along with files created or affected by the changes. You can also ask questions about the changes or ask Codex to write new code to enhance the current implementation.

Once satisfied with the code fixes, click “Push” and “Create New PR” to open a new pull request.

After a few seconds, you can click “View Pull Request” to access the pull request and merge it into the main.

Codex makes it possible to merge the changes with just a few clicks.

The changes appear on the main branch within seconds.

Why Is Codex Important?

Codex is a collaborative agent, not a passive code generator. You can ask it to write, refactor, test, debug, or explain, and it’ll show you the terminal logs, citations, and outputs for each step.

Here are some real-world benefits I’ve observed:

• Tasks are traceable and verifiable.
• Codex works in parallel, so you can queue multiple changes.
• It respects your development setup, especially if you’ve configured conventions through an AGENTS.md file.
• It aligns with human PR standards and can pass CI tests.

To me, this feels like OpenAI just released a software engineering intern.

Final thoughts

We learned how Codex can fix bugs, apply feature patches, and explain code logic, all while generating pull requests, running tests, and citing its actions through terminal logs and diffs.

This hands-on walkthrough illustrates how Codex can improve your daily developer workflow, whether you're debugging legacy code, onboarding to a new repo, or triaging maintenance tasks.

As Codex evolves, I anticipate deeper integrations with IDEs, CI pipelines, and task planners, making it a practical addition to any engineering workflow. To learn more about Codex, read the official release blog, and you can also find example use cases on OpenAI’s YouTube channel.

To dive deeper into OpenAI’s engineering-focused models and tools, I recommend these blogs:

• OpenAI Codex CLI Tutorial
• GPT-5.1 Codex Guide: Building a GitHub Issue Analyzer Agent
• Codex CLI For Data Workflow Automation: A Complete Guide
• Codex CLI MCP Tutorial: Building a Portfolio Dashboard Agent