The Five Surfaces

Before you install anything, understand where Codex lives. The surface you choose determines how closely you follow its work and where the code runs.

CLI is for scripted workflows, single-task work, and headless automation. Your code never leaves your machine unless you push it. Open source, built in Rust, runs on macOS, Windows, and Linux.

IDE extension is for interactive editing with precise file context. Installs in VS Code, Cursor, Windsurf, or JetBrains. Uses your CLI auth with no separate login.

Desktop app is the home of multi-thread workflows, the in-app browser, Computer Use, Goal mode, Appshots, and Automations. Launched on macOS in February 2026 and Windows on March 4, 2026.

Cloud is for async background tasks, parallel PRs, and work while you sleep. Tasks run in sandboxed containers preloaded with your GitHub repo. Nothing blocks your local machine.

In-app browser and Computer Use is for UI verification, frontend iteration, and end-to-end testing. Codex opens your local dev server, interacts with it, screenshots the result, and verifies that code changes produced the correct visual output.

A real workflow uses multiple surfaces:

  • CLI for scripted things

  • IDE for interactive feature work

  • Cloud for parallel tasks you do not need to watch

  • App for Goal-driven, long-running tasks

The main factor in choosing a surface is how closely you want to follow the agent's work. If you want to monitor changes as they are made, the CLI or IDE keeps the work on your machine and in front of you. If you would rather delegate a longer session and review at the end, Cloud is the right call.

The Mental Model: Agent, Not Autocomplete

With the surfaces clear, the next shift is understanding the unit of work.

The unit of work is a task, not a turn. The output is a PR, not a chat response.

Think less "write a function that does X" and more "implement feature Y, here are the constraints, run the tests when done."

Every Codex task follows the same internal loop. Codex reads your task and context, produces an internal plan, executes step by step, and checks its own work.

Stop thinking of Codex as a coding assistant. Start thinking of it as a junior engineer team you brief in the morning and review in the afternoon.

One real-world example of this in practice: developers at WorkOS now queue up four to five Codex tasks before they grab their morning coffee. By the time they sit back down, two to three completed PRs are waiting for review, handling the maintenance work that used to consume 30 to 40 percent of their day.

The current models as of May 2026:

  • GPT-5.5 (default) — handles most tasks, same latency as before but significantly fewer tokens for the same work

  • GPT-5.3-Codex — purpose-built for long autonomous runs, big refactors, and parallel cloud fan-out; 25% faster than the previous Codex specialist

  • GPT-5.5 Pro — highest reasoning; Pro, Business, and Enterprise plans only

  • Codex Mini — permanently free on ChatGPT Free; suitable for learning

Leave Codex on GPT-5.5 by default. Switch to GPT-5.3-Codex for big agentic tasks where Codex runs autonomously for a long time.

Getting Started: Your First Real Session

The fastest path to a working Codex session follows five steps. Forget the fizzbuzz tutorial. Start on a real codebase.

Step 1: Install the CLI.

bash

On Mac or Linux:
curl -fsSL https://chatgpt.com/codex/install.sh | sh

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

Or via npm: npm i -g @openai/codex

Step 2: Open a real project.

Navigate to a low-risk repository you are already familiar with. This matters.

Codex performs better when you can recognize the output and catch mistakes. First-session work on an unfamiliar codebase produces unpredictable results.

bash

cd your-existing-project
codex

Sign in with your ChatGPT account when prompted. Your browser opens automatically. Click Continue and return to the terminal.

Step 3: Run /init before doing anything else.

This single command is what most tutorials skip. Codex scans your directory and Git history, identifies languages, frameworks, build commands, and test commands, and scaffolds an AGENTS.md file populated with what it finds.

bash

/init

Review the generated file, adjust anything that is wrong, and commit it. Every future Codex session on this project will read it automatically.

Step 4: Give Codex an orientation task.

Ask it to explain the codebase before giving it something to change. This builds your confidence in what context it has loaded:

markdown

> Explain how authentication works in this project. Walk me through the relevant files and the flow from login to session creation.

Read the output. If it describes your actual codebase accurately, it has the context it needs. If it is vague or wrong, your AGENTS.md needs more detail.

Step 5: Give it one small, real task. Pick something concrete and bounded.

markdown

A real example from production use:

> Add stronger credit card number validation to the checkout flow.
> Card numbers must contain only digits after removing spaces and dashes,
> must be 12 to 19 digits long, and must pass a Luhn check.
> Keep the change minimal and consistent with the existing code style.
> Write tests that cover valid and invalid card numbers and run them before finishing.

This is the correct shape of a Codex prompt: specific file context, expected outcome, constraints, and a defined verification step. Review the diff it returns. You are now using Codex properly.

Step 6: Install the desktop app. Download from the OpenAI website. Sign in with the same ChatGPT account.

Step 7: Install the IDE extension. Search "OpenAI Codex" in your editor's extensions panel. It reads your CLI auth automatically.

Step 8: Connect GitHub. Go to Settings inside the Codex app and connect your GitHub account. Link at least one repository before using cloud tasks.

Where things live:

  • ~/.codex/config.toml : main config: approval mode, sandbox mode, MCP servers, model defaults

  • ~/.codex/AGENTS.md : personal AGENTS.md, applies to all projects

  • <project>/AGENTS.md : project-level instructions

  • <project>/.agents/skills/ : project-level Skills

  • <project>/.codex/config.toml : project-scoped config (trusted projects only)


AGENTS.md: The Most Important File in Your Repo

Now that you have a working session, the next step is making every future session start with the same quality. That is what AGENTS.md does.

  1. 1.

    AGENTS.md is the single file that separates mediocre Codex output from consistent, high-quality output.

  2. 2.

    It is a plain Markdown file at the root of your repo. Every time a Codex session starts on your project, the agent reads it automatically before doing anything else.

  3. 3.

    It is an open standard. Codex, Cursor, Gemini CLI, Windsurf, and GitHub Copilot all read it. Write it once and every agent in your toolchain reads the same source of truth.

Resolution order: Codex reads ~/.codex/AGENTS.md (home level, all projects) plus <project>/AGENTS.md (project level). AGENTS.override.md files take priority at each level. Combined limit is 32 KiB.

What goes in:

  • Stack, frameworks, language versions, package manager

  • Exact build, test, and dev commands; copy-pasteable, not "run the usual tests"

  • File structure conventions and naming rules

  • Style and pattern rules

  • Forbidden zones: what not to touch

  • Shipping requirements: CI, PR conventions, deploy mechanism

What does not go in:

  • Secrets or credentials (the file is in version control)

  • Vague guidance ("write clean code" means nothing to an agent)

  • Documentation that duplicates your README

Keep it under 500 words. Bloat pushes useful context out of the model's working memory.

A working template:

markdown

# Project DNA

## Stack
- Next.js 15 (App Router), TypeScript strict
- Tailwind CSS + shadcn/ui, Supabase, SWR

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
- Lint + fix: pnpm lint:fix
- Type check: pnpm typecheck
- Build: pnpm build

## Conventions
- kebab-case files, PascalCase components
- Server components by default; "use client" only when needed
- Data fetching only via /lib/data wrappers
- No direct Supabase calls from components
- No "any" types. Strict TS.

## What NOT to touch
- /lib/billing (Stripe). Ask before modifying.
- /supabase/migrations. Never edit existing migrations.

  • Verify Codex is reading it: prompt summarize the current instructions you have loaded

  • For large monorepos, place additional AGENTS.md files inside subdirectories.

  • A file at packages/api/AGENTS.md takes precedence over the root-level file for tasks inside that package.

  • Run codex trust . to enable a project-level .codex/config.toml. This prevents a malicious cloned repo from configuring Codex behind your back.

The CLI in Depth

With AGENTS.md set up, the next thing to master is the CLI itself. Most users only ever type codex and miss the commands that make it genuinely powerful.

There are four commands that cover 95% of real daily use.

codex opens interactive mode for exploration, iteration, and back-and-forth conversation with your codebase.

codex exec "<task>" runs Codex non-interactively. It streams to stdout and exits when done. This is the power tool for anything scriptable:

bash

codex exec "add jsdoc to all exported functions in /src/lib/format.ts"
codex exec --json "audit dependency security and report as markdown"
cat error_log.txt | codex exec "explain this stack trace and propose a fix"
git diff HEAD~1 | codex exec "explain this diff in plain English"
codex exec --model gpt-5.3-codex "refactor /lib/data to use SWR everywhere"

Wire exec into git hooks, CI pipelines, and cron jobs. It is the building block for everything automated.

codex resume --last picks up exactly where you left off. Every session is stored:

bash

codex resume --last "now do the follow-up"
codex resume --last "now write tests for the function you just added"
codex resume --all   # search all sessions across directories

codex cloud manages async cloud tasks, covered in the Cloud section below.

Useful flags:

  • --json : JSONL event stream for piping to other tools

  • --model <name> : select GPT-5.5 or GPT-5.3-Codex

  • --reasoning evel> : low, medium, or high

  • --search : allow web search during the task

  • -C <dir> : run in a different working directory

  • --sandbox <mode> : override sandbox mode for this session

  • --approval <policy> : override approval policy for this session

Sandbox and Approvals

The CLI gives you power. The sandbox controls how much of that power Codex can exercise without asking. Getting this right keeps your workflow fast without creating risk.

The sandbox is the boundary that controls what Codex can and cannot do. Setting it correctly prevents surprises.

The three sandbox modes:

  1. 1.

    workspace-write (default) : read and write inside the workspace, routine commands, no network unless allowed. Use this almost always.

  2. 2.

    read-only : read only, no writes, no shell. Use for code review and exploration.

  3. 3.

    danger-full-access : no restrictions. Use almost never. Reserve for tested, verified automations.

The two approval policies:

  • untrusted — asks before every non-trusted command. Use when learning or in an unfamiliar project.

  • on-request (default) — auto-approves routine sandboxed commands, asks before anything that breaks the sandbox boundary.

auto_review is a reviewer sub-agent that auto-approves or rejects based on your AGENTS.md. Enable it with approvals_reviewer = "auto_review" in config. Works well for long async tasks and Goal mode where you do not want to babysit every step.

bash

Starter ~/.codex/config.toml:
sandbox_mode = "workspace-write"
approval_policy = "on-request"
model = "gpt-5.5"
reasoning_effort = "medium"

[approvals]
trusted_commands = [
  "git status", "git diff", "git log",
  "pnpm install", "pnpm test", "pnpm lint", "pnpm typecheck"
]

Add commands that constantly nag you for approval. Never add anything destructive.

Prompting Codex Effectively

Sandbox configured, sessions running. The next lever is prompt quality, which has more impact on output than any other variable.

The single biggest lever on Codex output quality is prompt structure. Vague prompts produce vague code.

The framework: Tell, Show, Describe, Remind.

  • Tell it the outcome you want, not the method

  • Show it example inputs and expected outputs

  • Describe the APIs, libraries, and patterns to use

  • Remind it of conventions from AGENTS.md

Not all four are needed every time. A small bug fix might only need Tell and Remind. A new feature usually wants all four.

  1. 1.

    The single-change rule: Codex performs dramatically better on one thing than five. "Fix the auth bug, add tests, refactor the user repo, and update the README" is a coin-flip. The same work split into four prompts is reliable.

  2. 2.

    Force a plan first for anything non-trivial: "produce a plan first, do not write code until I approve." Thirty seconds reviewing a plan beats thirty minutes debugging a wrong implementation.

  3. 3.

    Specify failure behavior explicitly. Left to itself, Codex will make tests pass by any means necessary:

markdown

If tests fail after your initial implementation:
- DO NOT modify the test to make it pass
- DO NOT add try/catch to hide the error
- Stop, write a summary of what failed and why, wait for my input.

Constrain context explicitly. Name specific files to read. "Do not read or modify anything else. If you need information from elsewhere, ask me."

Reasoning effort levels:

  • Low : trivial edits, formatting, simple refactors

  • Medium (default) : most feature work and bug fixes

  • High : architecture decisions, hard debugging, big multi-file refactors

Goal Mode

Once single-task prompting feels natural, the next level is giving Codex a multi-day objective and letting it sequence the work itself.

Goal mode is for work too big to brief task-by-task but coherent enough for a single objective. It became stable in May 2026.

bash

codex goal "Migrate the test suite from Jest to Vitest.
One PR per package, no PRs over 500 lines. Run tests after each PR.
Don't open the next PR until the previous passes CI.
Stop and report when all packages migrate."

Manage a running Goal with these commands:

  1. 1.

    codex goal status : see active Goals and their progress

  2. 2.

    codex goal logs <id> : inspect what Codex has done so far

  3. 3.

    codex goal pause <id> : halt execution and wait for your input

  4. 4.

    codex goal resume <id> : continue from where it paused

  5. 5.

    codex goal cancel <id> : stop and discard the Goal

Start with bounded Goals. "At most 5 PRs" until you trust how Codex interprets your objectives. A runaway Goal confidently doing the wrong thing is the worst-case outcome.

Always bound with: max PRs, max lines of code per PR, CI gates between PRs, and clear stop conditions. Pause on any architectural decision not covered in AGENTS.md. Pause on any breaking API change.

Skills: Reusable Workflows

Goal mode handles big initiatives. Skills handle the recurring micro-workflows that show up in every project. If you find yourself repeating the same instructions across sessions, that is your signal to write a Skill.

A Skill is a reusable workflow packaged as a directory: instructions in a SKILL.md file, plus optional resources and scripts.

Codex discovers Skills by name and description. It loads the full instructions only when a task triggers the Skill. You can have 50 Skills with zero context cost until one is triggered.

Where Skills live:

  • Personal :

  • Team : .agents/skills/ inside the repo : project-specific, version-controlled, shared with collaborators

The SKILL.md format:

markdown

---
name: open-pr
description: Standard PR-opening workflow. Use when the user asks
  to open a PR, push a branch, or finish a feature.
---

When opening a PR:
1. Confirm the working branch is not main.
2. Ensure at least one commit since main.
3. Push the branch to origin.
4. Open a PR with conventional commit title and structured body.
5. Apply labels and request review from codeowners.

The three Skills every power user should write first:

  1. 1.

    open-pr is the standard PR workflow: check the branch, push, create the PR with a structured body, apply labels, and request review. The single most used Skill in daily work.

  2. 2.

    new-feature reads the PRD and AGENTS.md, identifies existing components to reuse, outputs a plan, waits for approval, implements, tests, and opens a PR via the open-pr Skill. If anything in the PRD is ambiguous, it asks before generating code.

  3. 3.

    investigate is the diagnose-without-fixing Skill. It confirms reproduction, reads relevant code paths, forms a hypothesis ("I believe X happens because Y"), and outputs the hypothesis and validation plan as Markdown. It does not implement a fix. The output is understanding, not code.

The investigate Skill matters because Codex will skip root cause analysis every time if you let it. It will jump directly to a fix, and that fix will often be wrong. Enforcing investigate-first is the single biggest improvement to debugging output quality.

Verify your Skills are loaded: list available skills

Sub-agents and Parallelism

Skills handle your repeatable workflows. Sub-agents handle your parallel ones. The distinction matters because parallelism done wrong creates more problems than it solves.

A sub-agent is a separate, isolated agent instance. It runs in its own context, returns a summary, and its context is discarded. It is different from a Skill, which runs in the main agent's context.

Three patterns where sub-agents are the right tool:

  1. 1.

    Exploration : spawn a sub-agent to read 30 files and summarize; the reading happens in its context, not yours

  2. 2.

    Parallel implementation : five independent features as five concurrent sub-agents, each with its own context and plan

  3. 3.

    Verification : a fresh reviewer sub-agent is not biased by having just written the code

Custom sub-agents are defined in .codex/agents/<name>.md:

markdown

---
name: code-reviewer
description: Senior-engineer code review of a diff or PR.
model: gpt-5.5
reasoning_effort: high
tools: [read, grep, bash]
---

You are a senior engineer reviewing code for clarity, correctness,
and conformance to AGENTS.md.
Output: must fix, should fix, nice to have.
Be terse. Quote line numbers. Suggest fixes.

  • Sub-agent addressing shipped in March 2026. Talk to a running sub-agent by nickname with @<nickname>.

  • Useful when several are running in parallel and you want to redirect one without disturbing the others.

  • The fan-out pattern: spawn N sub-agents in parallel on independent tasks and fold results back.

  • Five tasks complete in the time the slowest one takes. Rule of thumb: if a task takes under 30 seconds in main context, just do it there.

The Desktop App: Codex for Everything

Sub-agents and Skills run equally well across the CLI, IDE extension, and desktop app. But the desktop app is where the features that have no CLI equivalent live.

The April 16, 2026 "Codex for (almost) everything" update transformed the desktop app from a coding tool into a full developer workstation.

Computer Use

Codex operates your Mac: clicking, typing, scrolling, opening apps, navigating menus, and running alongside you without stealing cursor focus.

  • The killer use is behavioral verification. Unit tests pass but the UI is still broken.

  • Computer Use closes that gap by letting Codex open the dev server, click through the relevant flow, and screenshot the result.

  • To activate it, go to Codex Settings, Computer Use, Install. Grant Screen Recording and Accessibility permissions when macOS prompts. Invoke it from any prompt:

markdown

@Figma open the landing page file and export the hero section at 2x

Locked computer use lets Codex continue operating desktop apps after your screen locks. Enable it in Settings under Computer Use. Start a task before bed, lock your machine, review the results in the morning.

Appshots

Press Command-Command and the frontmost macOS window goes directly into your Codex thread.

Codex captures the screenshot, visible text, and accessibility text; often including content scrolled off-screen.

  • Without Appshots: see an error, switch to Codex, type a question, take a screenshot, drag it in, type more context. Half a minute of friction.

  • With Appshots: see the error, press Command-Command, ask your question. Five seconds.

If you interacted with a Codex thread in the last 60 seconds, the Appshot goes into that conversation.

Otherwise it opens a new thread. Multiple Appshots in a session stack into one thread. Requires Screen Recording and Accessibility permissions.

The In-App Browser

The in-app browser is a native agentic browser, not a page preview. It opens your local dev server, clicks, fills forms, inspects DOM state, captures screenshots, and verifies that the patch just written fixed the visual bug.

  1. 1.

    Open a local development server inside it, then add natural-language comments directly on rendered elements.

  2. 2.

    Write "make this button 20 pixels taller" on the element, and Codex executes the change in your codebase and reloads the page.

  3. 3.

    The in-app browser provides direct DOM access with no window-management overhead and is sandboxed from your real browser.

Memory

Memory lets Codex retain context across sessions.

  • After each session ends, Codex summarizes the interaction and writes it to ~/.codex/memories/.

  • On the next session, it reads those files before loading your prompt.

  • Codex learns your preferred commit message format, testing frameworks, architecture patterns, and the mistakes it made last time; without you repeating any of that context.

  • Enable it in Settings, or add memories = true under [features] in config.toml.

The 90-Plus Plugin Ecosystem

Plugins are curated bundles of Skills, MCPs, and integrations. Install with codex plugins install <name>.

Key plugin categories:

  • Project management : Linear, JIRA, GitHub

  • CI/CD : CircleCI, Vercel, GitHub Actions

  • Databases : Neon, Postgres, PlanetScale

  • Code quality : Sentry, CodeRabbit

  • Productivity : Notion, Remotion

Install only for tools you use daily. Scope per-project where possible. Audit quarterly. Every plugin costs context tokens whether you use it or not.

Codex Cloud: Async Work at Scale

The desktop app powers your local and interactive work. Cloud is what you reach for when the work is too large for a single interactive session or when you want multiple tasks running in parallel while you focus elsewhere.

Codex Cloud is the feature that turns Codex from a fast coding assistant into a junior engineering team that scales horizontally.

Submit a task, Codex spins up a sandbox preloaded with your repo, works, runs tests, and opens a PR. Nothing blocks your local machine.

Submitting a single task:

bash

codex cloud submit --task "Add Sentry tags to /lib/integrations/stripe.ts"

Parallel tasks; the core pattern:

bash

codex cloud submit --task "fix typo in pricing page"
codex cloud submit --task "add loading state to SubscriberList"
codex cloud submit --task "update README setup section"
codex cloud submit --task "add Sentry tags to stripe.ts errors"

Twenty minutes later, four PRs are open. Review, triage, merge.

CSV fan-out lets you submit a file of tasks and Codex fans them out as parallel cloud agents with progress tracking:

bash

# tasks.csv
title,prompt
"Sentry tag billing","Add Sentry tags to /lib/integrations/stripe.ts errors"
"Sentry tag auth","Add Sentry tags to /lib/integrations/auth.ts errors"
"Sentry tag email","Add Sentry tags to /lib/integrations/resend.ts errors"

codex cloud submit-csv tasks.csv

codex cloud browses active and finished tasks. codex cloud apply <task-id> pulls changes locally before merging.

GitHub Integration

Cloud tasks land in your repo as PRs. The GitHub integration determines how those PRs are reviewed, and how Codex feeds into your existing CI/CD pipeline.

Codex and GitHub integrate at three levels: repository environments, pull request reviews, and codex-action for CI/CD.

Repository environments are the foundation. Link a GitHub repository in Codex Settings and cloud tasks will clone the repo, run tasks in a sandboxed container, and push the result as a branch or PR. AGENTS.md is read automatically for every cloud task.

Pull request reviews work two ways:

  • Mention

  • Turn on Automatic Reviews to have Codex post on every new PR without a manual trigger.

After Codex posts a review, ask it to fix the flagged issues directly inside the PR comment thread. It commits the fix to the same branch and updates the PR.

codex-action is an official GitHub Action that runs the Codex CLI inside your CI/CD pipeline on any trigger: push, schedule, issue creation, or PR open. This is the recommended way to integrate Codex into fully automated pipelines where no human is present.

Automations: Unattended Work

GitHub integration handles what happens when a human opens a PR. Automations handle what happens when no human needs to be involved at all.

Automations are scheduled Codex tasks running in dedicated worktrees. Set them up from the Automations panel: name, project, prompt, schedule, and execution environment.

Thread reuse shipped in April 2026. Automations can reuse a thread across runs, accumulating context and getting smarter over time.

Three starter automations that every project should have:

  1. 1.

    Weekly dependency review (Monday 6am): Run pnpm outdated and pnpm audit. Report critical, major, and minor findings. Auto-PR safe minor and patch upgrades. Do not touch critical or major updates; those need human decisions.

  2. 2.

    Daily Sentry triage (weekday 8am): Fetch the last 24 hours of errors grouped by fingerprint. For each group with 3 or more occurrences, identify the file and line, read relevant code, and identify the root cause. Post a triage report. Diagnosis only, no fixes.

  3. 3.

    Weekly stale-PR cleanup (Friday 5pm): List open PRs older than 7 days. For each, determine whether it is waiting on you, waiting on review, or gone stale, and post a nudge comment. Do not close or merge anything.

Kill any automation whose output stops being read. A good automation saves a recurring task you would definitely do anyway, produces a single scannable output, and does not take destructive action unattended.

MCP Integration

Automations work with what is in your repo. MCP servers extend Codex to work with everything outside it.

MCP (Model Context Protocol) is the open spec behind plugins. Use a plugin when one exists. Use raw MCP for custom integrations to internal tooling.

  • STDIO : Codex spawns a local process and communicates over stdin/stdout. Covers 95% of solo use.

  • Streamable HTTP : Codex connects to a network endpoint. Used for hosted team MCPs.

Adding a raw MCP server:

bash

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add postgres -- npx -y @modelcontextprotocol/server-postgres\
  postgres://localhost/myapp_dev
codex mcp list
codex mcp remove context7

Or directly in ~/.codex/config.toml:

bash

[mcp.servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Configure per-tool approvals: auto-approve reads, ask before writes. Every MCP server adds tool definitions to Codex's context, costing tokens and diluting attention. Only enable what you actually use.

Docker MCP Toolkit connects Codex to 220-plus pre-built servers with one command: docker mcp-client configure codex

Mobile App

MCP servers extend what Codex can reach. The mobile app extends where you can reach Codex.

On May 14, 2026, Codex arrived in the ChatGPT mobile app on iOS and Android.

Mobile Codex is a remote control and monitoring surface, not a code editor. The typical use case is checking on a long-running cloud task or Goal mode run from your phone while away from your desk.

From your phone, you can:

  • Watch live runs across laptops, devboxes, or connected remote environments

  • Browse threads and jump between parallel tasks

  • Review diffs before they merge into a branch

  • Approve or reject commands Codex wants to run on your hardware

  • Swap the model mid-task if a stronger one is needed

  • Start new tasks from a fresh prompt or directly from a GitHub issue

  • Comment on a pull request Codex opened

To set it up, update ChatGPT to the May 13, 2026 release or newer, sign in with the same desktop account, and ensure at least one cloud environment is configured in Settings under Codex, Environments. Mobile inherits all existing threads and connected hosts automatically.

The practical loop this enables: start a Goal mode run in the morning before leaving home, check its progress on your commute, approve a paused decision from your phone, and walk into the office with the first two PRs already open.

Chrome Extension

The mobile app extends your reach. The Chrome extension extends Codex's reach into any website you are already signed into.

  • This means it can access authenticated services: LinkedIn, Salesforce, Gmail, Workday, and any internal tool that requires login.

  • Install it by going to Plugins inside the Codex desktop app, adding the Chrome plugin, and following the guided setup.

  • The extension shows Connected status when active. Invoke it from any Codex thread:

bash

@Chrome open Salesforce and update the account from these call notes.

Codex can control multiple Chrome tabs via sub-agents across different threads, each tab isolated.

A major advantage over headless browser automation: the Chrome extension can access web developer tools. Codex can inspect the DOM, read console errors, and diagnose runtime issues in a live browser session. Works on both macOS and Windows.

The Codex SDK

The Chrome extension handles browser automation. The SDK handles programmatic automation; embedding Codex as infrastructure inside your own applications and pipelines.

The Codex SDK gives developers programmatic control over Codex from their own applications and CI pipelines.

Install the JavaScript SDK:

java

npm install @openai/codex-sdk

Basic usage:

javascript

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);
console.log(result);

  • Call run() again on the same thread to continue the conversation. Resume a saved thread with codex.resumeThread(threadId).

  • The Python SDK uses from codex_app_server import Codex. Pass a model name when starting: thread = codex.thread_start(model="gpt-5.5").

  • The SDK is currently experimental and requires a local Codex CLI installation.

  • It communicates with the local app-server over JSON-RPC; it controls the same agent you interact with in the desktop app.

Verification: How to Actually Trust Codex Output

All of the above surfaces produce output. Verification is what determines how much of that output you can actually ship.

Generation is solved. Verification is the bottleneck.

Five parallel cloud PRs is five chances to ship a bug. Without a verification layer, your throughput is capped by how fast you can read PRs.

The core issue is sycophancy. The model that wrote the code is biased to think it is correct. Ask it to review its own work and you get a thumbs-up most of the time.

Two structural fixes:

  1. 1.

    auto_review (in-Codex) is Codex's built-in reviewer sub-agent. Fresh context, no investment in the prior output, far more likely to flag real issues.

  2. 2.

    Cross-provider verification (gold standard) means Codex writes and Claude Code reviews. Cross-provider catches blind spots specific to one model family. This is the minimum-viable verification habit for production code.

Computer Use for behavioral verification closes the gap between "tests pass" and "the thing actually works." Have Codex open the dev server, click through the relevant flow, screenshot the result, and compare it against your PRD.

The minimum-viable habit on every PR: run an automated review with a different model before opening the diff yourself. Read the review summary first. Only open the diff when the review is clean; then read for taste, not correctness. For UI changes, look at the screenshot.

Recipes: Battle-Tested Patterns

Verification habits in place, here are the end-to-end templates for the tasks developers run through Codex most often.

  1. 1.

    Implement a feature: use the new-feature Skill. Read the PRD and AGENTS.md. Plan first, wait for approval. Tests for the happy path and one error case. If anything is ambiguous, ask before generating code.

  2. 2.

    Fix a bug: use the investigate Skill first. Diagnose only. Output reproduction steps, root cause hypothesis, and a validation plan. Do not fix until confirmed.

  3. 3.

    Refactor: list all locations with grep. Output the migration plan. Wait for approval. All existing tests must pass unmodified. If a test needs updating, the test is wrong; stop and report. One PR.

  4. 4.

    Third-party integration: wrap in /lib/integrations/[name].ts. Add env vars to .env.example. No UI in this PR. Open as draft for manual testing against the external service.

  5. 5.

    Test backfill: output the test plan covering happy, edge, and error cases. Wait for approval. All tests must pass against existing production code. Do not modify production code.

  6. 6.

    Dependency upgrade: read release notes between versions. List breaking changes. Wait for approval. Update and apply code changes. Run tests until clean.

  7. 7.

    Goal mode initiative: bound with max PRs, max lines of code per PR, CI gate between PRs, and clear stop conditions. Pause on architectural decisions not in AGENTS.md. Pause on any breaking API change.

Common Mistakes

These patterns cover the common wins. The section below covers the common losses; the ten mistakes that explain most bad Codex experiences.

1. Vague tasks. Name specific outcomes, files, and constraints. If you cannot be specific, the task is not ready to brief.

2. No AGENTS.md. Write one. Even a bad one beats none.

3. Skipping the plan. "Produce a plan first" on anything non-trivial.

4. Multi-task prompts. One task per prompt. Use sub-agents or cloud tasks for parallel work.

5. Starting with danger-full-access. workspace-write and on-request is the right default for everything except tested automations.

6. Too many MCPs and plugins. Keep the list lean. Disable what you do not actively use.

7. Self-review. Use auto_review or a different tool entirely. The model that wrote the code is biased toward it.

8. Trusting compile-success as correctness. Include behavioral verification. Use Computer Use for UI changes.

9. Over-parallelizing. Parallelize independent work only. Shared files must be serialized.

10. Unbounded Goals. Max PRs, max lines of code, max time, clear stop conditions. Goal mode is most useful with the leash you would give a junior engineer.

Quick Reference Cheat Sheet

CLI commands:

bash

codex : interactive mode
codex exec "<task>" : non-interactive one-shot
codex resume --last : continue the most recent session
codex resume --all : search all sessions across directories
codex cloud submit --task "<task>" : async cloud task
codex cloud submit-csv tasks.csv : fan out a CSV of tasks in parallel
codex cloud apply <task-id> : pull cloud task changes locally
codex goal "<objective>" :  start a bounded multi-task Goal
codex goal status / pause / resume / cancel : manage a running Goal
codex trust . : enable project-level config for this directory
/init : scaffold AGENTS.md for the current project
/new : start a fresh session in the current thread
/compact : compress context when approaching the limit
@filename : attach a file as context in the composer
Command-Command : Appshot: send the frontmost macOS window into the current thread

Key file locations:

  • Global config: ~/.codex/config.toml

  • Global AGENTS.md: ~/.codex/AGENTS.md

  • Project AGENTS.md: <repo-root>/AGENTS.md

  • Override file: AGENTS.override.md

  • Memories: ~/.codex/memories/

  • Skills (personal):

  • Skills (team): .agents/skills/ inside repo

  • Sub-agents: .codex/agents/<name>.md

The four-part prompt structure:

  1. 1.

    Tell : the outcome, not the method

  2. 2.

    Show : example inputs and expected outputs

  3. 3.

    Describe : the APIs, libraries, and patterns to use

  4. 4.

    Remind : conventions from AGENTS.md

Conclusion

After 12 months of using Claude, the breaking point was not one bad day. It was the accumulation of rate limits, workflow friction, and a desktop app experience that kept getting in the way.

That frustration is what pushed the shift to Codex.

  • Over the last 90 days, going deep into the OpenAI ecosystem has made one thing clear: Codex feels more complete as a working environment for serious developer workflows.

  • The agentic model is stronger, the surrounding surfaces are broader, and the system is easier to trust once AGENTS.md, Skills, Cloud, and verification loops are in place.

  • That does not mean Claude Code has no value. It means the trade-offs stopped making sense.

If Claude Code still works for your workflow, keep using it. But if you are tired of rate limits, brittle sessions, and tools that feel like they are fighting your process, Codex is now good enough to justify a serious switch.