Codex CLI workflow for local product development (2026)

Start in the source-of-truth checkout

Launch Codex from the repository and environment that actually builds the product — not a copy, not a stale mirror. Give it the outcome, the constraints and the verification command in the first message. Ask for diagnosis before implementation when the cause is uncertain, and keep production writes, credential use and external publication outside the task unless you have explicitly authorized them.

cd ~/src/app
codex                      # interactive session in this checkout
codex --cd ~/src/other-app # or point it at a different repository

A good first task has an observable failing case, a named scope, and a command that proves the fix. A bad first task is "clean this up". If you cannot describe success without quoting the agent’s own explanation back at yourself, the task is too big — the same discipline the repeatable task loop applies to any agent.

The commands worth memorising

Two flags change what a run can see: --image brings visual context into the prompt, and --search switches a run to live web search. Both widen the blast radius of a task, so decide on them deliberately rather than leaving them on by habit.

Configure it once in config.toml

User-level settings live in ~/.codex/config.toml, and a project can override them with its own .codex/config.toml. Putting the safe defaults in the user file and the project-specific ones in the repository means a new checkout behaves correctly on the first run rather than the third.

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

Named permission profiles save you from re-deciding this per task. Codex ships :read-only, :workspace and :danger-full-access, and you can define your own with [permissions.<name>] tables and a matching default_permissions. Select one for a run with --profile.

When a setting does not seem to apply, the precedence order is the answer, highest first: CLI flags and --config overrides, then project config files with the one closest to your working directory winning, then a profile file selected with --profile, then the user config, then cloud-managed defaults, then a system config if present, then built-in defaults. /status inside the session shows what actually resolved.

Approvals and sandboxing are the risk boundary

Match the boundary to the consequence, not to your patience. Routine local edits inside one package need far less ceremony than network access, credential use, destructive commands, or anything that reaches production. The three sandbox modes exist so that a read-only investigation and a write-heavy migration are not the same grant.

• Use read-only for diagnosis and code review, where the useful output is an explanation rather than a diff.
• Use workspace-write for ordinary implementation, so edits stay inside the checkout you opened.
• Reserve danger-full-access for a specific, supervised reason, and turn it off again when that reason is done.
• Inspect the proposed command rather than approving a broad capability by habit — approval_policy = "never" removes the prompt, not the consequence.
• Preserve unrelated dirty work, prefer reversible steps, and run the final checks in the authoritative environment.

AGENTS.md is the repository’s standing brief

Codex reads AGENTS.md from the repository, and /init will write a first one for you. Treat it the way you would treat onboarding notes for a contractor who is competent but has never seen this codebase: what the source of truth is, which commands verify a change, what must never be touched, and which parts of the tree are generated.

The build and test commands that actually gate a change
Which directories are generated, and what regenerates them
The smallest check that covers a typical edit
Work that requires explicit authorization (deploys, migrations, publishing)
Conventions a reader cannot infer from the code

Keep it short and current. A long file costs context on every session and goes stale faster than anyone updates it. Durable guidance belongs here; a one-off instruction belongs in the prompt.

Non-interactive runs

codex exec is the same agent without the conversation, intended for repeatable workflows and pipelines. It is what turns a task you have run by hand three times into a script — a pre-commit check, a scheduled dependency sweep, a CI step that comments on a diff.

codex exec "Run the test suite and summarise only the failures, with file and line."

Give a non-interactive run a narrower sandbox than you would give an interactive one. Nobody is watching it, so the approval prompt that would have saved you is not going to fire. Decide its permission profile deliberately and keep its scope to something you can verify from the output.

Resume with evidence

codex resume returns you to a saved chat from the current repository, which only helps if the session ended in a state worth returning to. A useful session record names the task, the repository and branch, the files that changed, the checks that ran, and the one decision still outstanding. Ask for that summary before you close the terminal, not after.

Summarise for the next session: what changed and why, the branch,
the commands run and their actual results, what you could not verify,
and the next unresolved step.

CmdBrief keeps that local session metadata and bounded previews beside the product it belongs to, across Claude Code, Codex, Grok CLI, Kimi CLI, OpenCode and Cursor CLI, so returning to the right thread does not depend on remembering which terminal tab it was in.

Which model, and what it costs

Codex runs on the GPT-5.6 family — Sol, Terra and Luna — and the tier you get is set by your ChatGPT plan. On the Terminal-Bench 2.1 leaderboard, which scores the harness and model together over 89 command-line tasks, Codex CLI entries run from 87.4% ±0.9 with GPT-6 Astra down to 75.7% ±1.3 with GPT-5.6 Luna. Picking the cheap tier for a hard task is the most common way to make a CLI look worse than it is.

Where Codex sits beside the others

Codex and Claude Code overlap almost completely in shape and differ in the details that matter operationally: the config file, the permission vocabulary, the instruction filename. If you are deciding between them, the benchmark, cost and trial comparison has the current figures and a scorecard. If you already have both, run them in parallel worktrees rather than in the same directory — two agents and one checkout is how you get a diff neither of them can explain.

Primary sources

Provider terms and product behavior can change. Confirm plan, pricing, model, and permission details in the current official documentation.

• 01Codex CLI documentationlearn.chatgpt.com
• 02Codex configuration filelearn.chatgpt.com
• 03ChatGPT and Codex pricinglearn.chatgpt.com
• 04OpenAI Codex documentationdevelopers.openai.com
• 05Terminal-Bench 2.1 leaderboardsnorkel.ai