Primary navigation

Quickstart

Get started with Codex

Quickstart

Codex is OpenAI’s coding agent that can read, modify, and run code. It helps you build faster, squash bugs, and understand unfamiliar code.

It meets you where you are: in your terminal, in your IDE, or you can also run tasks in the cloud, in the Codex interface or in GitHub.

Setup

You’ll need a ChatGPT Plus, Pro, Team, Edu, or Enterprise plan to use Codex on every surface. You can also use Codex locally with an OpenAI API key, but this requires additional setup—you can learn more in our pricing page.

Once you’re set up, you can sign in with your ChatGPT account and use Codex in different ways:

  • Cloud agent: you can navigate to chatgpt.com/codex or tag @codex in a GitHub PR to use Codex in the cloud
  • IDE extension: you can install the Codex extension for your IDE and use it in your editor
  • CLI: you can install the Codex CLI and use it in your terminal

You can also delegate tasks to the cloud agent from the IDE extension.

Cloud agent

To use Codex in the cloud, you should start by configuring a new environment for Codex to work in. You can do this by navigating to the environment settings page at chatgpt.com/codex and following the steps there to connect a GitHub repository.

You can learn more about how to configure environments in the dedicated page.

Once your environment is set up, you can launch coding tasks from the interface, and follow progress there. You can inspect logs in real-time to follow along while Codex is working, or you can let it run in the background.

When a task is done, you will be able to review the proposed changes in the interface in the form of diffs, iterate if needed, and create a PR in your GitHub repository.

Codex will show you a preview of the changes and you’re welcome to accept the PR as is, or you can check out the branch locally and test the changes.

You can do this by running the following commands (assuming you have already cloned your repository):

git fetch
git checkout branch-name

To learn more about how to delegate tasks to Codex in the cloud, refer to our dedicated guide.

IDE extension

You can install the Codex extension for your IDE and use it in your editor:

Once installed, you’ll find the extension in your sidebar next to other extensions - it might be hidden in the collapsed section. Most people like dragging “Codex” to the right side of the editor.

You will be prompted to sign in with your ChatGPT account to get started (you can also use your API key, but this requires additional setup - you can learn more in our pricing page).

Once signed in, you will be able to use Codex in your editor. By default, it will run in “Agent” mode, which means it can read files, make edits, and run commands in the current directory.

You can undo edits from the editor, but we recommend creating git checkpoints before and after each task to be able to revert to a previous state if needed.

You can learn more about how to use the IDE extension in our dedicated guide.

CLI

The Codex CLI is a coding agent that you can run locally from your terminal and that can read, modify, and run code on your machine.

The Codex CLI officially supports macOS and Linux. Windows support is still experimental—we recommend running in WSL.

Installation

Install the Codex CLI with your preferred package manager:

Install with npm

npm install -g @openai/codex

Install with Homebrew

brew install codex

Usage

Run codex in your terminal to get started:

codex

This will run the Codex CLI with default settings, and you will be prompted to authenticate. We recommend signing in with your ChatGPT account, as you have included usage credits.

You will then be able to ask Codex to perform tasks in the current directory.

As Codex can make edits to your codebase, we recommend creating git checkpoints before and after each task to be able to revert to a previous state if needed.

You can configure which model, approval mode, prompt or other parameters to use directly from the CLI.

Refer to our Codex CLI overview page for more details.

Working with Codex

You are now ready to start using Codex in your preferred environment.

A typical workflow looks like this:

  1. Start with the Codex CLI to generate code for a new project
  2. Open your preferred IDE to make edits, assisted by the Codex IDE extension
  3. If you want to build new features that are pretty much independent from the current codebase, you can delegate this to the Codex cloud agent (e.g. adding auth, connecting to a database, adding new pages, etc.)
  4. Review the changes in the Codex interface and create PRs on GitHub
  5. Check out the PR locally and test the changes
  6. If changes are needed, you can iterate on the PR on GitHub by tagging @codex in a comment
  7. While this is happening, you can continue working on other tasks in your IDE
  8. Once you are satisfied with the changes, you can merge the PR
  9. Repeat the process with other tasks

Next steps

You can learn more about how to use Codex in these different environements in the dedicated guides:

You can also dive deeper into how to prompt Codex in our prompting guide, or how to configure Codex for enterprise in our enterprise admin guide.