Intermediate — AGENTS.md, approvals, sandbox, commands

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.

~/.codex/config.toml

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…)

Recommended models — Tool Master

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

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

Order

~/.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.

If one project uses other AIs such as , or alongside Codex, separate instruction files for each tool soon drift apart. AGENTS.md is an open format that many read, so write the rules once in AGENTS.md and every 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.md. The reasons and steps are explained in Claude Code Intermediate.

Write the shared rules only in AGENTS.md.
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.
To change a rule, edit only AGENTS.md. Both AIs follow the changed rule.

my-project/

~/.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, ), 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.

Terminal

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

~/.codex/config.toml

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.

~/.codex/config.toml

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.

Tool context — about 400k instead of 1M

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.

Six good habits — Tool Master

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.

Ten common mistakes — Tool Master

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

~/.codex/config.toml

model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

~/.codex/review.config.toml

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

Terminal

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

Terminal

# 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

~/.codex/config.toml

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

.agents/skills/release-notes/SKILL.md

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

.codex/agents/reviewer.toml

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.

.github/workflows/codex-review.yml

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.

Terminal

# 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 (): 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.

Basics — install it and do your first task

What it is

What you need

Install

Check the installation

First run — five steps

Features you will use often

Use it safely

Basic practice — try it once from the start

Learn more on SONUB

Official documentation