Codex — OpenAI’s coding agent
Install Codex, run your first task in a project folder, then level up in four tabs. Start by checking what you need and copying your install command.
Basics — install it and do your first task
New to it? Start here. Learn what Codex is, install it and follow the first five steps. When you have done them all, move on to the [Intermediate] tab above.
What it is
is ’s . It works in the (Codex CLI), as a and in the app. With you can also hand work to a environment and apply the result on your own computer.
Rules for your project go in , an open format that many coding agents read. You choose what Codex may do with /.
What you need
- An account: Codex is in every ChatGPT plan (Free, Go, Plus, Pro, Business, Edu, Enterprise), but where you can use it differs. On Free and Go it is only in the desktop app (still rolling out); the on this page needs Plus or higher. You can also sign in to the CLI with an — paid at prices, with no cloud features.
- A computer: or () or ( install script). and work too.
- A project folder to work in — ideally a , so every change can be reviewed and undone.
Install
On macOS and Linux run the first line; on Windows run the PowerShell line. If you installed with the , run the same again to update.
- macOS · Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh- Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"- npm
npm install -g @openai/codex- Homebrew
brew install --cask codex
Check the installation
Open a new terminal window. codex should print a number. If you see “”, open the terminal again and check your .
codex --version
First run — five steps
- Open a terminal, move into your project folder with <folder>, then type codex, press Enter and choose “Sign in with ChatGPT”.
- Ask “Tell me about this project” so it reads the project.
- Run to create AGENTS.md, then write your test command and the rules to follow.
- Use /permissions to choose what Codex may do without asking.
- Give a task that names the file, the behaviour and how to check it. Read the , run the tests yourself, then .
cd my-project
codex
Features you will use often
- AGENTS.md — project instructions read in every session (start with /init)
- /permissions — how far it may edit files and run commands
- "…" — run without the chat screen, for scripts and
- codex cloud — hand work to a cloud environment and apply the result locally
- The code editor extension and the ChatGPT app — the same Codex in other places
- skills — teach repeated work with folders in .agents/skills/
Use it safely
- If it changes more than you asked, stop it. Undo a file with <file> (or pick parts with git restore -p <file>). This discards every unstaged change in that file — your own edits too — but keeps staged changes and new untracked files (GIT step 4). Then ask again, naming the exact files.
- Read the diff even when the tests pass, and commit only what you understand.
- For a big task, ask for a plan first and hand it over in small pieces.
Basic practice — try it once from the start
- Make a practice folder ( hello-ai cd hello-ai), turn it into a Git repository with git init, then run codex. If you see the input box, it worked.
- Ask: "Make , a one-page website that shows today's date." If it asks before creating the file, read what it plans and allow it.
- Open index.html in your and check with your own eyes that the date shows.
- See what changed with git status, then save it with git add . and git commit -m "first page".
- Ask once more: "Make the date bigger." If you do not like the result, go back to the last commit with git restore index.html.
If you get stuck: if codex does not start, check the install with codex --version; if sign-in fails, run codex login. Done all five? Move on to the [Intermediate] tab.
Learn more on SONUB
Official documentation
Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.
Intermediate — AGENTS.md, approvals, sandbox, commands
You have installed it and done a first task — now build the habits you will use every day. Write AGENTS.md well, share the same instructions with other AIs such as Claude Code, decide how much to hand over with approvals and the sandbox, and learn the chat commands and how to ask well.
Models and reasoning effort — which to use (recommended: GPT-6.1 Sol, High)
As of November 2026, use GPT-6.1 Sol at High effort for development — set it as below or pick it with /. Every model and , and when to go lower or higher, is in Recommended use on Tool Master.
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
codex -m gpt-6.1-sol
codex -m gpt-6.1-sol -c model_reasoning_effort=high
codex exec -m gpt-6.1-sol "Review the current changes"
# inside Codex
/model # model → effort (Max · Ultra: More reasoning…)
Writing AGENTS.md well
reads when it starts work. It first reads your file (~/.codex/AGENTS.md), then walks from the top of the project (usually the top of the ) down to the , finds one file per folder and joins them in order. Files closer to the current folder come later, so they win.
- ~/.codex/AGENTS.md — your personal instructions for every project
- AGENTS.md at the top of the project — instructions the team shares ( it)
- AGENTS.md in a — instructions added only when working in that folder
- — if it is in the same folder, it is read instead of AGENTS.md (for trying a change for a while).
- Only up to 32 in total is read by default (project_doc_max_bytes). To use files with other names, list them in project_doc_fallback_filenames.
# AGENTS.md
## Setup
- Install: pnpm install
- Test: pnpm test
- Lint: pnpm lint
## Code style
- TypeScript strict mode, single quotes.
- Keep functions small. Add a test for every bug fix.
## Don't
- Don't edit generated files in dist/.
- Don't commit .env files.
~/.codex/AGENTS.md ← you, every project (read first)
my-project/AGENTS.md ← team rules (commit it)
my-project/web/AGENTS.md ← only for web/ (read last, so it wins)
reads the project and writes a first AGENTS.md. AGENTS.md is read once per run, so restart Codex after editing it.
Approvals and the sandbox — how much to hand over
Codex keeps things safe in two ways. The sandbox sets what it can technically do (writing files, ), and the sets when it asks you. Choose both together.
- — it only reads and changes nothing. Use it to look around a project you do not know.
- — it edits and runs only inside the working folder. In a Git repository the default is "Auto", which pairs this with on-request. The network is off by default and .git, .codex and .agents cannot be written.
- — no sandbox, it can do anything. Use it only in an .
- Approval policy (-a): on-request asks when it needs to go outside the sandbox, never does not ask (it works only inside the sandbox).
- /permissions switches modes during a conversation, and /status shows the current settings.
codex --sandbox read-only # look only, change nothing
codex --sandbox workspace-write # edit inside this folder ("Auto" in a Git repo)
codex -a never --sandbox workspace-write # never ask, but stay inside the sandbox
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
The --full-auto in older articles no longer exists. Use --sandbox workspace-write for the same thing. --yolo (--dangerously-bypass-approvals-and-sandbox) turns off both the sandbox and approvals, so use it only somewhere isolated.
Commands in the chat screen
Type / in the Codex chat screen and the list of commands appears. Learn the ones you use every day first.
- /model — choose the model and how hard it thinks (reasoning effort).
- /diff — see the files changed in this session. /review — have it review the changed .
- /compact — summarize the conversation to free up room. /new — start a new conversation.
- — pick an earlier conversation to continue. In the terminal, codex resume or codex resume --last.
- /status — see the current settings such as model, and working folder. /mcp — see the connected .
- @ — find a file and attach it to the request. $ — call a . ! — run a command right away (!git status).
- -i picture.png — start with a attached (during a conversation, paste it). --search — turn on live web search.
- /init — create AGENTS.md. /plan — have it make a plan first.
- <> — keeps working until it is met. /goal alone shows it; /goal pause, resume and clear pause, continue and remove it (Codex 0.128.0 and later).
Coming from Claude Code? /import brings in Claude Code's setup and recent conversations.
Save context — SONUB rule: auto compact at about 400k, base context at 6% or less
Codex also rereads the whole current every time you ask for something, so use the same rule as Claude Code — to work with about 400k instead of the full 1M, and keep the base context (the default , skills, MCP and so on) at 6% or less. Doing this cuts your usage a lot. About 400k and 6% are SONUB’s own rule of thumb, not official recommendations — the official docs only describe the settings.
- Put model_context_window = 500000 and model_auto_compact_token_limit = 475000 in ~/.codex/config.toml (example below): Codex treats the as 500k tokens and compacts automatically when the context reaches 475k.
- /compact compacts by hand at any time, and /new opens a fresh conversation when the job changes.
- Run /status right after opening a new conversation to see context usage. What is already taken before you ask anything (system prompt, AGENTS.md, skills, MCP tools) is the base context, and it should be 6% or less.
- Over 6%? Trim it — remove MCP servers you do not use from or turn them off with enabled = false, remove unused skills, and keep only the rules you really need in AGENTS.md.
model_context_window = 500000
model_auto_compact_token_limit = 475000
The base context is sent with every request, so saving even a few percent adds up over the whole conversation and cuts usage a lot.
Handing over work well — where, what and how to check
A good request has three parts: where (files and folders), what (the behaviour you want) and how to check it (tests, commands, screens). The clearer the three are, the less Codex wanders and the more it checks its own results.
- Vague request: "Fix the cart"
- Clear request: "In @src/cart.ts the total becomes when a quantity is 0. Make it remove that item when the quantity is 0, add a test to tests/cart.test.ts and check that test passes."
- Start a big job with "Show me only a plan first", adjust the plan, then let it go on.
- If it changes more than you asked, stop it, undo only that file with <file> (your own unstaged edits in it are lost too) and ask again, naming the files.
- Paste the whole error output — the original is more accurate than a summary.
- When it is done, read the changes with /diff, run the tests yourself, then commit.
Best practices — how OpenAI recommends using Codex
In short: ask with four parts (goal, context, limits, done when), plan hard work first, let Codex check its own work, keep rules in AGENTS.md and use one chat per piece of work. The six good habits, with commands for both tools, are in Recommended use.
Common mistakes — and how to avoid them
The official guide lists eight mistakes — for example rules stuffed into the , no build or test commands, a skipped plan and full access too early. All ten mistakes from both guides, each with its fix, are in Recommended use.
Intermediate practice — try it in your own project
- Create AGENTS.md with /init and refine the test command and three rules.
- If you also use Claude Code, check that the project has no CLAUDE.md, so both AIs read the same AGENTS.md.
- Have it look around the project with codex --sandbox read-only, then hand over a small fix with workspace-write.
- Review the changes with /diff and /review.
- See the current settings with /status and continue the conversation with codex resume --last.
Done all five? Move on to the [Advanced] tab.
Official documentation
- Codex — AGENTS.md
- Codex — Approvals & security
- Codex — Config reference
- AGENTS.md
- Codex — Models
- Codex — Best practices
- Codex — Common mistakes
Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.
Advanced — config.toml, codex exec, MCP, skills, hooks
Fit Codex to your way of working with the config file and profiles, put it into scripts with codex exec, connect outside tools with MCP, teach repeated jobs with skills and enforce must-follow rules with hooks.
config.toml and profiles — fit it to your way of working
settings live in ~/.codex/. Options you used to add every time become defaults once written here. Settings that differ by job go into files.
- · model_reasoning_effort — the model to use and how hard it thinks
- · sandbox_mode — the and sandbox (the values from Intermediate)
- A profile is a file ~/.codex/<name>.config.toml. Choose it with codex -p <name> and its values sit on top of the base settings (the old [profiles.x] tables are no longer read).
- -c key=value changes a setting for this run only (for example -c sandbox_workspace_write.network_access=true).
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
# a profile: codex -p review
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"
codex -p review
codex -c sandbox_workspace_write.network_access=true
A .codex/config.toml in a project holds settings for that project only — it is in projects you have marked as trusted.
codex exec — automate without the chat screen
"…" does the job once without the chat screen and exits. Progress goes to and the final answer to stdout, so it fits well into , and .
- It is read-only by default. Add --sandbox workspace-write to let it edit files.
- --json sends progress as (JSONL), -o <file> saves the final answer to a file, and --output-schema <file> gets an answer that matches a .
- Run it with no and standard input becomes the prompt; pipe input in together with a prompt and the input is appended.
- Outside a you need --skip-git-repo-check. codex exec resume --last continues the previous run.
# Ask once, print the answer (read-only by default)
codex exec "Summarize what changed in the last 5 commits"
# Allow edits inside this folder
codex exec --sandbox workspace-write "Fix the failing test in tests/cart.test.ts"
# Pipe input in
cat error.log | codex exec "Find the cause"
# For scripts: JSON events, the final answer in a file, a JSON Schema answer
codex exec --json "List the TODOs in src/" > events.jsonl
codex exec -o notes.md "Write release notes for this week"
codex exec --output-schema schema.json "Rate the test coverage of each file"
# Continue the last run
codex exec resume --last "Now add tests for it"
In CI, pass CODEX_API_KEY only to the step that runs Codex, so scripts in other steps cannot see the key.
MCP — connect outside tools
(Model Context Protocol) is an that lets tools use outside services (issue trackers, , , document tools). Add an MCP to Codex and it can use that server's tools — the same servers uses work as they are.
- codex mcp add <name> -- <> — add a server that runs on your computer (stdio).
- codex mcp add <name> --url <> — add a remote server ().
- Added servers are saved in [mcp_servers.<name>] tables in config.toml. During a conversation, /mcp shows their status.
# A server that runs on your computer (stdio)
codex mcp add playwright -- npx @playwright/mcp@latest
# A remote server (streamable HTTP)
codex mcp add notion --url https://mcp.notion.com/mcp
codex mcp list
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
tool_timeout_sec = 60
Add only MCP servers you trust. A server that fetches outside text can bring in instructions hidden in that text ().
Agent skills — teach it jobs you repeat
A is a folder with a in it — the same open format as Claude Code. Normally Codex knows only each skill's name and description; when a job matches the description, it reads the body and follows it. The old custom prompts (~/.codex/prompts) should now be turned into skills.
- .agents/skills/<name>/SKILL.md is for this repository, ~/.agents/skills/ for all your projects.
- Call one directly with $<skill name> or pick from the list with /skills. It also uses one on its own when the description fits.
- Write name and description, and keep scripts and reference documents in scripts/ and references/.
- Ask the built-in and it helps you make a new skill.
---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes or a changelog.
---
1. Find the last tag: `git describe --tags --abbrev=0`
2. Read the commits since then: `git log <tag>..HEAD --oneline`
3. Group them under Added / Fixed / Changed, in plain sentences.
Hooks — commands that always run at set moments
A is a command Codex always runs at a set moment. A request in can be forgotten, but a hook runs every time. Use hooks to run a , block dangerous commands and get a notification when work is done.
- Put them in ~/.codex/hooks.json (you) or .codex/hooks.json in the repository (project).
- Attach them to moments such as and PostToolUse (before and after a tool), UserPromptSubmit (when you send a request), Stop (when it finishes its answer) and SessionStart (when a session starts).
- chooses the tools, and if the command ends with 2 the action is blocked.
- If you only need notifications, put a in notify in config.toml — it runs with a argument each time a turn ends.
A new hook runs only after you mark it as trusted in /hooks. Trust a hook from someone else only after you have read and understood its command.
Advanced practice
- Write your default approval and sandbox in ~/.codex/config.toml, make a read-only review profile (review.config.toml) and use it with codex -p review.
- Write a script that summarizes this week's into a file with codex exec -o.
- Add one MCP server and check it with /mcp.
- Turn one job you do often into a skill in .agents/skills/ and call it with $name.
- Use a PostToolUse hook so a formatter runs on every file edit, and mark it as trusted in /hooks.
Done all five? Move on to the [Master] tab.
Official documentation
Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.
Master — subagents, cloud, GitHub, several AIs together
Hand work to subagents and the cloud, get reviews from @codex on GitHub, review each other's work with other AIs such as Claude Code, and have the team work from the same setup.
Subagents — hand off parts of the work
Ask to start and it splits research, building and review to run at the same time. Each has its own conversation, so the main conversation stays clean.
- Built-in default, worker and explorer are there from the start, and /subagents moves between subagents.
- Make your own subagents as files in .codex/agents/ (project) or ~/.codex/agents/ (you) — name, description, developer_instructions.
- Subagents inherit the parent's sandbox and approval settings.
- Split the roles in your request, like "Review the current with reviewer, and meanwhile have worker write tests".
name = "reviewer"
description = "Reviews diffs for bugs and missing tests. Read-only."
developer_instructions = """
Run git diff. List bugs with file and line, then missing tests.
Never edit files.
"""
model_reasoning_effort = "high"
Codex cloud — hand work to the cloud
runs work in 's environment. It does not use your computer, so you can hand over several jobs at once and apply only the finished results you choose to your files.
- First create an environment (, setup , , internet access) in the Codex settings in .
- codex cloud shows the task list and starts new tasks. You can also hand one over directly with codex cloud exec --env <environment > "…".
- codex apply <task ID> applies the change made in the cloud to your repository ().
- Have it try the same job several times (--attempts) and pick the best result.
codex cloud # see and start cloud tasks
codex cloud exec --env <ENV_ID> "Add input checks to the signup form"
codex cloud list
codex apply <TASK_ID> # apply the result to your files
GitHub — @codex review in PRs
Connect a repository to Codex and just writing @codex review in a comment gets you a review. With the (openai/codex-action) it can also run automatically on every PR.
- @codex review — reviews that PR and reports only serious problems (, P1). You can turn on automatic review of every PR in the Codex settings.
- Any other @codex … comment starts a cloud task with that content.
- openai/codex-action@v1 takes and sandbox, runs Codex and gives the final answer as final-message — post it as a comment in a next step.
- Pass the key as a repository secret (OPENAI_API_KEY), and keep sandbox at for a review that only reads.
name: Codex review
on:
pull_request:
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- uses: openai/codex-action@v1
id: codex
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt: "Review this pull request. List bugs and missing tests."
sandbox: read-only
# the answer is in steps.codex.outputs.final-message
Put a ## Rules section in and Codex's PR reviews follow those rules.
Using several AIs together — review each other
When another reviews one AI wrote, problems that one would miss alone show up. If you share the same instructions through AGENTS.md, it is easy to switch between Codex and in one project.
Splitting the roles is another way. One AI plans and builds, another reviews and tests, and a person reads the final diff and decides whether to merge.
- codex review --uncommitted — Codex reviews the uncommitted changes. --base <> reviews a whole branch.
- diff | claude -p "…" — Claude Code reviews the changes Codex made.
- From inside another AI's session, can hand one job to Codex (for example writing tests or making a picture).
- When the two AIs disagree, have both give evidence (file, line, test result) and let a person check and choose.
# Claude Code wrote the change — Codex reviews it
codex review --uncommitted
# Codex wrote the change — Claude Code reviews it
git diff | claude -p "Review this diff. List bugs and missing tests."
# From inside another AI's session, hand one job to Codex
codex exec --sandbox workspace-write "Write unit tests for src/price.ts"
Running a team setup — together on the same settings
When many people and many AIs work in one repository, settings pile up fast. Decide what is shared and what is personal, and what is a request and what is enforced.
- Shared (): AGENTS.md, .codex/config.toml, .codex/hooks.json, .codex/agents/, .agents/skills/
- Personal (do not commit): ~/.codex/config.toml, files, ~/.codex/AGENTS.md
- Keep AGENTS.md short. Add a rule only when the same mistake repeats, and delete wrong rules.
- Enforce what must be followed with the sandbox, approvals and , not with instructions.
- Pass keys only to the step that runs Codex, and run reviews read-only.
Master practice — automation and working with other AIs
- Run Codex once without a conversation: codex exec "Find the test of this project" > report.md, then read report.md.
- Save your usual settings (, sandbox) in ~/.codex/config.toml, open codex again and check with /status that they apply.
- Make a second folder with add ../my-project-b -b try-b and give Codex and Claude Code different jobs. When both finish, have each review the other's diff.
- Leave @codex review on a GitHub pull request and see the review arrive (connect Codex to the repository first).
- Add one team rule to AGENTS.md, give the same job to Codex and Claude Code, and compare whether both follow the rule.
If you get stuck: codex exec is read-only by default, so add --sandbox workspace-write when it must edit files. If a setting does not apply, check the current values with /status and codex --help. Done all five? Check yourself with the checklist below.
Master checklist
- Shared rules in AGENTS.md — other AIs such as Claude Code work from the same instructions
- You choose the sandbox and approvals to fit the job, with defaults written in and profiles
- Repeated jobs go to skills, must-follow rules to hooks, outside tools through
- Repeated work is with codex exec and the GitHub Action
- Big jobs are split across subagents and codex cloud, and only chosen results are applied
- AIs review each other's work, and a person checks the final diff and tests
The tools change often. If a command does not work, check codex --help and the official docs first. Options in older articles (--full-auto, [profiles.x]) may already have changed.
Official documentation
Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.