OpenAI Codex Guide (2026): App, CLI, IDE, Setup & Prompts

Codex is OpenAI’s agent for work with a checkable finish line. It can inspect a repository, edit files, run commands, use connected tools, and return a diff or finished artifact. This guide shows which surface to choose, how to set safe boundaries, and how to get useful work on the first run.

1. Start here: what to use and what to ask

If you want one recommendation, install the ChatGPT desktop app, open a small Git repository, choose a worktree, and give Codex a bounded task with an explicit verification step. The desktop app makes parallel work and review easier to see. The CLI and IDE extension are better when you already live in a terminal or editor.

Codex can do more than code. The product has expanded into general computer work, files, web research, connected apps, and repeatable tasks. Its strongest pattern remains the same: give it context, boundaries, and a definition of done.

2. What OpenAI Codex is in 2026

Codex is the agentic work mode in OpenAI’s product family. Unlike a plain chat response, an agent can inspect its environment, decide on a sequence of actions, edit files, run tools, observe results, and correct its work. You can use it through the ChatGPT desktop app, a terminal, an IDE, or OpenAI’s cloud service.

This naming deserves a clear note because “Codex” has referred to several things. OpenAI introduced an earlier code model under that name in 2021. The current product is an agent and its surrounding clients, environments, permissions, integrations, and coding-focused models. Treat old articles that describe Codex only as natural-language code completion as historical material.

Agent, client, model, and environment are different

• Codex agent: the system that reasons, calls tools, and works toward an outcome.
• Client or surface: the desktop app, CLI, IDE extension, web interface, or a product built on the SDK/app server.
• Model: the selected reasoning model, such as a member of the GPT-5.6 family. Models and access change more often than the workflow.
• Environment: where the work happens: your local checkout, an isolated Git worktree, or a remote cloud environment.

The distinction prevents a common mistake: choosing a model is not the same as setting permissions, and choosing “local” is not the same as granting unrestricted access. OpenAI documents sandbox boundaries and approval rules as separate controls.

What Codex does well

Codex is good at work where it can inspect the relevant material and test its answer: mapping an unfamiliar codebase, tracing a bug, implementing a focused feature, adding tests, checking a pull request, comparing documented behavior with code, or turning structured inputs into a reviewable artifact. It is less dependable when important context is hidden, the requested outcome is purely subjective, or it has no way to observe whether the result works.

3. Choose the right Codex surface

Decision rule: use the desktop app when you want to supervise several tasks, the CLI when the terminal is already the center of the job, the IDE when editor context matters most, and cloud when you want a repository task to run remotely. Use the SDK or app server only when you are building a system around Codex.

Beyond coding

The current product also reaches into Goals and long-running work, Sites, visualizations, browser-assisted work, notifications, voice, and reusable Computer History. Computer History replaced the earlier Chronicle preview; it should not be documented as a rename or as the same system. These features differ in maturity and platform coverage, so this guide focuses on the stable operating method rather than copying every release-note item. OpenAI’s feature index is the better live inventory.

For a deeper command reference after you have the basics, see Kingy’s OpenAI Codex command guide. For the broader product direction, see our guide to OpenAI Sites and app building.

4. Install Codex and get access

Desktop app

Download the ChatGPT desktop app for macOS or Windows. OpenAI also provides a Linux preview for supported distributions and processor architectures. Sign in, open a folder or project, and choose Codex when you want agentic work.

The Linux label matters: it is a preview, not a promise that every desktop feature or distribution behaves identically. Check the official Linux page before planning a team rollout.

CLI

OpenAI’s current recommended installers are:

# macOS or Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

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

The package-manager alternatives remain useful:

npm install -g @openai/codex
brew install --cask codex

Run codex in a project directory, then sign in with ChatGPT or configure an API key. ChatGPT sign-in connects the CLI to eligible subscription usage and cloud features. API-key access is suited to the CLI, SDK, IDE, and automation, but OpenAI says it does not include subscription cloud features. See the current CLI guide and authentication guide.

IDE

Install the official Codex extension in VS Code or a compatible editor such as Cursor or Windsurf. OpenAI also documents integrations for JetBrains IDEs and Xcode. Sign in, open the Codex panel, and confirm which files and repository root are in scope. Use the official IDE documentation for the current marketplace links and platform notes.

Cloud

Open Codex on the web, connect an eligible GitHub repository or GitLab Beta project, configure the environment, and delegate a task. Cloud work occurs in an isolated environment. Setup scripts, dependencies, secrets, and network rules therefore need deliberate configuration; do not assume your laptop’s state exists in the cloud. OpenAI’s cloud guide is the source of truth.

5. Your first useful Codex task

A good first run should be small enough to review and real enough to expose your environment. A documentation fix, a focused test, or a low-risk bug with a reproducible symptom is ideal.

1. Start from a clean, version-controlled folder. Commit or stash unrelated changes so the resulting diff is attributable.
2. Choose Local or Worktree. Pick a worktree when you want isolation or plan to run several tasks in parallel.
3. State the outcome and scope. Name the relevant files, behavior, constraints, and anything Codex must not change.
4. Define proof. Ask for targeted tests, a build, a screenshot, citations, or another result you can inspect.
5. Review the plan and permissions. If an action needs broader access, judge that action, not the fluency of the explanation.
6. Inspect the output. Read the diff, verify commands actually passed, and test the user-visible path before merging or publishing.

Try this:

Inspect this repository before editing. Explain the relevant execution path,
then fix [specific symptom] with the smallest maintainable change.

Boundaries:
- Work only in [files or directory].
- Preserve public behavior except for the stated bug.
- Do not add a dependency unless the existing stack cannot solve it.
- Stop and ask before any external write, destructive command, or secret access.

Done means:
- Reproduce or explain the failure.
- Add or update a focused test.
- Run the narrow test, then the relevant broader check.
- Summarize the cause, changed files, evidence, and residual risk.

The prompt does not tell the agent every keystroke. It makes the decision boundary and acceptance test explicit.

6. How to prompt Codex for reliable work

OpenAI’s prompting guide emphasizes the same ingredients experienced teams use in a ticket: goal, context, constraints, and verification. The practical version is a five-part brief:

1. Outcome: what should be true when the task ends?
2. Context: which files, symptoms, users, sources, or decisions matter?
3. Boundaries: what may change, what must remain untouched, and which actions need approval?
4. Definition of done: which observable checks prove the outcome?
5. Handoff: what should the final report include?

Use evidence-bearing verbs

“Check,” “measure,” “compare,” “reproduce,” “cite,” “render,” and “run” create observable work. “Improve,” “modernize,” and “make world class” describe direction but not completion. Keep the ambition, then add the proof:

• Instead of “improve performance,” ask Codex to profile the slow route, report the baseline, change the dominant cause, rerun the same measurement, and flag measurement limits.
• Instead of “clean up the UI,” name the viewport, target flow, design constraints, accessibility checks, and screenshots required.
• Instead of “research this,” define the questions, date window, acceptable sources, citation rule, and output format.

Prompt recipes

Map this repository for a new maintainer. Read the root instructions first.
Identify entry points, important data flows, build/test commands, deployment
path, and the five files most likely to matter for [feature]. Do not edit.
Support each claim with a file path and line. End with three low-risk starter tasks.

Review the current branch against [base]. Focus on correctness, security,
backward compatibility, and missing tests. Ignore personal style preferences.
For each finding, give severity, exact file/line, failure scenario, and smallest
credible fix. If there are no actionable findings, say so and list what you checked.

Answer [questions] using current primary sources. Record source, publication or
update date, access date, and the exact claim supported. Separate documented fact,
your inference, and anything unverified. Prefer official documentation and release
notes. Produce a concise recommendation plus a claim-to-source table.

Implement [user outcome] within [scope]. First inspect existing patterns and state
your plan. Preserve [constraints]. Add focused tests and verify the complete user
path at [viewports/environments]. Show the final diff, test results, screenshots,
and any behavior you could not verify. Do not deploy.

Repository-wide standing instructions belong in AGENTS.md, not in every prompt. Kingy has a separate guide to AGENTS.md.

7. Codex models and reasoning effort

Model names change faster than the working method, so check OpenAI’s current model page before standardizing a team configuration. As checked on September 21, 2026, OpenAI recommends Astra, Sol, Terra, and Luna. Availability and Power controls depend on the plan, sign-in method, client, and rollout.

GPT-5.3-Codex-Spark is no longer available in the desktop app, CLI, or IDE extension. See the September 14 deprecation notice.

GPT-5.5 retires from ChatGPT, ChatGPT Work, and Codex on October 14, 2026. For ChatGPT sign-in, replace saved gpt-5.5 selections with gpt-5.6-sol, including scheduled tasks. The OpenAI API is unaffected. See OpenAI’s migration guidance.

Reasoning effort is a cost and latency control

Start with the default. Increase effort when the task needs deep dependency tracing, ambiguous diagnosis, architecture trade-offs, or a final security/release review. More reasoning can improve hard work, but it takes longer and consumes more usage. It does not repair missing context or turn an untestable brief into a testable one.

OpenAI describes Ultra as a multi-agent mode that splits suitable work across subagents. Use that when independent lanes exist, such as researching several subsystems or running implementation and evaluation in parallel. Sequential work with one narrow dependency chain may gain little from it. Max is better understood as deeper single-agent effort. Most routine tasks need neither.

8. Codex plans, usage, and API billing

OpenAI changes allowances and promotional access, so treat this table as a dated snapshot and verify the official pricing page before buying. Prices below are listed in US dollars and were checked September 3, 2026.

ChatGPT Work and Codex share usage. A long Codex task, a high reasoning setting, large repositories, and repeated tool calls can draw more heavily on the same allowance. OpenAI exposes current usage in the account’s Codex usage settings; treat the dashboard, not a third-party estimate, as authoritative. The pricing page lists Free and Go but does not spell out their Codex feature and quota matrix in the same detail as paid tiers, so confirm the controls shown in your account.

Subscription and API billing solve different problems. ChatGPT sign-in is convenient for an individual using the desktop app, CLI, IDE, and eligible cloud features. An API key is easier to meter and control in CI or an internal service. Never place a personal key in a repository, prompt, screenshot, or shared shell history.

9. Environments, permissions, and the safe operating model

Codex is useful because it can act. That makes boundaries part of the product, not an advanced afterthought.

Local, worktree, or cloud

For repository work, a worktree is the best default when the client offers it. It gives each task a separate checkout while sharing Git history. OpenAI’s worktree guide explains handoff, ignored-file inclusion, branch rules, and cleanup.

Sandbox and approvals solve different problems

The sandbox defines what spawned commands can reach. The approval policy decides when Codex must stop and ask before crossing a boundary. OpenAI’s common local “Auto” pattern combines workspace write access with on-request approvals. In a version-controlled folder, this lets the agent inspect, edit, and test inside the workspace while asking before broader file or network access.

Older configurations using approval_policy = "untrusted" can prevent startup. Follow the migration instructions; trust_level = "untrusted" is a separate project setting.

A practical permission checklist

• Use Git and inspect the starting status.
• Keep secrets outside prompts and tracked files.
• Grant the smallest filesystem and network scope the task needs.
• Read command, target, and consequence before approving an escalation.
• Require a separate decision for production, deployment, publication, purchases, and external messages.
• Review the diff and run an independent check before merging.
• Assume web pages, issue text, files, and tool output may contain hostile instructions.

For managed organizations, review OpenAI’s agent approvals and security guidance alongside your own identity, retention, audit, and incident-response requirements.

10. Customize Codex without creating a maintenance trap

AGENTS.md: durable repository instructions

AGENTS.md tells Codex how work should happen in a repository. Put stable facts there: test commands, architectural boundaries, naming conventions, directories that must not change, and what evidence a completed task needs. Instructions can be layered from a global file through repository and subdirectory files. Keep them short enough to audit and update them when the project changes. See OpenAI’s AGENTS.md documentation.

# Working agreement
- Run `npm test -- --runInBand` for unit tests.
- Do not edit generated files under `dist/`.
- Public API changes require a migration note.
- Before completion, run lint plus the smallest relevant test suite.
- Never deploy or contact external systems without current user approval.

Skills, plugins, MCP, and hooks

• Skills package reusable instructions, scripts, references, and assets for a repeatable job.
• Plugins can bundle skills, connectors, and MCP servers into an installable capability.
• MCP connects Codex to external tools and data through the Model Context Protocol. Treat every server’s permissions and output as part of your trust boundary.
• Hooks run configured logic at defined lifecycle points. Keep them deterministic, fast, and visible to maintainers.

Start with plain repository instructions. Add a skill when a procedure repeats and needs resources or scripts. Add MCP only when the task truly needs an external system. Plugins are not supported in the IDE extension, although direct MCP configuration is. The official entry points are skills and plugins, MCP, and hooks.

Subagents and parallel work

Subagents help when work divides into independent, bounded lanes: audit frontend and backend changes separately, research several primary sources, or run implementation and adversarial review in parallel. Give each lane a concrete output and prevent multiple agents from editing the same files without coordination. OpenAI documents subagent configuration and handoff in its subagents guide.

Scheduled tasks

The desktop app can schedule work against a local project or a Git worktree. The computer must remain on and the app must be running when a task needs local files. Web and mobile can also run eligible scheduled tasks with uploaded context or connected tools, but they cannot directly use a folder on your computer. The CLI and IDE extension do not provide the scheduling management interface.

Unattended work deserves narrower access and a stricter output contract, not broader authority. A good scheduled task monitors, prepares a local candidate, and alerts on a material change. It should not silently deploy, publish, delete, or message people. See the official scheduled tasks guide.

11. Five practical Codex workflows

1. Repository onboarding

Ask for a read-only map with cited file paths, entry points, data flow, test commands, and uncertainty. Then verify the map against the actual build scripts and one execution path. This is faster and safer than asking for immediate refactoring.

2. Reproduce, fix, and prove a bug

Provide the symptom, environment, expected behavior, and reproduction evidence. Require a failing test or a concrete explanation if the failure cannot be automated. Ask for the smallest fix, the narrow test, and then the relevant wider suite. The final report should separate root cause from changed behavior.

3. Review a change

Give Codex the base branch and risk priorities. Ask only for actionable findings with severity, exact location, failure scenario, and fix. A review that finds nothing should say what was checked. OpenAI also offers cloud code review for supported repository workflows.

4. Run a multi-lane audit

Split independent questions, not arbitrary chunks. One agent can inspect implementation, another tests and failure cases, and a third current documentation or security controls. Have a lead reconcile contradictions and produce one prioritized result. For a detailed competitive framing, see Kingy’s Codex versus Claude Code comparison.

5. Maintain a living document or page

Create a claim ledger with source, date checked, volatility, and the exact section it supports. Schedule a read-only freshness check against primary sources. Notify only when a material claim changes. Prepare a minimal patch and require a human publication decision. Keep a visible update log so readers can distinguish a substantive re-review from a changed date.

If you need an auditable interface for repeated actions, Kingy’s Codex record-and-replay guide covers another useful pattern.

12. Troubleshooting Codex

Codex edits the wrong files

Stop the run. Check the project root, Git status, writable roots, active worktree, and applicable AGENTS.md files. Restore through Git or your backup only after you understand which files changed. On the next attempt, name the allowed directory and forbidden paths in the prompt.

It keeps asking for permission

Read the request. Repeated prompts often reveal that the task needs network access, a file outside the selected workspace, or an untrusted command. Configure the narrow recurring need if you understand it. Do not switch to unrestricted mode solely to remove friction.

The result looks confident but fails

Ask what was actually run and inspect the raw output. “Implemented” is not evidence. Require the exact test, build, browser path, data query, or source citation. If the environment cannot perform the check, the handoff must label it unverified.

The cloud task cannot build the project

Assume environment drift first: missing setup script, language version, package registry access, service, environment variable, or secret. Recreate only what the task needs. Avoid copying a developer machine wholesale into a remote environment.

The CLI command or model name is rejected

Check codex --version and codex --help, then compare the installed client with the current Codex changelog and model page. Update through the same installer or package manager you used. A documented rollout may not yet be enabled for your account.

The task runs out of context or wanders

Reduce scope, point to the smallest relevant files, put durable facts in AGENTS.md, and turn a long program of work into checkpoints with observable outputs. Start a fresh task when old exploration is no longer useful context.

13. Frequently asked questions

14. How this living guide is maintained

A living page needs more than a recent date. Kingy’s update standard for this guide is:

• Review volatile claims weekly against primary OpenAI sources.
• Update the visible date only after a substantive source check.
• Record material changes to models, pricing, platforms, commands, deprecations, security controls, or availability.
• Keep stable guidance separate from fast-moving release details.
• Label documented fact, Kingy inference, and direct testing distinctly.
• Test outbound links and inspect desktop and mobile rendering after publication.

Verification note

For the September 21 review, Kingy compared the live article with OpenAI’s current product guides, pricing, model page, security guidance, feature maturity policy, and changelog. Public cached and uncached CDN requests returned matching article content. The earlier September 3 review also checked locally installed Codex CLI help; that command check was not repeated in this review. This is documentation verification, not a benchmark of model quality or every platform.

Change log

Primary source map

• OpenAI Codex overview
• ChatGPT desktop app
• Codex CLI
• IDE extension
• Codex cloud
• Models
• Pricing and usage
• Local, worktree, and cloud modes
• Sandboxing
• Agent approvals and security
• Prompting
• AGENTS.md
• Skills and plugins
• MCP connections
• Subagents
• Scheduled tasks
• Code review
• Codex SDK
• App server
• Security
• Changelog
• Feature maturity

Editorial note: Product access and prices can vary by account, region, rollout, and workspace policy. This page is independent editorial guidance and is not an OpenAI support or policy document. When a current product control matters, follow the linked primary source.