C

Codex

OpenAI's coding agent: give it a task in your repository and it writes, runs and tests the code, locally or in the cloud.

6 chapters27 tutorialsOfficial site

01 · Introduction

What Codex is

Codex is OpenAI's agent for software work. Instead of pasting code into a chat, you point it at a project and describe the task: add a date filter to the report page, find why the test fails, write a script that renames these files.

It comes in a few shapes that share the same agent:

  • Codex CLI: runs in your terminal on your own machine, inside your project folder.
  • Codex in ChatGPT: runs in a cloud sandbox connected to your GitHub repository and opens a pull request with the result.
  • IDE extension: the same agent inside VS Code and similar editors.

You do not have to be a programmer to get value from it, but you do need to be able to run and check what it produces.

02 · When to use it

When to use it

  • Small, well-described changes to an existing project: a new field, a bug with a clear error message, a one-off data script.
  • Chores you would otherwise postpone: writing tests, updating a dependency, adding comments.
  • Learning a codebase: ask it to explain how a feature works, file by file.

For a brand-new product with no code yet, start with a clear written plan first; an agent is only as good as the brief.

03 · Setup

Getting started

Terminal (CLI):

  1. Install Node.js, then run npm install -g @openai/codex.
  2. In your project folder run codex and sign in with your ChatGPT account (or set an API key).
  3. Describe the task. Codex proposes changes and asks before running commands, unless you loosen the approval mode.

Cloud (ChatGPT):

  1. Open Codex in the ChatGPT sidebar and connect your GitHub account.
  2. Pick a repository and an environment (it installs dependencies in a sandbox).
  3. Type the task; when it finishes, review the diff and open a pull request.

A ChatGPT Plus, Pro, Team or Enterprise plan includes Codex; the CLI can also use pay-as-you-go API credit.

04 · How to use it

Day-to-day use

  • Write the task like a ticket: what to change, where, how you will know it worked.
  • Add an AGENTS.md file to the repository with the commands to build and test and the house rules. Codex reads it on every run.
  • Let it run the tests. A diff that passes tests is worth ten times a diff that "looks right".
  • Review every change before merging, especially anything touching data, payments or permissions.
  • Keep tasks small. Ten small pull requests are easier to check than one large one.

05 · Pitfalls

Pitfalls

  • Approval modes. Full-auto mode lets it run any command in your project. Use it only in a folder you can restore from git.
  • It can be confidently wrong about library versions; check the official docs when something looks off.
  • The cloud sandbox has no internet by default, so tasks that need to download packages at run time may fail until the environment is configured.
  • Usage is metered. Long sessions on large repositories go through a plan's allowance faster than chat does.

06 · Resources

Where to go next

Compare it with Claude Code (see the Claude handbook): the workflow is the same, and many teams use both.

My notes

Sign in to keep private notes on this handbook.Sign in