Codex CLI Prompting Guide: Sandboxes, AGENTS.md, and Skills (2026)

Codex CLI is OpenAI's coding agent for the terminal. You point it at a repository, describe the task, and it reads files, writes them, runs commands, and reacts to the output until the work is done. It is the same product family as the Codex cloud tasks and the ChatGPT desktop integration, but the CLI is where most day-to-day engineering happens, because it runs where your code, your shell history, and your test suite already live.

Since July 2026 its default model has been GPT-5.6 Sol, the flagship tier of OpenAI's GPT-5.6 generation. That matters less to your prompting than the thing that genuinely distinguishes Codex CLI from its competitors: it splits what the agent can do from when the agent must ask. Those are two separate settings, enforced at two different layers, and understanding the split is most of what separates a productive Codex session from a frustrating one.

Key takeaways:

• Sandbox mode and approval policy are independent dials. Set the sandbox from the blast radius you can tolerate, then set approvals from how much interruption you want.
• AGENTS.md is the highest-leverage file in the repository. Every rule you put there is a rule you stop retyping, and it works across other agents too.
• Reasoning effort is a cost dial with five settings. Mechanical work does not need high; design work does.
• Named profiles in config.toml let you switch the whole model-and-effort configuration per task instead of tuning flags one at a time.
• Plan before you write. /plan produces a reviewable artifact, and a wrong plan costs a paragraph while a wrong run costs a revert.
• Every MCP server you connect widens both the agent's reach and its prompt injection surface. Add them deliberately.
• The prompt patterns that ship are the same ones that work everywhere: name the success criterion, name the verification command, and keep the diff reviewable.

For the category-level view, see the pillar on prompting AI coding agents. For the instruction-file convention Codex shares with every other agent, see the AGENTS.md guide.

Getting Set Up

Install Codex CLI from npm:

npm install -g @openai/codex

Homebrew (brew install --cask codex) and a direct install script are also available, and Windows users can install through winget. Then authenticate:

codex login              # OAuth through your ChatGPT account
codex login --with-api-key   # API key instead
codex login status       # confirm which account is active

Run codex inside a repository to start an interactive session, or pass a prompt directly for a one-shot run. Before the first real task, run /init so Codex drafts an AGENTS.md for the project, then edit it, because the generated version is a starting point rather than a finished specification.

The Two Dials That Matter

Sandbox Mode: What Codex Can Do

Sandbox mode is enforced at the operating-system level, using Seatbelt on macOS, Landlock and seccomp on Linux, and restricted tokens on Windows. This is the part that does not depend on the model behaving well.

workspace-write is the setting most people should live in. It is permissive enough for real work and still prevents the class of accident where an agent edits something outside the project it was pointed at.

Approval Policy: When Codex Must Ask

Approval policy is a separate key, and it controls interruption rather than capability:

• on-request is the default. Codex works freely inside the sandbox and stops to ask when it needs to do something the sandbox would block, such as writing outside the workspace or reaching the network.
• never suppresses prompts entirely. It exists for CI and unattended automation, where there is nobody at the keyboard to answer.

An older untrusted policy has been retired; on-request covers what it did. The /permissions command adjusts these boundaries mid-session, and /status prints the configuration that is actually in effect, which is the fastest way to settle an argument about which config file won.

Configuration and Precedence

Codex reads TOML configuration from several places, and the precedence runs from most specific to least:

• Command-line flags and -c overrides
• Project config (.codex/config.toml, discovered by walking upward)
• An explicitly selected profile
• User config (~/.codex/config.toml)
• System config (/etc/codex/config.toml)
• Built-in defaults

A reasonable user config:

model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Profiles Are the Underused Feature

Profiles let you name a whole configuration and switch to it per task:

[profiles.mechanical]
model_reasoning_effort = "low"

[profiles.design]
model_reasoning_effort = "xhigh"

codex --profile mechanical "apply the rename from the plan in docs/rename.md"
codex --profile design "propose three approaches for splitting the billing module"

Reasoning effort runs from minimal through low, medium, high, and xhigh. The instinct to leave it on maximum is expensive and often counterproductive: mechanical work does not get better with more deliberation, it just costs more and takes longer. Treat effort the way you treat temperature — a parameter matched to the task, not a quality slider you pin to the top.

AGENTS.md: The File That Does the Most Work

Codex layers instruction files as it walks the tree. A global file in your Codex home directory applies everywhere; then AGENTS.md files from the repository root down to your working directory are concatenated, with the closest file winning where they conflict. Override variants replace rather than extend the normal file at that level, which is useful when a subproject genuinely needs different rules rather than additional ones.

What belongs in it:

# AGENTS.md

## Commands
- Install: `npm install`
- Test: `npm test` (must pass before any task is considered done)
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`

## Conventions
- TypeScript strict mode. No `any`.
- Prefer named exports.
- Tests live beside the file they cover, as `*.test.ts`.

## Do not touch
- `public/generated/**` — build output
- `supabase/schema.sql` — mirrored from migrations, never hand-edited

## Definition of done
Typecheck, lint, and tests all pass. Show the diff before declaring completion.

The "definition of done" section is the one teams skip and then miss. An agent that knows which command proves the work is finished will run it unprompted; an agent that does not will hand you a confident summary of work it never verified.

For the full convention, including monorepo layering and how other tools read the same file, see the AGENTS.md guide.

Prompt Patterns That Work

Plan First on Anything Non-Trivial

/plan asks Codex to produce an approach without executing it. The economics are lopsided: a wrong plan costs you a paragraph to read and a sentence to correct, while a wrong run costs a revert and the tokens spent getting there.

/plan

Goal: move rate limiting from in-process memory to Redis.

Constraints:
- The limiter must fail closed in production if Redis is unreachable.
- Dev and test keep the in-memory store; no Redis dependency in CI.
- Public function signatures in lib/rate-limit.ts stay unchanged.

Tell me which files you will touch and in what order, and name anything
about the current implementation you are unsure of.

That last line is the one that earns its place. Asking the agent to surface uncertainty converts silent wrong assumptions into questions you can answer in one turn.

Name the Verification Command in the Prompt

An agent that has been told how to check its work will check it. One that has not will tell you the work is done because the edits applied cleanly.

The second half of that instruction matters more than it looks. "Make the test pass" is a goal an agent can satisfy by deleting an assertion, and occasionally one will.

Keep the Diff Reviewable

/diff shows everything changed in the session. Ask for work in increments you are willing to read: a run that touches four files is reviewable, and a run that touches forty is a merge you are approving on faith. When a task is genuinely large, have Codex plan it as a sequence and execute one step per run, verifying between steps. This is the same discipline described in spec-driven AI coding.

Use /review as a Second Pass

/review runs a code review against the working tree. It is most useful immediately after a long autonomous run, as a check on work you did not watch happen. It is not a substitute for reading the diff, but it reliably catches the class of mistake where the agent solved the stated problem and quietly broke an adjacent one.

MCP Servers and Skills

Codex is an MCP client. Adding a server:

codex mcp add linear -- npx -y @linear/mcp-server
codex mcp list

Remote servers are added by URL with the auth token supplied through an environment variable rather than inline. Inside a session, /mcp lists the tools currently available.

Skills package repeatable instructions so you stop pasting the same checklist into every session. If you already write skills for other agents, the concept transfers directly; the Agent Skills guide covers the format and the design rules in depth, including why the description field is the part that determines whether a skill ever fires.

Failure Modes and Their Fixes

The agent edits files you did not expect. Your AGENTS.md has no out-of-scope section, or the task was scoped by topic instead of by path. Name the directories in the prompt.

Runs get expensive. Reasoning effort is pinned high for mechanical work. Create a low-effort profile and use it for anything that is applying a decision rather than making one.

The agent claims success without verifying. No definition of done in AGENTS.md, and no verification command in the prompt. Both are one-line fixes.

Approvals interrupt constantly. The sandbox is too tight for the task, so every ordinary action crosses the boundary. Move from read-only to workspace-write rather than loosening approvals.

A long run drifts off the requirement. Skipped the plan step. Use /plan and read it.

Where Codex CLI Fits

Against Claude Code, the comparison is close: both are terminal agents running the full loop, both read AGENTS.md, and both support MCP and skills. Codex separates sandbox from approvals more explicitly and layers TOML configuration across system, user, and project scopes. Against Cursor and Cline, the difference is the surface: Codex has no editor, which is a loss when you want to watch diffs land in place and a gain when you want the agent to run unattended in a worktree. Against Google's Antigravity CLI, the shapes are converging — both now ship sandboxes, subagent-style parallelism, skills, and AGENTS.md support.

The honest summary: in 2026 the terminal agents differ less in capability than in how they let you constrain them. Codex CLI's answer is a real OS sandbox plus a separate approval dial, and if you configure those two things deliberately, the rest of the prompting is the ordinary discipline that works with any agent.

Where to Go Next

• The category pillar: prompting AI coding agents
• The instruction file every agent reads: AGENTS.md guide
• Packaging repeatable procedures: Agent Skills guide
• The framework behind the prompt patterns here: the Agentic Prompt Stack
• Build reusable task prompts with the SurePrompts generator