# Codex

Delegate tasks to a software engineering agent in the cloud.

Codex is a cloud-based software engineering agent. Use it to fix bugs, review
code, do refactors, and fix pieces of code in response to user feedback. It's
powered by a version of [OpenAI o3](https://platform.openai.com/docs/models/o3)
that's fine-tuned for real-world software development.

## Overview

We believe in a future where developers drive the work they want to own,
delegating toilsome tasks to agents. We see early signs of this future today at
OpenAI, with Codex working in its own environment and drafting pull requests in
our repos.

**Codex vs. Codex CLI**  
These docs cover Codex, a cloud-based agent you can find in your browser. For an
open-source CLI agent you can run locally in your terminal, install Codex CLI.

### Video: Getting started with Codex

Codex evolves quickly and may not match exactly the UI shown below, but this
video will give you a quick overview of how to get started with Codex inside
ChatGPT.

## Connect your GitHub

To grant the Codex agent access to your GitHub repos, install our GitHub app to
your organization. The two permissions required are ability to _clone the repo_
and the ability to _push a pull request_ to it. Our app **will not write to your
repo without your permission**.

Each user in your organization must authenticate with their GitHub account
before being able to use Codex. After auth, we grant access to your GitHub repos
and environments at the ChatGPT workspace levelâmeaning if your teammate grants
access to a repo, you'll also be able to run Codex tasks in that repo, as long
as you share a workspace.

## How it works

At a high level, you specify a prompt, and the agent goes to work in its own
environment. After about 3-8 minutes, the agent gives you back a diff.

You can execute prompts in either _ask_ mode or _code_ mode. When you select
_ask_, Codex clones a read-only version of your repo, booting faster and giving
you follow-up tasks. _Code_ mode, however, creates a full-fledged environment
that the agent can run and test against.

1.  You navigate to chatgpt.com/codex and **submit a task**.
2.  We launch a new **container** based upon our base image. We then **clone
    your repo** at the desired **branch or sha** and run any **setup scripts**
    you have from the specified **workdir**.
3.  We
    [configure internet access](https://platform.openai.com/docs/codex/agent-network)
    for the agent. Internet access is off by default, but you can configure the
    environment to have limited or full internet access.
4.  The agent then **runs terminal commands in a loop**. It writes code, runs
    tests, and attempts to check its work. The agent attempts to honor any
    specified lint or test commands you've defined in an `AGENTS.md` file. The
    agent does not have access to any special tools outside of the terminal or
    CLI tools you provide.
5.  When the agent completes your task, it **presents a diff** or a set of
    follow-up tasks. You can choose to **open a PR** or respond with follow-up
    comments to ask for additional changes.

## Submit tasks to Codex

After connecting your repository, begin sending tasks using one of two modes:

- **Ask mode** for brainstorming, audits, or architecture questions
- **Code mode** for when you want automated refactors, tests, or fixes applied

Below are some example tasks to get you started with Codex.

### Ask mode examples

Use ask mode to get advice and insights on your code, no changes applied.

1.  **Refactoring suggestions**

    Codex can help brainstorm structural improvements, such as splitting files,
    extracting functions, and tightening documentation.

    ```text
    Take a look at <hairiest file in my codebase>.
    Can you suggest better ways to split it up, test it, and isolate functionality?
    ```

2.  **Q&A and architecture understanding**

    Codex can answer deep questions about your codebase and generate diagrams.

    ```text
    Document and create a mermaidjs diagram of the full request flow from the client
    endpoint to the database.
    ```

### Code mode examples

Use code mode when you want Codex to actively modify code and prepare a pull
request.

1.  **Security vulnerabilities**

    Codex excels at auditing intricate logic and uncovering security flaws.

    ```text
    There's a memory-safety vulnerability in <my package>. Find it and fix it.
    ```

2.  **Code review**

    Append `.diff` to any pull request URL and include it in your prompt. Codex
    loads the patch inside the container.

    ```text
    Please review my code and suggest improvements. The diff is below:
    <diff>
    ```

3.  **Adding tests**

    After implementing initial changes, follow up with targeted test generation.

    ```text
    From my branch, please add tests for the following files:
    <files>
    ```

4.  **Bug fixing**

    A stack trace is usually enough for Codex to locate and correct the problem.

    ```text
    Find and fix a bug in <my package>.
    ```

5.  **Product and UI fixes**

    Although Codex cannot render a browser, it can resolve minor UI regressions.

    ```text
    The modal on our onboarding page isn't centered. Can you fix it?
    ```

## Environment configuration

While Codex works out of the box, you can customize the agent's environment to
e.g. install dependencies and tools. Having access to a fuller set of
dependencies, linters, formatters, etc. often results in better agent
performance.

### Default universal image

The Codex agent runs in a default container image called `universal`, which
comes pre-installed with common languages, packages, and tools.

_Set package versions_ in environment settings can be used to configure the
version of Python, Node.js, etc.

[openai/codex-universal](https://github.com/openai/codex-universal)

While `codex-universal` comes with languages pre-installed for speed and
convenience, you can also install additional packages to the container using
[setup scripts](https://platform.openai.com/docs/codex/overview#setup-scripts).

### Environment variables and secrets

**Environment variables** can be specified and are set for the full duration of
the task.

**Secrets** can also be specified and are similar to environment variables,
except:

- They are stored with an additional layer of encryption and are only decrypted
  for task execution.
- They are only available to setup scripts. For security reasons, secrets are
  removed from the environment when the agent is running.

### Setup scripts

Setup scripts are bash scripts that run at the start of every task to install
dependencies, linters and other tools that the agent can use to do its work. By
default, Codex will run the standard installation commands for these common
package managers: `npm`, `yarn`, `pnpm`, `pip`, `pipenv`, and `poetry`. You can
also manually configure a setup script. For example:

```bash