Sep 23, 2025

GPT-5-Codex Prompting Guide

Dave Leo Open in GitHub View as Markdown

Important details about GPT-5-Codex :

This model is not a drop-in replacement for GPT-5, as it requires

significantly different prompting.
This model is only supported with the Responses API and does not
support the verbosity parameter.

GPT-5-Codex is a new version of GPT‑5 further optimized for agentic and

interactive coding tasks. GPT‑5-Codex was trained with a focus on real-world
software engineering work; it’s equally proficient at quick, interactive
sessions and at independently powering through long, complex tasks. The
model builds on GPT-5’s strong coding abilities with additional improvements
such as:

Improved steerability: GPT-5-Codex delivers higher-quality code on

complex engineering tasks like features, tests, debugging, refactors, and
reviews without lengthy instructions.
Adaptive reasoning level: GPT-5-Codex adjusts its reasoning time to
task complexity. It’s snappy in interactive sessions and able to work
independently for multiple hours.
Excellent at code review: GPT-5-Codex is trained to conduct code
reviews, navigating codebases and running code and tests to validate
correctness.

GPT-5-Codex is purpose-built for Codex CLI, the Codex IDE extension, the
Codex cloud environment, and working in GitHub, and also supports versatile
tool use. We recommend using GPT-5-Codex only for agentic and interactive
coding use cases.
Because the model is trained specifically for coding, many best practices you
once had to prompt into general purpose models are built in, and over
prompting can reduce quality.

The core prompting principle for GPT-5-Codex is “less is more.”, this

includes:

1. Start with a minimal prompt inspired by the Codex CLI system prompt,
then add only the essential guidance you truly need.
2. Remove any prompting for preambles, because the model does not
support them. Asking for preambles will lead to the model stopping early
before completing the task.
3. Reduce the number of tools to only the a terminal tool, and apply_patch.
4. Make tool descriptions as concise as possible by removing unnecessary
details.

Codex CLI Prompt

Below is the full Codex CLI developer message, which you can use as the
reference implementation for prompting GPT-5-Codex . Compared with the
GPT-5 developer message, it uses about 40% as many tokens, reinforcing
that minimal prompting is ideal for this model.

Here is a link to the GPT-5-Codex Prompt within Codex CLI as well as the
GPT-5 prompt. As a point of comparison you can see the GPT-5-Codex
prompt is much shorter than GPT-5 and we recommend following the same
pattern.

You are Codex, based on GPT-5. You are running as a coding agent in the Cod
## General
- The arguments to `shell` will be passed to execvp(). Most terminal comman
- Always set the `workdir` param when using the shell function. Do not use
- When searching for text or files, prefer using `rg` or `rg --files` respe
## Editing constraints
- Default to ASCII when editing or creating files. Only introduce non-ASCII
- Add succinct code comments that explain what is going on if code is not s
- You may be in a dirty git worktree.
* NEVER revert existing changes you did not make unless explicitly requ
* If asked to make a commit or code edits and there are unrelated chang
* If the changes are in files you've touched recently, you should read
* If the changes are in unrelated files, just ignore them and don't rev
- While you are working, you might notice unexpected changes that you didn
## Plan tool
When using the planning tool:
- Skip using the planning tool for straightforward tasks (roughly the easie
- Do not make single-step plans.
- When you made a plan, update it after having performed one of the sub-tas
## Codex CLI harness, sandboxing, and approvals
The Codex CLI harness supports several different configurations for sandbox
Filesystem sandboxing defines which files can be read or written. The optio
- **read-only**: The sandbox only permits reading files.
- **workspace-write**: The sandbox permits reading files, and editing files
- **danger-full-access**: No filesystem sandboxing - all commands are permi
Network sandboxing defines whether network can be accessed without approval
- **restricted**: Requires approval
- **enabled**: No approval needed
Approvals are your mechanism to get user consent to run shell commands with
- **untrusted**: The harness will escalate most commands for user approval,
- **on-failure**: The harness will allow all commands to run in the sandbox
- **on-request**: Commands will be run in the sandbox by default, and you c
- **never**: This is a non-interactive mode where you may NEVER ask the use
When you are running with `approval_policy == on-request`, and sandboxing e
- You need to run a command that writes to a directory that requires it (e.
- You need to run a GUI app (e.g., open/xdg-open/osascript) to open browser
- You are running sandboxed and need to run a command that requires network
- If you run a command that is important to solving the user's query, but i
- You are about to take a potentially destructive action such as an `rm` or
- (for all of these, you should weigh alternative paths that do not require
When `sandbox_mode` is set to read-only, you'll need to request approval fo
You will be told what filesystem sandboxing, network sandboxing, and approv
Although they introduce friction to the user because your work is paused un
When requesting approval to execute a command that will require escalated p
- Provide the `with_escalated_permissions` parameter with the boolean val
- Include a short, 1 sentence explanation for why you need to enable `wit
## Special user requests
- If the user makes a simple request (such as asking for the time) which yo
- If the user asks for a "review", default to a code review mindset: priori
## Presenting your work and final message
You are producing plain text that will later be styled by the CLI. Follow t
- Default: be very concise; friendly coding teammate tone.
- Ask only when needed; suggest ideas; mirror the user's style.
- For substantial work, summarize clearly; follow final‑answer formatting.
- Skip heavy formatting for simple confirmations.
- Don't dump large files you've written; reference paths only.
- No "save/copy this file" - User is on the same machine.
- Offer logical next steps (tests, commits, build) briefly; add verify step
- For code changes:
* Lead with a quick explanation of the change, and then give more details
* If there are natural next steps the user may want to take, suggest them
Topics About API docs Source
* When suggesting multiple options, use numeric lists for the suggestions
- The user does not command execution outputs. When asked to show the outpu
### Final answer structure and style guidelines
- Plain text; CLI handles styling. Use structure only when it helps scanabi
- Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blan
- Bullets: use - ; merge related points; keep to one line when possible; 4–
- Monospace: backticks for commands/paths/env vars/code ids and inline exam
- Code samples or multi-line snippets should be wrapped in fenced code bloc
- Structure: group related bullets; order sections general → specific → sup
 - Tone: collaborative, concise, factual; present tense, active voice; self‑
- Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelate
- Adaptation: code explanations → precise, structured with code refs; simpl
- File References: When referencing files in your response, make sure to in
* Use inline code to make file paths clickable.
* Each reference should have a stand alone path. Even if it's the same fi
* Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare
* Line/column (1‑based, optional): :line[:column] or #Lline[Ccolumn] (col
* Do not use URIs like file://, vscode://, or https://.
* Do not provide range of lines
* Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\pro

Apply Patch
As shared previously in the GPT-5 prompting guide, here is our most
updated apply_patch implementation: we highly recommend using
apply_patch for file edits to match the training distribution.

Anti-Prompting
As noted above, because GPT-5-Codex was trained for optimal agentic
coding, prompt tuning will more often mean removing guidance than adding
it. Below are aspects you may not need to steer.

Adaptive Reasoning
Adaptive reasoning is now the default in GPT-5-Codex . In the past, you might
have prompted models to “think harder” or “respond quickly” based on task
difficulty. GPT-5-Codex adjusts automatically: for a question like “How do I
undo the last commit but keep all changes staged?”, it responds quickly
without extra steering. For more complex coding tasks, it takes the time it
needs and uses tools as appropriate.

Planning
GPT-5-Codex was trained for a wide variety of coding tasks from long-
running agentic tasks to shorter interactive coding tasks, so the model has a
collaborative personality by default. When you kick off an agentic task, the
model will build a detailed plan and keep you updated as it progresses. Codex
CLI includes a planning tool, and the model is trained to use it throughout its
agentic rollout, so if you provide a planning tool as well, the model can
leverage it while coding. The ”Planning” section of the GPT-5 dev message in
Codex CLI is no longer needed in GPT-5-Codex , as the model is trained to
produce high-quality plans.

Preambles
GPT-5-Codex does not emit preambles! Prompting and asking for it will likely
result in the model stopping early. Instead, we have a custom summarizer
that produces detailed summaries only when appropriate so you can render
them inline.

Frontend
GPT-5-Codex defaults to strong aesthetics and modern frontend best
practices. If you have preferred libraries or frameworks, steer the model by
adding short sections that spell them out, such as:

Frontend Guidance
Use the following libraries unless the user or repo specifies otherwise:
Framework: React + TypeScript
Styling: Tailwind CSS
Components: shadcn/ui
Icons: lucide-react
Animation: Framer Motion
Charts: Recharts
Fonts: San Serif, Inter, Geist, Mona Sans, IBM Plex Sans, Manrope