Codex — OpenAI’s coding agent

What it is

Codex is OpenAI’s coding agent. It works in the terminal (Codex CLI), as a code editor extension and in the ChatGPT app. With codex cloud 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 Copy

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" Copy

npm

npm install -g @openai/codex Copy

Homebrew

brew install --cask codex Copy

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.

First run — five steps

1. Go to your project folder, run codex and choose “Sign in with ChatGPT”.
2. Ask “Tell me about this project” so it reads the project.
3. Run /init to create AGENTS.md, then write your test command and the rules to follow.
4. Use /permissions to choose what Codex may do without asking.
5. Give a task that names the file, the behaviour and how to check it. Read the diff, run the tests yourself, then commit.

Learn more on SONUB

• Codex: OpenAI's coding agent
• Agents and sub-agents: how an AI works step by step
• Goal and Ralph Loop: let an agent keep going until it is really done
• Agent skills — Codex uses the same SKILL.md folders

Official documentation

• OpenAI — Codex
• Codex CLI — GitHub
• AGENTS.md

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.

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 Git repository) 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.

Using it with Claude Code — instructions in one place, AGENTS.md

If one project uses other AIs such as Claude Code, Cursor or Gemini alongside Codex, separate instruction files for each tool soon drift apart. AGENTS.md is an open format that many coding agents read, so write the rules once in AGENTS.md and every AI works from the same instructions.

When you use it with Claude Code, the best way is to keep no CLAUDE.md in the project and use only AGENTS.md. Without a CLAUDE.md, Claude Code reads AGENTS.md, and it still reads your global ~/.claude/CLAUDE.md. The reasons and steps are explained in Claude Code Intermediate.

1. Write the shared rules only in AGENTS.md.
2. Keep no CLAUDE.md in the project. If you use CLAUDE.md in even one folder, put a CLAUDE.md in every folder, each with just one line: @AGENTS.md.
3. To change a rule, edit only AGENTS.md. Both AIs follow the changed rule.

~/.claude/CLAUDE.md   ← personal rules for Claude Code (still loaded)
~/.codex/AGENTS.md    ← personal rules for Codex

my-project/
└── AGENTS.md         ← the rules — Codex and Claude Code both read this
                        (no CLAUDE.md in the project)

• How to use only AGENTS.md — in detail in Claude Code Intermediate

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

1. Create AGENTS.md with /init and refine the test command and three rules.
2. If you also use Claude Code, check that the project has no CLAUDE.md, so both AIs read the same AGENTS.md.
3. Have it look around the project with codex --sandbox read-only, then hand over a small fix with workspace-write.
4. Review the changes with /diff and /review.
5. 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
• AGENTS.md

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.

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 CI.

• 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 AI tools use outside services (issue trackers, databases, browsers, document tools). Add an MCP server 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 skill 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 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 $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.

• Learn about agent skills — make, install, SONUB skills

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

1. 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.
2. Write a script that summarizes this week's commits into a file with codex exec -o.
3. Add one MCP server and check it with /mcp.
4. Turn one job you do often into a skill in .agents/skills/ and call it with $name.
5. 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

• Codex — Config reference
• Codex — Non-interactive mode
• Codex — MCP
• Codex — Skills
• Codex — Hooks

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.

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 repository to Codex and just writing @codex review in a PR 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 AI reviews code 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 diff 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"

• How to use only AGENTS.md — in detail in Claude Code Intermediate

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

• Codex — Subagents
• Codex — Cloud
• Codex — GitHub
• Codex — GitHub Action

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.