What Codex is and how to set it up
An agent that reads your repository and edits files, rather than a completion popup - plus a starting configuration you can trust.
An agent, not an autocomplete
Codex is a software engineering agent. You describe a task in natural language; it explores the repository, proposes or applies edits across several files, and runs commands such as the test suite. That is a different tool from tab completion: the unit of work is a task, not a line, and the unit of review is a diff, not a suggestion.
| Surface | How you drive it | Best for |
|---|---|---|
| CLI | A terminal prompt in the project directory | Local work with shell, git and test commands |
| IDE extension | A side panel next to your editor | Staying in the editor while reviewing edits inline |
| Cloud / delegated | A task queued from the web or an issue | Long, self-contained changes you can review later |
| API / CLI scripting | Non-interactive invocation in a script or CI job | Repeatable jobs such as a mechanical refactor |
- It sees what you give it: files in the working tree, plus whatever it can read through the tools you allow.
- It is not deterministic - the same instruction can produce two different diffs on two runs.
- It is strongest where the repository itself demonstrates the pattern to follow: an existing test style, an existing config format, an existing error type.
- It is weakest where correctness is invisible to tests, such as business rules, security decisions and anything with money attached.
Install and configure
# install the CLI, then authenticate with your account
npm install -g @openai/codex
codex --version
codex # first run walks through sign-in
# sanity check: ask a question that needs no file access
codex exec "list the top-level directories and describe the build system"# ~/.codex/config.toml - the shape of the settings that matter first.
# Key names move between releases; run the tool's own help to confirm yours.
model = "gpt-5-codex"
# how much the agent may do without asking
approval_policy = "on-request" # ask when it wants to leave the sandbox
sandbox_mode = "workspace-write" # read-only | workspace-write | danger-full-access
# project instructions live in the repository, not in your home directory:
# AGENTS.md at the repo root, and per-directory AGENTS.md files deeper in the tree💡
Start with
read-only or workspace-write and an approval policy that asks before commands outside the sandbox. Raise the limits only for a specific task, and lower them again afterwards - a wide permission granted once tends to stay granted.FAQ
Do I need an API key or a subscription?
Either works. A ChatGPT plan covers interactive use, and an API key is the usual choice for scripted, non-interactive runs where you want usage billed and metered separately. Whichever you pick, keep the credential out of the repository.
How is this different from a chat window?
A chat window has no file access and no way to verify anything. An agent reads the repository, makes edits and can run the test suite, which means you review a concrete diff instead of pasting code back and forth.
Related
Using Codex in a real workflow Installing and configuring Claude Code
Last refreshed 2026-09-18.