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.
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):
- Install Node.js, then run
npm install -g @openai/codex. - In your project folder run
codexand sign in with your ChatGPT account (or set an API key). - Describe the task. Codex proposes changes and asks before running commands, unless you loosen the approval mode.
Cloud (ChatGPT):
- Open Codex in the ChatGPT sidebar and connect your GitHub account.
- Pick a repository and an environment (it installs dependencies in a sandbox).
- 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.mdfile 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.
