OpenAI Codex Guide: Basics, Icons and Advanced Workflows

CHAPTER 01Understand the basics

Codex is OpenAI’s coding agent. It can inspect a codebase, explain how it works, make changes, and use tools to check the result. The desktop workspace also brings together files, research, previews, and connected tools; available capabilities depend on the surface, enabled tools, account, and permissions. You can begin by asking for an explanation without changing anything. OpenAI glossary, Using the desktop workspace.

Five terms to learn first

A chat contains its own conversation. A project keeps related work together. A folder contains files on disk. These concepts are related, but they provide different kinds of context. Projects and chats.

Choose a suitable first task

Start with something small enough to inspect yourself. Ask Codex to explain a folder, summarise a document you provide, improve a short passage, or create a simple practice file.

For your first attempt, keep the available model and reasoning defaults. You can tune them when you have a task whose speed or difficulty makes that choice useful. Current documentation describes both model and reasoning controls and, in some interfaces, a Power control with Faster, Smarter, and Advanced options. The choices depend on your account, client, workspace settings, and rollout. Models.

CHAPTER 02Your first local task

This exercise is a suggested practice workflow, not a report of a task already run on your computer.

Step 1 Choose a practice folder

Create an empty folder named Codex Practice using Finder. Add or open it as a local project in the app. On macOS, the documented Open folder shortcut is Command O when that operation is available in Codex. Use a practice folder so the files you create are easy to identify. Commands.

A local project is appropriate when Codex needs to read or change files on your computer. A project can have several attached folders; its primary folder sets the default working directory for new chats and the default repository for Git actions. Technical permissions still determine what commands can access. Local projects.

Step 2 Ask for an explanation

Send this prompt:

Explain what is in this practice folder.
Tell me which folder you are working in.
Do not create, edit, delete, or move any files yet.

Check that the reported location is the folder you intended. If it is wrong, correct the location before asking for changes.

Step 3 Create one small file

Create a file named practice-note.txt in this practice folder.
Give it the title “My first Codex task” and three short bullet points
explaining what I can practise here.
Show me the saved file and its location.

Open the output. Check the filename, title, and three bullet points. A message saying that a file was saved is a reason to inspect that file.

The desktop app can preview supported outputs alongside the conversation. Preview options vary by file type and available features. Work with files.

Step 4 Request a focused revision

In practice-note.txt, replace the second bullet point with a reminder
to review outputs before using them. Preserve the title and other bullets.
Show me the updated file.

Compare the new version with the request. This is the basic working loop: give a task, inspect the output, and ask for a specific revision.

Step 5 Understand permissions

A local command runs within technical access boundaries. The sandbox controls such things as permitted filesystem changes and network access. Approval controls govern when an action requires review or permission to proceed. A prompt can describe your intent, but it does not remove technical restrictions. Read an approval request for the action and scope it proposes. Sandbox.

CHAPTER 03A visual map of the desktop workspace

Select a region in the interactive map to see its role. This is a schematic: the exact arrangement and visibility of controls can differ by build, window size, and open panels.

1 Projects and chats

Use navigation to return to work or start another chat. Give chats names that describe the outcome, such as “Explain the checkout error” or “Draft the product FAQ.”

Start a separate chat when the outcome changes substantially. Keep related chats in a project when they need the same files or instructions.

The documented Codex New chat control beside Recents starts without a project. Quick chat opens an ordinary ChatGPT chat, whose chats do not appear in the Codex sidebar. The documented macOS Quick chat shortcut is Command Option N. Check the label when choosing between them. Projects and chats.

Pinning keeps a project or chat easy to find. It changes its placement, not the files or context it can access. Archived chats can be restored through Settings → Archived chats → Unarchive. Organising chats, Archived chats.

2 Activity and scheduled work

The sidebar bell opens Activity where available. It helps you find chats that are unread, running, or waiting for your response. On macOS, Command Option U opens or closes Activity. Notifications.

Scheduled is the place to review scheduled tasks and their runs. A run with findings can have an unread indicator because it needs attention. Its specific colour is not established by that documentation. Scheduling and automation setup will be covered in a later chapter. Scheduled tasks.

3 Conversation and tool activity

Read the conversation as a record of the request and the work:

• Your message describes the task or changes its direction.

• A progress update describes work underway.

• A tool result records an action or retrieved information.

• A question or approval request identifies input the task needs.

• A final reply reports the result and any unresolved limitations.

For a file task, open the file. For a code change, inspect the diff and relevant checks. For a research claim, follow the supporting source. An activity indicator tells you about the task’s state; the output tells you whether the result meets your request.

4 Composer and task controls

The composer is where you type a message and add relevant context. Type / to see the commands available in that environment. The command list can depend on access and enabled features. Type a dollar sign to explicitly invoke an available skill. Slash commands.

Your send key is configurable. Settings can make Enter send, or require Command Enter for some or all messages. Follow-up behaviour is also configurable: a message sent during work may steer the current run or wait for a later run. Check Settings → General before assuming what a follow-up will do. General settings.

Controls beneath or around the composer can select the model, reasoning, or execution environment. Read their current labels and available options; use the illustrated map to understand the role of each region.

5 Files and inspection panels

Use previews to examine supported generated files. For code, use the review pane to inspect the changes in a Git repository. The repository may contain edits made by you, Codex, or another process, so choose the review scope deliberately. Last turn is the scope for the assistant’s most recent changes. Work with files, Code review.

A terminal is a command interface and output area. If a task fails, its error message can be more useful than the final summary alone. Ask Codex to explain the failure, its effect on the output, and the next step needed.

6 Settings and account

Open Settings with Command comma on macOS. Begin with General, Keyboard Shortcuts, Notifications, and Appearance. Personalization and Memories affect how future work can use instructions and context; they deserve a separate chapter before changing them casually.

Appearance can change the app’s accent, background, and foreground colours. Identify a control by its position, symbol, label, and behaviour as well as its colour. Settings.

CHAPTER 04Icons and status indicators

An icon may be a button, a status, a badge attached to another object, or part of the current selection. Establish what it refers to before interpreting it.

Purple green and blue indicators

This is the guide’s illustration key, not a universal app palette. In the actual app, identify the object, label, and tooltip together: a pull-request badge describes a PR; an unread marker describes read state; a selected control describes your current selection. OpenAI documents those states without prescribing one colour legend for every client.

Indicators established by the documentation

Sources: Notifications, Commands, Scheduled tasks, Code review, and the 27 February 2026 pull-request badge entry in the OpenAI changelog.

Pet activity labels

Select a pet activity label to see its documented meaning and the next useful action. These controls illustrate the status definitions; their appearance does not reproduce your app’s indicators.

When several chats have activity, the pet prioritises Needs input, then Blocked, Ready, and Running. The floating tray is separate from operating-system notifications. These definitions describe the pet interface; they do not establish the colour of a sidebar dot. Pet status.

Identify an unfamiliar symbol

First locate the object the symbol belongs to. A badge beside a pull request describes something different from an indicator beside a chat.

Hover to look for a tooltip, or use keyboard focus to expose the label when supported. Record the wording and the surrounding control. For an unknown read-state marker, compare the same chat in read and unread states rather than comparing unrelated chats.

On macOS, the documented Mark chat as unread shortcut is Command Shift U. Use a single chat for that comparison. Clearing all unread indicators changes a wider set of navigation markers and is unnecessary for identifying one dot. Commands.

CHAPTER 05Write a useful prompt and inspect the result

For a small task, ordinary language is enough. For a larger task, include the outcome, relevant context, expected output, and boundaries that matter.

Create a one-page FAQ from the attached product notes.

Write for first-time customers in plain English.
Use only the supplied notes. Mark unanswered questions as unknown.
Save the draft as a document I can review.
Keep it private and do not send or publish it.

For a coding task:

Investigate why submitting an empty contact form crashes this practice app.
Explain the cause, make the smallest suitable fix, and run the relevant checks.
Show me the changed files, what you tested, and anything still unresolved.

These are authored examples. They illustrate how to state an outcome and its checks without requiring a fixed prompting formula. Prompting.

Change direction clearly

Name the part you want changed and the result you expect. “Shorten the introduction to two paragraphs and preserve the examples” gives a more inspectable instruction than “Make it better.”

When work is running, make the correction explicit: “Use the newer file I just attached as the source for the comparison.” Remember that the app’s follow-up setting determines whether a message steers active work or waits for a later run. General settings.

Check completion

Ask for the saved output and its location, the important changes, the checks actually performed, and any unresolved gap.

For a code task, inspect the diff. A change on disk, a Git commit, a pushed branch, a merged pull request, and a deployed website are separate outcomes. Ask for the evidence relevant to the outcome you requested.

For a document, open it and check both its content and layout. For research, check whether the source supports the particular claim, including its date and scope. For an automation, distinguish creating the schedule from a successful run.

If the task stopped early, ask what has already happened before retrying an action that might create a duplicate or repeat a write.

CHAPTER 06A small macOS shortcut reference

These are documented defaults. Features can be unavailable, and custom bindings can differ. Use Settings → Keyboard Shortcuts to inspect your current setup.

Source: Commands and keyboard shortcuts, Notifications.

To discover app commands, type a forward slash in the composer and select an available item. Useful entries to recognise include /status for session information, /plan for planning, and /review for code review. Availability varies; a command listed for another Codex surface is not proof it exists in your current app. Slash commands.

CHAPTER 07Organise projects context and memory

Use one chat for an outcome you can name. Use a project when several chats need the same sources, instructions, or folders. For example, a website project might contain separate chats for fixing navigation, researching a feature, and reviewing a release.

Choose the right kind of context

A long conversation can contain more information than the model can actively use at once. Compaction condenses earlier context so work can continue; it is not a substitute for a precise project specification, a saved file, or source control. Keep durable decisions in project instructions or documentation, and ask for a concise handoff when moving to another chat.

A useful handoff includes the objective, current files and branch, decisions, checks completed, unresolved issues, and next action. It should distinguish a proposed change from one already applied.

Find and preserve work

Search chats when you remember a phrase or branch name. Find in chat searches the conversation already open. Pinning keeps work prominent. Archiving removes it from the active list and supports restoration through Archived chats.

A shared chat snapshot is a separate delivery action. Inspect what the snapshot contains before sharing it, especially tool output or file content. Sharing a conversation does not automatically give the recipient access to its local folders or private connected services.

Sources: Projects and chats, Using and sharing work, Memories.

CHAPTER 08Choose models reasoning and speed

Choose the model for the work you need to complete, then adjust reasoning effort when the task warrants it. The available list is more reliable than a model name copied from an old tutorial.

For a small rewrite, explanation, or routine change, begin with the default. For a difficult debugging task, architectural tradeoff, or complex research synthesis, consider a stronger model or more reasoning. Compare the result on a task you understand before making an expensive choice your default.

GPT-5.5 retirement: GPT-5.5 retired from Codex with ChatGPT sign-in on October 14, 2026, at noon PDT (19:00 UTC). OpenAI recommends gpt-6.1-sol on Plus, Pro, Business, Enterprise, and Edu when available, or gpt-6-luna in the desktop app for Free and Go. Check saved model selections, workspace defaults, custom agents, scripts, and scheduled tasks that still select gpt-5.5. The OpenAI API and Codex sessions authenticated with an API key are unaffected. See OpenAI’s model and migration guidance.

GPT-6.1 Terra: OpenAI now offers Terra in Work and Codex on Plus, Pro, Business, Enterprise, and Edu. Choose it from the available model list for writing, image understanding, and computer use. Enterprise access depends on workspace availability and administrator controls. Terra is not available in Chat and does not support UAE inference residency. CLI users need version 0.159.0 or later. See Models and plan access.

Separate four decisions

A faster service tier is not the same as selecting a smaller model. More reasoning does not add missing evidence or grant new tools. Parallel agents add coordination and usage as well as potential speed.

Some interfaces group choices under Power, Faster, Smarter, and Advanced. Other clients expose model and reasoning controls separately. Inspect the control’s description rather than assuming labels match across every client.

OpenAI documents a 500,000-token default context window for GPT-6.1 Sol in Codex and ChatGPT Work. Sol usage drawn from your subscription has no long-context surcharge there; API-key usage follows separate API pricing. See Models and Pricing.

Watch usage and costs

Usage can depend on model choice, task length, context, reasoning, and tool use. Use the account’s usage display to check the applicable limits and reset information. Do not infer a universal token or credit allowance from another person’s plan.

ChatGPT sign-in, API billing, and third-party services are separate considerations. A plugin can require its own subscription, credits, or account. Ask for a cost estimate before requesting paid external generation, deployment, or a large repeated workflow.

Ultrafast availability: GPT-6.1 Sol and GPT-6 Astra support Ultrafast on Pro $500 and eligible Enterprise and Edu plans. Enterprise access is off by default. Ultrafast consumes included subscription usage at 8× the Standard rate; purchased credits and Enterprise pay-as-you-go usage are billed at 6×. These are usage multipliers, not guarantees of task speed. GPT-6.1 Sol supports inference residency in the United States and Europe (EEA plus Switzerland); Astra supports the United States only. See speed modes and eligibility.

Current plan eligibility, model availability, usage accounting, and prices belong in the live references: Models and Pricing and usage.

CHAPTER 09Understand permissions approvals and privacy

Three layers answer different questions:

A sandbox can restrict file reads, file changes, command execution, or network access. Approval controls determine how actions outside the permitted autonomous scope are reviewed. Administrator policy can constrain the choices you see.

Approval inside the sandbox: A command rule can require review even when the command stays inside the sandbox. Auto-review evaluates eligible actions that already require approval; being inside the sandbox does not by itself guarantee that an action can run without review. See OpenAI’s approval guidance.

Read the proposed action

When Codex asks for approval, identify the command or tool, the files or service involved, the consequence, and how broadly the permission applies. An approval for one action is different from a persistent exception.

A denial can be a useful boundary. Ask which part failed and whether the task can proceed within the available access. Changing wording in a prompt does not change the effective policy.

Scope external actions

For tasks involving connected accounts, name the account and intended action. “Draft a reply” describes a different outcome from “Send this reply.” “Prepare the deployment” differs from “Deploy to production.”

For unfamiliar work, a useful opening instruction is:

Inspect the current state and explain the proposed change.
Keep the work within this project.
Before an action sends, publishes, deletes, purchases, or changes access,
describe the concrete action and its consequence.

This is a suggested task boundary. Built-in controls still apply.

Treat source content as evidence

A webpage, email, repository file, or document may contain instructions addressed to an agent. Treat those as source material unless they are legitimate instructions for the task. A retrieved page cannot grant authority to send private files elsewhere.

Use supported secret storage and authentication flows. Keep credentials out of examples, screenshots, shared conversations, and source control. A service permission also does not prove that the task needs every action the account permits.

For detailed technical controls, see Sandbox, Agent approvals and security, and Permission profiles.

CHAPTER 10Create and review files

Name the output you want and the checks that matter. A request for a spreadsheet should identify columns, formulas, and totals. A presentation needs an audience, purpose, length, and evidence. A PDF needs readable layout as well as accurate content.

Turn the attached notes into a five-slide presentation for new customers.
Explain the problem, the product, two examples, and the next step.
Use the supplied facts only. Include source notes and flag missing information.
Open a preview and report where the editable file is saved.

Use the right review method

Supported desktop previews and annotations let you point to a specific part of an output and request a targeted revision. Name the page, slide, sheet, paragraph, or selected area. State what should remain unchanged.

The same request can need different tools in different clients. Document, media, and connected-app capabilities can depend on installed plugins. Choose the requested file format explicitly and inspect the saved result in a suitable viewer.

Sources: Work with files, Plugins.

CHAPTER 11Use the web browser computer and media tools

Web search retrieves information. Browser interaction operates a page. Desktop computer use operates an application through its interface. A task can need one or several of these capabilities.

For research, specify the question, source boundaries, time period, and desired output. Ask for links supporting the particular claims. Separate a vendor’s statement from an independently measured result.

For browser interaction, identify the site, account, and outcome:

Open the preview website and check the navigation on desktop and mobile.
Test the menu, contact link, and sign-up path up to the submission step.
Report reproducible problems with the page and expected behaviour.

Work in the intended session

An in-app browser and an existing browser profile can have different logins, cookies, and permissions. Opening a website does not establish that the agent can use an account already open elsewhere.

Browser previews can support comments and annotations. Select the part that needs changing and describe the intended result. Developer-oriented browser capabilities can help investigate network requests, console errors, page structure, and performance where available.

Desktop computer use depends on supported application access and operating-system permissions. Some applications or actions can be blocked. If the tool cannot access an app, use supported files, exports, or another authorised interface when that can achieve the task.

Add voice images and other media deliberately

Voice is another input method where supported. Images and screenshots can provide visual context. Image generation, video, transcription, and other media workflows may require particular tools or plugins; availability and cost vary.

An original illustration is useful for explaining a workflow. Label it as an illustration when its layout or symbols are schematic. Use a real product capture only when the exact installed interface is what the image claims to show.

Sources: Browser, Computer use, Image inputs, Plugins.

CHAPTER 12Complete a coding task

A useful coding request gives Codex the expected behaviour, the current failure, relevant reproduction steps, and the checks needed to establish a fix.

The contact page crashes when submitted with no email address.
Find the cause, make the smallest suitable fix, and preserve the current layout.
Check both empty and valid submissions.
Show the changed files, checks performed, and any unresolved issue.

Follow the work through six stages

Use the interactive workflow below to explore each stage. The example is a practice task, not a claim that a repository was changed.

Match the checks to the change

Ask Codex to use the project’s existing setup and verification commands. A small documentation edit needs different checks from an authentication change. Meaningful verification follows the behaviour that could fail.

For a UI change, inspect the rendered page and the affected interaction. For an API change, check representative inputs and responses. For a data transformation, validate row counts, missing values, units, and invariants.

A failed dependency install, unavailable service, or missing credential limits what can be verified. The final report should say which checks ran, which passed, which failed, and which could not run.

Keep unrelated edits visible. If another person or process has changed the working tree, do not assume every diff belongs to the current task.

Sources: Local environments, Code review, Prompting.

CHAPTER 13Review changes and use Git

Git records versions of a repository. Its operations describe different stages of delivery.

An open PR can exist after an agent has finished. A merged PR can exist before a deployment succeeds. Read the object’s label rather than treating every coloured badge as an agent status.

Choose the review scope

The desktop review pane can show Last turn, Unstaged, Staged, Commit, or Branch scopes. Use Last turn to focus on the assistant’s most recent changes. Use the broader scopes when reviewing repository state or a release.

A plus beside a hovered diff line adds line-specific feedback. Describe the concrete problem and expected behaviour. For a supported PR review, inspect comments and checks alongside the code.

Undo with the appropriate operation

Unstaging changes what will go into a commit; it does not discard the file edit. Reverting a working-tree change can discard that edit. A Git revert creates a new commit that reverses an earlier commit. These are different actions.

Before any recovery, inspect status and preserve work that may be needed. For a shared branch, follow repository conventions rather than rewriting history casually.

Source: Code review.

CHAPTER 14Isolate work with worktrees and handoffs

A worktree is another checkout of a Git repository with its own working files. It shares repository history, which makes it useful for independent work on related code.

Use a worktree when you want one task to change files without disturbing the checkout you are using. Separate chats alone do not isolate files if they point to the same working directory.

Choose the starting state

Confirm whether the worktree should start from the default branch, another branch or commit, or a supported transfer of current work. Uncommitted files and ignored files need deliberate handling; a new checkout does not imply that every local setting is copied.

A branch can normally be checked out in only one worktree at a time. A detached HEAD means the checkout points directly at a commit rather than an ordinary checked-out branch. Create or select a branch before expecting commits to be associated with a named branch.

Move and clean up safely

Handoff is the app’s supported workflow for moving a chat and its code state between Local and Worktree. Read the destination and summary before proceeding.

Managed worktrees have lifecycle and cleanup behaviour. Preserve important commits and outputs, and understand the supported archive and restore workflow. An archive snapshot can help recovery, but it does not replace pushing work that should be retained in the project’s remote repository.

Source: Worktrees.

CHAPTER 15Understand skills plugins apps and MCP

These terms describe different kinds of extension.

Installing a plugin, connecting an account, and permitting an action are separate steps. A plugin can be present while its account connection is missing. A successful connection does not mean the account can access every file.

Invoke the workflow you want

Use an explicit skill or plugin mention when its workflow is central to the task. State the intended result and source or account. Some skills can be selected automatically when the task matches.

For a reusable skill, define its purpose, triggering conditions, inputs, procedure, and expected output. Put detailed references and scripts beside the instructions when they improve repeatability. Test it on representative tasks and revise instructions that cause predictable failures.

Diagnose a missing tool

Check the supported client, installation, enabled state, account connection, service permission, and workspace policy. The IDE extension does not support plugins in the same way as desktop and CLI; standalone skills and direct MCP configuration have their own support.

MCP connections can use local processes or remote HTTP services. Authentication, server configuration, and the tools actually exposed determine what the agent can do. Keep credentials in the appropriate local or service-managed configuration.

Sources: Skills, Plugins, MCP.

CHAPTER 16Configure durable instructions and project setup

Use the smallest durable surface that fits the behaviour.

Write useful AGENTS.md instructions

Include the project’s purpose, relevant directories, setup commands, verification commands, and conventions the agent cannot reliably infer. Keep instructions specific enough to act on.

# Project guidance

Use the existing package manager and lockfile.
Inspect the working tree before editing.
Keep the change focused on the requested outcome.
Run the relevant existing checks.
Report changed files, checks performed, and unresolved limitations.

Codex discovers global guidance and then applicable project guidance along the path to the working directory. More local project guidance can refine earlier project instructions. AGENTS.override.md has a defined role in discovery. These files remain subject to higher-priority instructions and managed policy.

Understand configuration layers

User defaults live in ~/.codex/config.toml. Trusted project configuration can live in .codex/config.toml. CLI overrides, selected profile files, user defaults, cloud or system defaults, and managed requirements have defined precedence.

A default is not an entitlement or a permission grant. Ask Codex to explain the effective configuration when the selected setting differs from what you expected.

Local environments can define setup scripts and reusable actions such as Run or Test. Use them to make project setup repeatable instead of rediscovering the same commands in every chat.

Sources: AGENTS.md, Configuration, Local environments.

CHAPTER 17Schedule repeatable work

A scheduled task combines instructions, a cadence, execution context, and a reporting destination. A follow-up inside an existing chat preserves its continuity; a standalone scheduled task can give each run its own chat and result.

Before scheduling, make one manual run useful and predictable.

Each weekday at 9 am America/Vancouver, inspect the specified release page.
Report only a new release or a failed check.
Include the source link and what changed.
Do not publish, send messages to anyone else, or modify project files.
Stop after ten checks.

This is a teaching example. It does not create an automation.

Define the operating rules

Specify the time zone, source, what counts as a meaningful change, allowed actions, output, and end condition. If unchanged results should stay quiet, say so.

The Scheduled view contains tasks and runs. Review the actual run history and findings. Creating a schedule does not prove that a later run completed.

Desktop tasks that need local files require the computer and app to be available. Git tasks can use isolated background worktrees where supported; tasks in an ordinary folder can operate directly in that folder. Choose the execution location deliberately.

Event-triggered tasks and team-managed cloud tasks are separate capabilities with their own client and plan requirements. Do not assume that every desktop automation can be triggered by every connected service.

Maintain the task

Review failures, stale sources, unnecessary notifications, credentials, and changing instructions. Pause or stop work that has reached its end condition. Edit the existing automation when appropriate rather than creating duplicate schedules.

Source: Scheduled tasks.

CHAPTER 18Use goals and parallel agents

A goal gives long-running work a persistent objective. Define the outcome, boundaries, and completion criteria, then steer the same chat as the work develops. The documented /goal workflow has progress controls for pausing, resuming, editing, or clearing the goal. Use /plan first when the approach needs discussion.

Audit this practice project’s navigation and fix reproducible defects.
Keep changes within the navigation components.
Finish when the named routes work at desktop and mobile widths,
the relevant checks pass, and the changed files have been reviewed.
Report anything blocked by missing access.

Separate the forms of parallel work

For parallel agents, give each a distinct question or area. Good examples are independent source research, review of separate modules, or investigation of different hypotheses. Avoid assigning two agents conflicting ownership of the same files.

Have one coordinating task integrate the findings, resolve disagreements, and run checks on the combined result. Subagent output is evidence to assess; it does not remove the need for integration.

Parallel work can reduce elapsed time when tasks are independent. It can also increase token use, duplicated effort, and coordination cost. Use it when the structure of the problem supports it.

Sources: Long-running work, Subagents.

CHAPTER 19Use Codex in the terminal and IDE

The CLI is useful for terminal-first work and scripts. The IDE extension puts the conversation beside the files, selections, and development tools you are already using. The desktop app adds its own navigation, panels, and workflows. Learn the shared concepts, then use each surface’s own command reference.

Begin in the CLI

After installing and authenticating through the supported setup, start in the project directory:

codex

Continue a saved session with:

codex resume

Use the installed command’s help and interactive command list to discover supported options. Commands and flags can change; do not apply a desktop slash-command table to the terminal uncritically.

CLI 0.167.0, released November 6: Open the agent command center with codex agents --no-daemon. The command center and session picker mark unread results, and the terminal session picker can switch between connected backends while preserving drafts. You can also expand patch details while an approval prompt is open. See the official release notes.

Use editor context precisely

Open the intended folder or workspace in the IDE. Select the relevant code or refer to the file and observed behaviour. In a multi-root workspace, confirm which root provides the task’s working context.

An editor attachment, selected text, and an instruction to modify a file are different things. State the intended change. Review the resulting diff in the editor and run the project’s relevant checks.

The IDE does not expose every desktop capability. In particular, use the supported skill and MCP routes rather than assuming the desktop plugin interface is present.

Source: Developer commands and surface references, Plugins.

CHAPTER 20Choose local remote cloud and mobile execution

Ask where the code and tools actually run. The device showing a chat is not necessarily the machine executing its commands.

Local and remote hosts

Use local execution when the task depends on files or tools on the connected computer. A remote host has its own repository, setup, access, and connectivity requirements. Confirm which host owns the task before troubleshooting a missing file.

Phone control does not move a worktree onto the phone. It lets you start, guide, approve, and review work on the selected connected host or supported cloud environment.

iOS follow-ups: In ChatGPT for iOS 1.2026.300, released November 2, follow-ups steer the running task by default unless you have saved a different preference. Task read status syncs with supported hosts, helping clear stale unread indicators across devices. See the iOS release notes.

Codex Cloud

Choose a published environment when you want a reusable hosted setup. Environment preparation can include repository checkout, dependency installation, tools, and setup verification. Review the setup report, publish the environment, and start tasks with that environment.

Environment variables provide values directly to programs. Network secrets can provide credentials through a destination-scoped HTTPS proxy substitution mechanism. Configure secrets through the supported controls and verify the required service access.

Important work still belongs in source control or saved outputs. Reusable environment state is not a replacement for committing and preserving a result.

Codex Cloud and Codex Cloud Legacy have different workflows and capabilities. Personal local skills, browser access, integrations, and execution policies should not be assumed to transfer between them.

Sources: Cloud environments, Mobile, Worktrees.

CHAPTER 21Automate through the CLI SDK and App Server

Use an interactive chat while you are exploring the task. Use a programmatic interface when another program needs repeatable inputs, outputs, and lifecycle control.

Non-interactive CLI

A basic one-shot request is:

codex exec "Summarise this repository and identify the main entry points."

Run non-interactive examples inside a suitable Git practice repository; codex exec normally requires a Git repository. By default, progress goes to standard error and the final reply goes to standard output. JSON mode produces an event stream:

codex exec --json "Summarise this repository."

JSON Lines contains a sequence of event objects. It is different from a single final JSON document.

For a final structured result, define a JSON Schema and pass its file path with the documented --output-schema option. The schema can require a summary, a list of findings, and a list of unresolved checks. Validate the returned fields before using them downstream.

Run these examples only in a suitable authenticated practice environment. They are instructional snippets, not executed jobs.

SDKs and custom clients

The TypeScript SDK can start, continue, and resume local threads. A minimal server-side pattern is:

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

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Explain this project without changing files."
);
console.log(result.finalResponse);

The Python SDK controls local Codex through App Server. Choose the supported SDK when it fits. App Server exposes a lower-level protocol for custom clients, including threads, turns, events, authentication, and approvals. Experimental APIs and transports need their documented compatibility constraints.

Hooks and CI

Hooks can run mechanical checks around supported lifecycle events. Treat hook definitions as executable configuration: inspect their commands, inputs, outputs, and trust requirements before enabling them.

For CI, separate repository setup, model access, patch creation, and repository writes. Use the supported Codex GitHub Action guidance for GitHub Actions. Avoid exposing API credentials to unrelated dependency scripts or untrusted repository code.

A dependable automation validates inputs, bounds the task, records events, verifies output, and handles retries without duplicating side effects. Start with a patch artifact or reviewable result before broadening autonomous delivery.

Sources: Non-interactive mode, SDKs, App Server, Hooks, GitHub Action.

CHAPTER 22Troubleshoot and recover

Start with the last concrete observation: the error, file state, selected host, connection status, or failed check.

CLI updates, October 27–29: Version 0.165.0 closed a marketplace URL validation gap that could let Git connect to a different host from the one checked against allowed patterns. Version 0.166.0 preserves acknowledged approval and permission settings when resuming or forking threads. Update through your installation method if you use an older release. See the official release notes and CLI installation guide.

Recover in a controlled order

1. Stop conflicting work if it is still active.

2. Inspect the current files, Git state, and external outcome.

3. Preserve work that may be needed.

4. Choose the smallest appropriate recovery operation.

5. Verify the recovered state before resuming.

Stopping an agent does not undo completed actions. Restoring a chat does not necessarily restore a deleted file. Reverting a change, restoring a backup, and resuming a conversation solve different problems.

Old tutorials can describe renamed interfaces, retired models, or unsupported flags. Compare advice with the current client, help output, and official reference before changing configuration.

Sources: Troubleshooting, Code review, Configuration.

CHAPTER 23Operation dictionary and settings reference

The illustrated atlas in chapter 4 gives a quick visual lookup. This table groups the main operations by purpose.

Settings groups to recognise

An overflow menu contains additional actions for the object beside it. A disclosure arrow expands or collapses content. A disabled control is unavailable in its current context. Read the label and scope before treating a generic symbol as a task status.

Documented desktop slash commands

Type / to discover the commands actually available in your session. Installed skills can add entries. This is the documented desktop reference; other clients and account access can differ.

Sources: Settings, Commands, Slash commands.

CHAPTER 24Practice recipes and glossary

Use these recipes to build skill in increasing order of consequence.

Explain before editing

Explain the structure of this project and the main execution path.
Read the relevant files, but do not change anything.
List the key files and three questions that would help you understand it.

Research with clear source boundaries

Compare these two products for the task I described.
Use current official specifications and clearly attributed independent tests.
Separate advertised claims from measured results.
Mark unsupported points as unknown and include supporting links.

Make and verify a small change

Implement the requested behaviour while preserving unrelated work.
Use the existing project conventions.
Run the relevant checks and inspect the changed output.
Report the changed files, results, and any checks that could not run.

Build a reusable workflow

Turn this repeated procedure into a focused skill.
Define when it should run, required inputs, steps, expected output,
verification, and failure handling. Keep one-off project details separate.

Coordinate an advanced task

Break this outcome into independent parts with clear ownership.
Use isolated checkouts for independent edits when appropriate.
Integrate the results, resolve disagreements, and verify the combined output.
Report evidence for the requested outcome and unresolved limitations.

Glossary

This edition uses original illustrations and a guide-specific colour key. Feature availability and exact control placement can vary by platform, plan, workspace policy, and release. Use the live official references for changing model availability, pricing, commands, and configuration.

Update history and sources

This illustrated edition expands the guide into 24 chapters with a visual operation atlas, practical examples, native expandable diagrams, commands, and advanced workflows. The product guidance is documentation-based. Original illustrations explain concepts and are not evidence of testing every client, plan, or platform.

Source guidance checked October 16, 2026. Examples are instructional unless explicitly described as executed. Model availability, pricing, command support, and workspace controls can change.

Previous verification history

For the October 5 review, Kingy compared the live article with current OpenAI documentation on models, pricing, releases, feature maturity, installation, desktop and Linux support, plugins, scheduled tasks, authentication, and security. Cached and uncached CDN responses contained matching article content. The September 3 review also checked locally installed CLI help; that command check was not repeated. This is a documentation review, not a model benchmark or a test of every platform.

Related Kingy guides