Codex — OpenAI’s coding agent
Type codex in a project folder and it starts. It reads your project, edits files and runs commands to test its own work. This page covers installing it and your first run, and links to the course chapters that go deeper.
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
Codex is OpenAI’s . It works in the (Codex ), as a extension and in the ChatGPT app. With codex you can also hand work to a cloud environment and apply the result on your own computer.
Rules for your project go in AGENTS.md, an open format that many coding agents read. You choose what Codex may do with /permissions.
What you need
- An account: sign in with ChatGPT (Plus, Pro, Business, Edu or Enterprise plans). You can also sign in with an API key, which needs extra setup.
- A computer: macOS or Linux (install script) or Windows (PowerShell install script). npm and Homebrew work too.
- A project folder to work in — ideally a Git repository, 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 script, run the same command 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 --version should print a version number. If you see “command not found”, open the terminal again and check your PATH.
codex --version
First run — five steps
- Go to your project folder, run codex and choose “Sign in with ChatGPT”.
- Ask “Tell me about this project” so it reads the project.
- Run /init 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 .
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
- codex exec "…" — run without the chat screen, for scripts and pipelines
- 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
- Agent skills — teach repeated work with SKILL.md folders in .agents/skills/
Use it safely
- If it changes more than you asked, stop it, undo with git restore and 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.
Learn more on SONUB
Official documentation
Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.
Intermediate — daily habits: AGENTS.md, approvals and 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.
Writing AGENTS.md well
Codex reads AGENTS.md when it starts work. It first reads your global file (~/.codex/AGENTS.md), then walks from the top of the project (usually the top of the ) down to the current folder, 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 (commit it)
- AGENTS.md in a subfolder — instructions added only when working in that folder
- AGENTS.override.md — 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 KiB 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)
/init 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, network), and the approval policy sets when it asks you. Choose both together.
- read-only — it only reads and changes nothing. Use it to look around a project you do not know.
- workspace-write — it edits and runs commands 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.
- danger-full-access — no sandbox, it can do anything. Use it only in an isolated container.
- 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 code.
- /compact — summarize the conversation to free up room. /new — start a new conversation.
- /resume — pick an earlier conversation to continue. In the terminal, codex resume or codex resume --last.
- /status — see the current settings such as model, permissions and working folder. /mcp — see the connected MCP servers.
- @ — find a file and attach it to the request. $ — call a skill. ! — run a shell command right away (!git status).
- -i picture.png — start with a screenshot attached (during a conversation, paste it). --search — turn on live web search.
- /init — create AGENTS.md. /plan — have it make a plan first.
Coming from Claude Code? /import brings in Claude Code's setup and recent conversations.
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 NaN 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 pnpm 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, roll back with git restore 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.
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
Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.
Advanced — extend it: 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 , teach repeated jobs with skills and enforce must-follow rules with hooks.
config.toml and profiles — fit it to your way of working
Codex settings live in ~/.codex/config.toml. Options you used to add every time become defaults once written here. Settings that differ by job go into profile files.
- model · model_reasoning_effort — the model to use and how hard it thinks
- approval_policy · sandbox_mode — the approval policy 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 read only in projects you have marked as trusted.
codex exec — automate without the chat screen
codex exec "…" does the job once without the chat screen and exits. Progress goes to stderr and the final answer to stdout, so it fits well into scripts, cron and .
- It is read-only by default. Add --sandbox workspace-write to let it edit files.
- --json sends progress as JSON lines (JSONL), -o <file> saves the final answer to a file, and --output-schema <file> gets an answer that matches a JSON Schema.
- Run it with no prompt and standard input becomes the prompt; pipe input in together with a prompt and the input is appended.
- Outside a Git repository 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
MCP (Model Context Protocol) is an open standard 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 Claude Code uses work as they are.
- codex mcp add <name> -- <command> — add a server that runs on your computer (stdio).
- codex mcp add <name> --url <url> — add a remote server (streamable HTTP).
- 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 (prompt injection).
Agent skills — teach it jobs you repeat
A is a folder with a SKILL.md 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 (~/.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 $skill-creator 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 hook is a command Codex always runs at a set moment. A request in AGENTS.md can be forgotten, but a hook runs every time. Use hooks to run a formatter, 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 PreToolUse 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).
- matcher chooses the tools, and if the command ends with exit code 2 the action is blocked.
- If you only need notifications, put a program in notify in config.toml — it runs with a JSON 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 commits 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-18. These tools change often — if a command fails, see the official docs.
Master — subagents, cloud, GitHub, several AIs together
Hand work to and the , get reviews from @codex on , 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 Codex to start subagents 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 TOML 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 diff 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
codex cloud runs work in OpenAI's cloud 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 (repository, setup script, secrets, internet access) in the Codex settings in ChatGPT.
- codex cloud shows the task list and starts new tasks. You can also hand one over directly with codex cloud exec --env <environment ID> "…".
- codex apply <task ID> applies the change made in the cloud to your repository (git apply).
- 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 GitHub to Codex and just writing @codex review in a comment gets you a review. With the GitHub Action (openai/codex-action) it can also run automatically on every PR.
- @codex review — reviews that PR and reports only serious problems (P0, 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 prompt 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 read-only 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 ## Code Review Rules section in AGENTS.md 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 Claude Code in one project.
Splitting the roles is another way. One AI plans and builds, another reviews and tests, and a person reads the final and decides whether to merge.
- codex review --uncommitted — Codex reviews the uncommitted changes. --base <branch> reviews a whole branch.
- git diff | claude -p "…" — Claude Code reviews the changes Codex made.
- From inside another AI's session, codex exec 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 (commit): AGENTS.md, .codex/config.toml, .codex/hooks.json, .codex/agents/, .agents/skills/
- Personal (do not commit): ~/.codex/config.toml, profile 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 hooks, not with instructions.
- Pass CI keys only to the step that runs Codex, and run reviews read-only.
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 config.toml and profiles
- Repeated jobs go to skills, must-follow rules to hooks, outside tools through MCP
- Repeated work is automated 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-18. These tools change often — if a command fails, see the official docs.