AI Learning Library

Real-world AI tools,
one page at a time

One concept per page. Learn by turning pages like a book — no endless scrolling. Built from hands-on, verified material.

codex ~ project
Codex Practical Guide
CODEX·CLI
Codex — Practical Guide
OpenAI's official coding agent Codex. From install and auth to config, models, MCP, automation, and security — learn it one page at a time.
Codex CLI · 30 parts Start
claude ~ code
CLAUDE
Claude Code Guide
Anthropic's official CLI. Hooks, MCP, agent orchestration.
Coming soonComing Soon
codex ~ cli
CODEX
Codex CLI Guide
OpenAI terminal agent. AGENTS.md, sandboxing.
Coming soonComing Soon
midjourney ~ v7
MIDJOURNEY
Midjourney V7 Guide
V7 prompts, reference images, style consistency.
Coming soonComing Soon
Codex — Practical Guide
Section 01 / 30

Codex — Practical Guide

A practical, beginner-friendly guide to Codex, OpenAI's official coding agent — all 30 parts. From install and auth to config, models, MCP, Skills, automation, security, and team operations.

0. Before Reading This Guide

01The Purpose of This Guide

This guide enables you to use Codex at the following levels.

Install → Log in → Run in your project → Help it understand the codebase → Delegate work safely → Review changes → Test → Automate recurring tasks → Manage team rules and security

This is not just a collection of commands—it explains how to weave Codex into your actual development workflow.

02What This Guide Covers

This guide comprehensively covers Codex's core features.

Getting Started
Installation, authentication, first run
Basic Usage
CLI, slash commands, file editing, diff review
Safety Features
sandbox, approval, permission profiles
Configuration
config.toml, profiles, model selection
Project Rules
AGENTS.md
Extensions
MCP, Skills, Plugins, Hooks
Task Management
Plan Mode, Goal Mode, Session Management
Automation
codex exec, GitHub Action, CI/CD
Advanced Use
Cloud, Desktop App, IDE Extension, Chrome Extension
Operations
Performance tuning, debugging, security, Enterprise deployment
Practical Examples
Workflow Recipes, Migration Guide, Quick Reference Card

03How to Read This Guide

You can read it cover to cover, but it's better to adjust the order based on your goals.

Codex Beginners
Section 0 → 1 → 3 → 4 → 5, then 6, 8, 14
Terminal-Savvy Developers
Section 1 → 2 → 5 → 7, then 9, 13, 24
Ready to Use Immediately
Section 5 → 8 → 14 → 15, then 20, 28, 29
Team Lead
Section 15 → 28 → 29, then 14, 30
Looking to Automate
Section 24 → 29 → 30, then 13, 28
Coming from Another AI Coding Tool
Section 1 → 2 → 29, then 15, 20

04Recommended Learning Order for Beginners

Beginners should read at least in this order.

  1. Section 0: How to Read This Guide
  2. Section 1: Codex Essentials
  3. Section 2: How Codex Works
  4. Section 3: Installation
  5. Section 4: Authentication
  6. Section 5: Your First Session
  7. Section 8: Frequently Used Slash Commands
  8. Section 14: Sandbox and Approval
  9. Section 15: AGENTS.md

05Essential Concepts Every Beginner Must Know

Certain concepts come up frequently when using Codex.

CLI
Way to run Codex from the terminal
TUI
Interactive interface that opens inside the terminal
Session
One ongoing conversation about a task with Codex
Thread
Conversation flow managed continuously
Fork
Copy an existing conversation and continue in a different direction
Sandbox
A safety feature that limits what Codex can access
Approval
A policy where Codex requests user approval before certain actions
AGENTS.md
A rules file that Codex must follow in your project
config.toml
Codex configuration file
Profile
A bundle of settings for different work situations
MCP
Protocol for connecting external services with Codex
Skill
A knowledge package for reusing specific work methods
Hook
Automatic actions that run before or after specific events
Plugin
A package that extends Codex functionality
Plan Mode
Mode that plans first before executing
Goal Mode
Mode for managing ongoing work goals
codex exec
Non-interactive automated execution method

These terms will be explained in more detail later. For now, just remember that these names will come up repeatedly.

065 Essential Things Every Beginner Must Learn First

When you first use Codex, it might seem like there are many features. But you don't need to know everything from the start.

Just start with these 5 things.

1Run Codex in Your Project
2Ask About Project Structure
3Plan Complex Tasks First
4Review Changes
5Use Safe Default Permissions

Learning just these 5 things lets you start using Codex safely.

1. Run Codex in Your Project

cd my-project codex

2. Ask About Project Structure

Explain this project's structure and how to run it in a way that beginners can understand.

3. Plan Complex Tasks First

/plan I want to refactor the login feature. Find related files, identify risks, and propose a step-by-step plan first.

4. Review Changes

/diff

5. Use Safe Default Permissions

sandbox_mode = "workspace-write" approval_policy = "on-request"

07Principle 1. Start with Safe Defaults

Don't start with strong permissions like danger-full-access.

Recommended defaults are:

sandbox_mode = "workspace-write" approval_policy = "on-request"

This combination lets you work within your current project while requiring user approval for risky actions.

08Principle 2. Don't Execute Large Tasks Right Away

For large tasks, first verify the plan using /plan.

/plan I want to refactor the payment module. Analyze the current structure and propose a step-by-step change plan first.

It's safer to execute after reviewing the plan.

09Principle 3. Always Review Changes

Even code created by Codex should be reviewed by a human.

/diff

Especially review after these operations:

10Principle 4. Run Tests

After changes, run relevant tests.

You can request this inside Codex.

Run tests related to the login API I just modified and summarize the results.

Or run them directly.

npm test

11Principle 5. Document Recurring Instructions in AGENTS.md

Rules you need to repeat should be written in AGENTS.md.

Example:

# AGENTS.md - Run relevant tests after all changes. - Preserve existing API response formats. - Follow TypeScript strict mode standards. - Add tests for new features.

12Example Standards Used in This Guide

This guide uses the following formats for clarity.

Terminal Commands:

codex codex "prompt" codex --profile fast "task"

Configuration (TOML format):

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

Commands inside Codex:

/plan Create a step-by-step plan for this task.

13Recommended Default Configuration

Beginners should start with this configuration as a baseline.

model = "gpt-5.5" model_reasoning_effort = "medium" sandbox_mode = "workspace-write" approval_policy = "on-request"

Here's what each setting means:

model = "gpt-5.5"
Use the recommended default model
model_reasoning_effort = "medium"
Balance between speed and accuracy
sandbox_mode = "workspace-write"
Allow read/write in the work folder
approval_policy = "on-request"
Request approval for risky or out-of-scope actions

Just these settings are enough to start.

14Prerequisites for Practice

To practice Codex, it helps to have these.

Node.js / npm
Required if using npm installation method
Git
Needed to review project changes
Code Project
Any git repo works
OpenAI / ChatGPT Account
Login and usage rights required
Terminal
Required for CLI usage
Code Editor
VS Code, Cursor, Windsurf, etc.

It's good to prepare a test project. It's safer not to apply it directly to important production projects from the start.

15Recommended Flow for Your First Practice

It's better to start with a small example project rather than a real production project.

  1. Navigate to a test project folder
  2. Run codex
  3. Request a project structure explanation
  4. Ask how to run and test the project
  5. Request a small modification
  6. Review changes with /diff
  7. Run tests
  8. Commit changes or revert them

In the terminal:

cd sample-project codex

Inside Codex:

Explain the structure, how to run it, and how to test it for someone new to the project.

16Things Beginners Should Never Do

Beginners should avoid the following actions.

Start with danger-full-access
Codex can access the entire system
Make large edits right away in production
Hard to understand scope and risks
Commit without /diff
Can miss unintended changes
Deploy without testing
May not catch errors
Work on team projects without AGENTS.md
Codex may not know team rules
Connect many MCPs at once
Increases complexity and token costs
Give large tasks with vague requests
Results may not match expectations
Section 00 · Wrap-up

What to Remember from This Unit

This section is an orientation before diving into the main Codex content.

Start safely, plan first, review changes, and test.

Beginners should focus on these first:

Next Section

Section 1. Codex Essentials

1. Codex Essentials

01What is Codex?

Codex is an integrated coding agent that developers can use from the terminal, desktop app, IDE, cloud, and browser environments.

Codex can do the following:

02Codex Definition for Beginners

An AI development partner that understands my project, finds needed files, creates solutions, and can execute commands.

Codex is not just a chatbot that answers questions about code. It can read the codebase directly, execute commands, modify files, connect to external tools, and even delegate cloud tasks when needed.

In other words, think of it as an agent-based development tool that performs development work together with you, not just "a tool that answers questions."

03Why Codex Isn't Just a Simple Chatbot

Typical AI chatbots respond based on code or descriptions that users paste in. Codex, on the other hand, operates within an actual development environment.

Codex can directly perform these tasks:

# Read project structure ls # Run tests npm test # Modify specific files apply patch # Review changes git diff

In other words, Codex goes beyond simply saying "fix it this way." It helps with the entire workflow of actually reading files, modifying them, and verifying the changes.

04Core System 1: config.toml

config.toml is the configuration file that determines how Codex operates.

You can configure the following:

Which model to use
Choose which AI model to use
Reasoning strength
Adjust the model's thinking depth
Sandbox mode
Limit access scope
Approval policy
Define which actions require user permission

Basic settings for beginners to remember:

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

05Core System 2: Sandbox / Approval

Since Codex can execute actual commands and modify files, safety mechanisms are necessary.

Sandbox
Limit how far Codex can technically access
Approval
Determine when Codex needs user permission before taking actions

Typical sandbox modes:

read-only
Read-only access. Most secure
workspace-write
Can read and write within the current work folder
danger-full-access
Full system access. Use with caution

06Recommended Combination for Beginners

sandbox_mode = "workspace-write" approval_policy = "on-request"

This combination is practical for real development work while ensuring risky tasks require user approval.

For example, in workspace-write mode, Codex can modify files within the current project folder but cannot freely modify the entire system.

07Core System 3: AGENTS.md

AGENTS.md is a file where you write the work rules that Codex must follow in your project.

Example:

# AGENTS.md ## Development Rules - Write TypeScript code to strict mode standards. - Always run npm test after changes. - Do not arbitrarily change existing public APIs. - Minimize style changes. - Add tests for new features.

Simply put, AGENTS.md is a project operations manual you give to Codex.

08Benefits of Good AGENTS.md

With a good AGENTS.md, Codex won't repeat the same mistakes.

It also makes it easier for Codex to work according to your team's methods.

It's the most effective tool for determining Codex's behavior.

09Core System 4: MCP

MCP stands for Model Context Protocol.

With MCP, Codex can connect to external tools and services:

10MCP's Role

If basic Codex is "a tool that reads and modifies my code," then Codex with MCP becomes "an agent that connects external services to complete work."

For example, if Sentry MCP is connected, Codex can review error logs and identify bug causes through a complete workflow.

11Core System 5: Skills

Skills are reusable work knowledge that makes Codex better at specific tasks.

For example, you can create skills like:

12Benefits of Skills

Skills help you avoid repeating long prompts every time.

For example, instead of saying this every time:

Review this PR. Separate out security issues, performance issues, missing tests, and API compatibility issues.

You can create a PR review skill, and Codex can reuse those guidelines when needed.

13Codex's Main Usage Interfaces

Codex is not a single-purpose tool. You can use the same Codex intelligence across multiple interfaces:

CLI
Terminal-focused development, quick fixes, automation
Desktop App
Manage multiple tasks simultaneously, visual diff review
IDE Extension
Edit directly in VS Code, Cursor, Windsurf
Codex Cloud
Delegate long-running tasks to the cloud
Chrome Extension
Browser-based tasks, admin pages, dashboards

14Recommended Starting Point for Beginners

For beginners, starting with CLI or IDE Extension is easiest.

15Codex's Core Workflow

Codex's basic workflow is typically as follows:

  1. User makes a request
  2. Codex reviews the current project and settings
  3. Reads project guidelines like AGENTS.md
  4. Finds necessary files
  5. Reads related code
  6. Plans the work
  7. Executes shell commands if needed
  8. Creates file modifications
  9. Shows the diff
  10. User reviews
  11. Runs tests
  12. Summarizes results

16Codex Execution Example

In the terminal:

cd my-project codex

Inside Codex, you can make requests like this:

Explain this project's structure to me.

Or:

Add input validation to the login API.

17Reviewing Changes

After work, review changes with this command:

/diff

This is the most important step in Codex's workflow.

18Essential Commands for Beginners

You don't need to memorize all commands at first. These are enough:

codex
Run Codex
/plan
Create a work plan before execution
/diff
Review changes made by Codex
/status
Check current session status

19Key Commands (continued)

/model
Change model
/compact
Summarize long conversation to free up context
/resume
Resume previous session
/review
Review code
/permissions
Check or change permissions
/quit
Exit

The most important commands for beginners are /plan and /diff.

20Principle 1: Start with a Plan for Large Tasks

Bad example:

Refactor this entire project for me.

Good example:

/plan I want to refactor the authentication module. First analyze the current structure and propose risks and a step-by-step plan.

For complex tasks, it's safer to use /plan first.

21Principle 2: Always Review Diffs After Changes

You should always review changes made by Codex:

/diff

Especially review diffs after these operations:

22Principle 3: Put Project Rules in AGENTS.md

Instead of repeating the same instruction, write it in AGENTS.md.

Example:

- Run npm test after all changes. - Write migration files when changing DB schema. - Keep existing API response formats intact. - Write unit tests for new functions.

23Principle 4: Use Appropriate Profiles for Each Situation

Different tasks require different speeds and safety levels.

For example, use fast profile for quick questions, careful for security reviews, and ci for CI automation:

codex --profile fast "Explain this function" codex --profile careful "Review this authentication logic for security" codex --profile ci "Analyze why the test failed"

24Principle 5: Manage Context

Codex remembers long conversations, but performance may degrade if the context window fills up.

In such cases, use /compact:

/compact

Or specify just the files you need:

@src/auth/login.ts Focus on this file to review input validation logic.

25Mistake 1: Using danger-full-access From the Start

codex --sandbox danger-full-access

This mode gives Codex very broad permissions. Beginners should avoid using it by default.

Recommendation:

codex --sandbox workspace-write --ask-for-approval on-request

26Mistake 2: Committing Without Reviewing Diff

Code created by Codex should still be reviewed by humans.

Always follow this order:

Request → Generate Changes → /diff Review → Run Tests → Commit

27Mistake 3: Making Vague Requests Too Broadly

Bad example:

Make the code better.

Good example:

Read the login flow in src/auth folder, and propose a refactoring plan to reduce duplicate validation logic.

28Mistake 4: Using Codex on Team Projects Without AGENTS.md

Work rules are important in team projects.

Without AGENTS.md, Codex may not know your team's style, testing approach, and deployment rules.

29Mistake 5: Connecting Too Many MCPs

More MCP servers mean more tool definitions and potentially higher token costs.

It's best to connect only essential MCPs at first.

30Codex Learning Roadmap

Codex in one sentence:

A multi-surface coding agent that understands your local project and external tools, and performs command execution and file modification within safety boundaries.

Beginners should learn in this order:

Install → Log in → Run CLI → Request project analysis → Use /plan → Request code changes → Review with /diff → Run tests → Write AGENTS.md → Configure profiles
Section 01 · Wrap-up

Key Takeaways from This Section

Next Section

2. Understanding How Codex Works

2. Understanding How Codex Works

01Codex's Overall Architecture

Codex can be understood in 4 main layers.

Codex ├─ Surface Layer │ ├─ CLI │ ├─ Desktop App │ ├─ IDE Extension │ ├─ Cloud Tasks │ └─ Chrome Extension │ ├─ Extension Layer │ ├─ MCP │ ├─ Skills │ ├─ Apps │ └─ Web Search │ ├─ Security Layer │ ├─ Sandbox │ └─ Approval Policy │ └─ Core Layer ├─ GPT-5.x-Codex Intelligence ├─ Shell Tool ├─ Patch Tool ├─ Read Tool └─ Web Search Tool
Core Layer is the brain, Security Layer is the safety guard, Extension Layer is the expansion mechanism, and Surface Layer is what users see.

02Core Layer: Codex's Brain

Core Layer is the innermost core intelligence of Codex. It's based on the GPT-5.x-Codex model family and understands user requests and plans actual development work.

What Core Layer Handles

03Core Layer's Thinking Process

Suppose a user requests "Add email format validation to the login API."

Codex's Core Layer doesn't just answer. It typically thinks through the following process:

1. Find where the login API is. 2. Read related route, controller, and service files. 3. Check if existing validation methods are used. 4. Create a solution matching the project style. 5. Find test files if necessary. 6. Create a change patch. 7. Show diff for user review.

In other words, Core Layer is the center of reasoning, judgment, code understanding, and work planning.

04Tools Used by Core Layer

Codex's brain doesn't work alone. It uses several tools to perform necessary tasks.

Read
Read file contents
Shell
Execute terminal commands
Patch
Apply file modifications
Web Search
Search web information when needed
MCP Tools
Connect to external services

Because of this structure, Codex acts like an agent that takes action in actual development environments, not just explaining things.

05Security Layer: Safety Mechanisms

Since Codex can execute actual commands and modify files, safety mechanisms are essential. Security Layer has two components.

Sandbox
Limit where Codex can access
Approval Policy
Determine when specific actions need user permission

06Sandbox Modes

Sandbox limits where Codex can technically access.

Typical sandbox modes:

read-only
Read files only
workspace-write
Can read and write in current work space
danger-full-access
Full system access

Most suitable default for beginners:

sandbox_mode = "workspace-write"

This mode allows real development work while not giving unlimited system access.

07Approval Policy

Approval Policy determines when Codex needs user permission before taking actions.

Typical approval policies:

untrusted
Request approval for most actions besides reading
on-request
Proceed with regular tasks, request approval for risky or out-of-scope actions
never
Proceed without approval requests

Recommended combination for beginners:

sandbox_mode = "workspace-write" approval_policy = "on-request"

This combination balances work efficiency and safety well.

08OS-Level Sandbox

Codex's sandbox is not just a promise—it uses OS-level restrictions.

macOS
Seatbelt
Linux
Landlock + seccomp
Windows
Restricted token-based sandbox

Why this matters: Codex doesn't just promise "we won't do it"—it restricts access permissions at the OS level.

Sandbox is a safety fence around Codex. Even if Codex makes a mistake, it cannot escape the fence.

09Extension Layer Overview

Extension Layer allows Codex to connect to external tools beyond basic functions.

Main components:

10MCP (Model Context Protocol)

With MCP, Codex can connect to external services.

Connectable services:

Example: If Sentry MCP is connected, Codex can review actual error logs, find related code locations, and propose fixes.

MCP extends Codex from a simple code helper to a development agent connected to external work systems.

11Skills and Apps

Skills are reusable work knowledge that makes Codex better at specific tasks.

Examples of skills you can create:

Skills are reusable manuals that teach Codex specific work methods.

Apps connect with ChatGPT connectors and let you reference business context outside the codebase.

12Web Search

Web Search lets Codex reference latest internet information.

Useful tasks:

However, not every task needs web search. Many internal code-only tasks work fine with just file reading and shell execution.

13Surface Layer: Where You Use Codex

Surface Layer is where users actually interact with Codex. Codex doesn't provide just one interface.

You can use it across multiple surfaces:

14CLI (Command Line Interface)

CLI is how you use Codex from the terminal.

Basic execution:

codex

Pass a prompt directly:

codex "Explain this project's structure"

CLI is good for:

CLI is the most basic yet powerful usage method.

15Desktop App

Desktop App lets you use Codex visually.

Features more convenient than CLI:

Desktop App is good for:

Running multiple tasks in parallel
Easy per-task thread management
Visually reviewing diffs in detail
Visual review is convenient
Team members not familiar with Codex
Can use with minimal terminal knowledge
Managing long-running work
Good for separating workflows

16IDE Extension

IDE Extension is how to use Codex inside VS Code, Cursor, Windsurf, and similar editors.

IDE Extension is good for:

IDE Extension is the most natural way for beginners since you can invoke Codex from the editor you're already using.

17Codex Cloud and Chrome Extension

Codex Cloud is running tasks in OpenAI-managed environment rather than locally.

Cloud tasks are good for:

Codex for Chrome is suited for browser-based work. You can use it for admin consoles, internal dashboards, CMS content, and ticket systems.

18Usage Recommendation by Surface

Skilled Codex users don't stick to one interface. They choose appropriate surfaces for different task types.

Quick questions
CLI
Modify current file
IDE Extension
Large refactoring plan
CLI + /plan
Running multiple tasks in parallel
Desktop App
Long-running work
Cloud
Browser-based work
Chrome Extension

Codex is more of an integrated development agent with different surfaces for different situations than a single tool.

19Codex's Basic Workflow

Codex's actual workflow usually goes like this:

  1. User makes a request
  2. Codex checks the current project and settings
  3. Reads project guidelines like AGENTS.md
  4. Finds needed files
  5. Reads related code
  6. Creates a work plan
  7. Executes shell commands if necessary
  8. Creates file modification proposals
  9. Shows the diff
  10. User reviews
  11. Runs tests
  12. Summarizes results

20Real Case: Adding Password Validation

Suppose a user requests "Add password length validation to the signup API."

Codex typically checks:

After this process, Codex creates a solution.

21AGENTS.md: Project Guideline File

Codex uses AGENTS.md as important guidelines if it exists.

Example AGENTS.md content:

# AGENTS.md - Run npm test after all changes. - Write code to TypeScript strict mode standards. - Don't break existing API response formats. - Add tests for new features.

Then Codex references these rules when working. You don't need to repeat instructions.

AGENTS.md is the key mechanism that makes Codex act appropriately for your project.

22Codex's Configuration Priority

Codex reads configuration from multiple locations. Priority is:

  1. CLI options passed when running
  2. Project configuration file
  3. User configuration file
  4. System configuration file
  5. Codex defaults

Example:

codex -m gpt-5.4 "Review this code"

In this case, gpt-5.4 is used for that session.

Options specified directly when running have highest priority.

23Context Management

Codex uses conversation history, read files, command results, and project guidelines as context.

But context has limits. Long conversations or many files can fill the context window.

Command to use then:

/compact

/compact summarizes long conversations to free up context space.

Also, specifying just needed files helps Codex work more efficiently:

@src/auth/login.ts Check login validation logic in this file.
Smaller work scope means Codex works more accurately.

24Recommended Understanding Order for Beginners

You don't need to memorize the entire structure from day one. Understand in this order:

  1. Run Codex from CLI or IDE
  2. Understand that Codex can read and modify files
  3. Understand that sandbox and approval are safety mechanisms
  4. Build habits of working safely with /plan and /diff
  5. Tell it project rules via AGENTS.md
  6. Configure basic behavior with config.toml
  7. When needed, extend with MCP and Skills
  8. Separate large work with Desktop App or Cloud

Just these three things are enough at first:

Codex reads code. Codex can execute commands. Codex moves safely within sandbox and approval boundaries.

25Beginner Real-World Scenario

Situation

You received a new project you've never seen. You don't know where to start.

Run Codex

cd my-project codex

First Request

Explain the overall structure of this project so a beginner can understand. Summarize main folders, how to run it, how to test, and key entry points.

26Beginner Scenario (continued)

Next Request

/plan Analyze how the login feature works in this project. Find related files and create a plan that explains the data flow step-by-step.

Change Request

If the login API doesn't have email format validation, add it. First check the existing validation style and apply it the same way.

Review Changes

/diff

Run Tests

Run related tests and summarize the results.

This flow is Codex's most basic usage pattern.

Section 02 · Wrap-up

What to Remember from This Section

Codex is an integrated development agent made up of 4 layers: Core, Security, Extension, and Surface.

Next Section

Section 3. Installing Codex

3. Installing Codex

01What to Check Before Installation

Check these items before installing Codex.

Operating System
Supports macOS, Linux, Windows
Terminal
macOS Terminal, iTerm2, Linux shell, Windows PowerShell, etc.
Git
Required for reviewing project changes
npm
Required if installing via npm
Homebrew
Required if installing via Homebrew on macOS
Authentication Info
ChatGPT account or API Key (required for Codex authentication)

Codex CLI is a coding agent that runs on your local terminal and can read, modify, and execute commands within your chosen directory.

02Recommended Installation Method for Beginners

Beginners should start based on their operating system:

macOS
Standalone installer or Homebrew
Linux
Standalone installer or npm
Windows
PowerShell installer or npm
WSL2
Install as Linux

Simple criteria:

macOS / Linux → standalone installer Windows → PowerShell installer Already have Node.js → npm Use Homebrew frequently on macOS → Homebrew

03macOS / Linux: Official Standalone Installer

On macOS or Linux, you can use the official installer.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

This method installs Codex CLI without needing npm or Homebrew.

After installation, run this command in the terminal:

codex

On first run, you'll see a login prompt.

04Unattended Install

For environments like CI, remote servers, or automation where interactive input is not possible:

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

CODEX_NON_INTERACTIVE=1 is an environment variable to reduce interactive prompts during installation.

05Windows: PowerShell Installer

On Windows, you can install from PowerShell.

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

After installation, run this in PowerShell:

codex

Windows has native PowerShell support for Codex, and you can also use WSL2 if a Linux native environment is needed.

06Installing via npm

If you already have Node.js and npm installed, you can install via npm.

npm install -g @openai/codex

After installation, run:

codex

npm method is a universal way to install on macOS, Linux, and Windows.

To update, use:

npm install -g @openai/codex@latest

07Installing via Homebrew

On macOS with Homebrew, you can install with:

brew install --cask codex

After installation, run:

codex

Updates typically go like this:

brew update brew upgrade --cask codex

08Installing via winget

On Windows, you can also install using winget.

winget install OpenAI.Codex

However, the latest official Codex CLI quickstart explicitly recommends PowerShell installer for Windows. Windows beginners should use this method first:

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

If using winget, verify after installation:

codex --version

09Direct Binary Download

If you can't use npm, Homebrew, or installers, download platform-specific binaries directly from GitHub Releases.

macOS Apple Silicon / arm64
codex-aarch64-apple-darwin.tar.gz
macOS Intel / x86_64
codex-x86_64-apple-darwin.tar.gz
Linux x86_64
codex-x86_64-unknown-linux-musl.tar.gz
Linux arm64
codex-aarch64-unknown-linux-musl.tar.gz

After download, extract, rename the executable to codex, and add it to PATH.

10Direct Binary Download · Installation Example

tar -xzf codex-x86_64-unknown-linux-musl.tar.gz mv codex-x86_64-unknown-linux-musl codex chmod +x codex sudo mv codex /usr/local/bin/

Verify installation:

codex --version

11Verifying Installation

After installation, check that Codex installed correctly:

codex --version

If successful, you'll see the version number.

codex-cli 0.136.0

Then run Codex:

codex

On first run, a login screen appears.

12Upgrading Codex

Codex updates frequently. New versions include model support, sandbox improvements, permissions, hooks, plugins, desktop integration, and bug fixes, so upgrade regularly.

Upgrade standalone installer

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Upgrade npm

npm install -g @openai/codex@latest

Upgrade Homebrew

brew update brew upgrade --cask codex

Verify after upgrade

codex --version

13Shell Completions Setup

Shell completions let you autocomplete Codex commands in the terminal.

bash

codex completion bash > /etc/bash_completion.d/codex

If you have permission issues, use sudo:

codex completion bash | sudo tee /etc/bash_completion.d/codex

zsh

mkdir -p ~/.zsh/completions codex completion zsh > ~/.zsh/completions/_codex

14Shell Completions Setup (continued)

If your ~/.zshrc doesn't have the completion path, add this:

fpath=(~/.zsh/completions $fpath) autoload -Uz compinit compinit

Apply:

source ~/.zshrc

fish

mkdir -p ~/.config/fish/completions codex completion fish > ~/.config/fish/completions/codex.fish

Apply:

source ~/.config/fish/config.fish

15First Run After Installation

After installation, navigate to your project folder:

cd my-project

Run Codex:

codex

On first run, you'll see a login prompt. For beginners, ChatGPT account login is recommended. API key method is also available, but some features may differ, so ChatGPT login is simplest initially.

16Pros and Cons by Installation Method

Standalone installer
Simplest, no npm needed | Recommended for macOS/Linux beginners
PowerShell installer
Windows official quickstart method | Recommended for Windows users
npm
Cross-platform, easy updates | Recommended for Node.js developers
Homebrew
Easy management on macOS | Recommended for macOS developers
winget
Windows package management | Recommended for advanced Windows users
Direct binary download
No package manager needed | Recommended for restricted servers/advanced users

17Troubleshooting PATH Issues

If codex command isn't recognized after installation, it's usually a PATH issue.

Error example:

codex: command not found

Windows PowerShell:

codex : The term 'codex' is not recognized

Check with:

which codex

Windows PowerShell:

where.exe codex

View current PATH:

echo $PATH

Windows PowerShell:

$env:Path

18Installation Security Notes

Since Codex accesses authentication tokens and project code, installation source is critical. Only use official sources:

Official OpenAI documentation Official openai/codex GitHub repository Official npm package @openai/codex Official installer URL

Recently, malicious npm packages targeting Codex developers have been reported stealing auth tokens.

Avoid similarly-named unofficial packages during installation.

Bad examples:

npm install -g codex npm install -g codex-ui npm install -g codexui-android

Recommended:

npm install -g @openai/codex

19Basic Commands to Try Right After Installation

After installation, verify in this order:

codex --version
codex

Run from project folder:

cd my-project codex

Or run as one-liner:

codex "Explain this project's structure"

20Troubleshooting ① · ②

Problem 1. Cannot find codex command

Symptom:

command not found: codex

Solution:

codex --version which codex echo $PATH

If using npm, reinstall:

npm install -g @openai/codex@latest

Problem 2. npm permission error

Symptom:

EACCES: permission denied

Simplest workaround is using standalone installer:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

21Troubleshooting ③ · ④

Set npm global prefix

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global'

Add to shell config file:

export PATH="$HOME/.npm-global/bin:$PATH"

Apply:

source ~/.zshrc

Or:

source ~/.bashrc

Problem 3. Windows PowerShell execution policy issue

Check current policy:

Get-ExecutionPolicy

Install command temporarily uses ByPass:

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

22Troubleshooting ⑤

Problem 4. Installed but no login screen appears

Check version first:

codex --version

Run again:

codex

If still problematic, it might be an existing config or auth file issue. See the next section on authentication.

Problem 5. Old version runs instead

Multiple installations might have old Codex in PATH first.

Check:

which codex codex --version

Windows:

where.exe codex codex --version

Clean up duplicates, then reinstall or upgrade.

23Installation Checklist for Beginners

You're done once you've checked all these:

□ Check OS
Chose installation method for my OS
□ Official source
Used only official installation commands
□ Verify version
codex --version works
□ Project folder
Can run codex from project folder
□ Login screen
Login screen appears on first run
□ npm package name
If npm install, verified package is @openai/codex
□ Unofficial packages
Didn't install unofficial Codex-like packages
Section 03 · Wrap-up

What to Remember from This Section

Codex can be used on macOS, Linux, and Windows. Recommended installation method varies by OS.

After installing, verify with codex --version, and avoid installing unofficial packages with similar names.
Next Section

Section 4. Authenticating Codex

4. Authenticating Codex

01Authentication Methods at a Glance

Here are the main authentication methods available in Codex.

ChatGPT OAuth
Most users —
codex login
Device Auth
Remote servers, environments where browser auto-launch is difficult —
codex login --device-auth
API Key
API-based usage, automation, separate key management environments —
codex login --with-api-key
Access Token
Advanced environments using already-issued access tokens —
codex login --with-access-token

For beginners, ChatGPT OAuth login is recommended.

02Logging In with ChatGPT Account

This is the most basic authentication method.

Run the following command in the terminal:

codex login

A browser will open—log in with your ChatGPT account. After logging in, return to the terminal and you can use Codex.

Check login status:

codex login status

If you're properly logged in, your current authentication mode will be displayed.

03Why ChatGPT Login Is Recommended

For first-time users, ChatGPT account login is easier than API Key.

Simple setup
Just log in through the browser
Less risk of key exposure
You don't handle API Key directly
Connected to account plan
You can use account permissions: Plus, Pro, Business, Enterprise, etc.
Easy integration with Desktop App and Cloud features
Suitable for account-based features

04Logging In with Device Auth

In environments where the browser doesn't open automatically, you can use Device Auth.

For example, it's useful in these situations:

Command:

codex login --device-auth

Running this command displays an authentication URL and code in the terminal. You can then open the URL in another device or browser and enter the code to log in.

05Device Auth Flow

The Device Auth process works as follows.

1Run codex login --device-auth on a remote server
2Terminal displays authentication URL and code
3Open the URL in your local browser
4Enter the code
5Log in with ChatGPT account
6Codex authentication on remote server completes

06Logging In with API Key

You can also authenticate Codex using an API Key. According to the official CLI reference, API Key is passed via stdin.

Example:

printenv OPENAI_API_KEY | codex login --with-api-key

Or you can enter it directly.

codex login --with-api-key

In this case, the terminal waits for you to input the API Key.

Security note: Avoid putting API Key directly in commands.

07API Key Input Methods

Bad example — exposing key in command:

codex login --with-api-key sk-...

Recommended method — using environment variables and stdin:

export OPENAI_API_KEY="sk-..." printenv OPENAI_API_KEY | codex login --with-api-key

This method is safer because the key doesn't remain in terminal history.

08When API Key Login Is Suitable

API Key login is appropriate for these situations.

CI/CD automation
Authentication possible without browser login
Server environments
Environment variable management is easier than account OAuth
Organization-level API usage management
Can be managed by API billing
SDK / automation scripts
Suitable for token-based execution flows

However, beginners risk exposing API Key while managing it directly, so ChatGPT OAuth login is recommended initially.

09Logging In with Access Token

In advanced environments, you can also pass an access token via stdin.

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

This method is used in automation environments that already securely issue and manage access tokens, rather than for general beginners.

Beginners typically don't need to use this method.

10Checking Login Status

To check if Codex is currently logged in, use the following command:

codex login status

This command displays your current authentication mode and returns exit code 0 if credentials exist.

Automation script example:

if codex login status >/dev/null 2>&1; then echo "Codex is logged in" else echo "Codex is not logged in" fi

Even beginners should run this command first if problems occur.

11Logging Out

To remove saved authentication credentials, use the following command:

codex logout

codex logout removes saved API keys and ChatGPT authentication information.

Logout is recommended in these situations:

Used on a shared computer
Protect your account
Before returning company equipment
Remove authentication information
When switching to another account
Prevent existing authentication conflicts
When replacing API Key
Remove old key

12Configuring Credential Storage Method

Codex must save authentication information so you don't have to log in again next time. The credential storage method can be set with cli_auth_credentials_store in config.toml.

file
Store credentials in a file
keyring
Use operating system keychain or secure storage
auto
Use keyring if possible, fall back to file if not

For beginners, auto is recommended. For company equipment where security is critical, consider using keyring.

13Enforcing Login Method

In organization or team environments, you may want to restrict login methods. This is possible with the forced_login_method setting in config.toml.

Enforce ChatGPT login only:

forced_login_method = "chatgpt"

Or you can mandate API Key method only:

forced_login_method = "api"

This setting is more important for teams, companies, and enterprise environments than for individual beginners.

14Difference Between MCP OAuth and Codex Login

Two kinds of authentication can appear in Codex.

Codex Login
Permission to use Codex CLI itself
MCP OAuth Login
Permission to use a specific MCP server or external service

To log in to Codex itself:

codex login

To log in to an MCP server:

codex mcp login <server-name>

Beginners should complete Codex login first and cover MCP later in the external service integration section.

15Cautions When Using Multiple Accounts

If you use both personal and company accounts, authentication conflicts can occur.

Recommended method:

Personal projects → Personal ChatGPT account Company projects → Company workspace account Automation / CI → API Key

When switching accounts, follow this sequence:

codex logout codex login codex login status

16Authentication and Plan Permissions

When you log in with a ChatGPT account, available Codex features may vary depending on your account plan and organization settings.

Factors that affect availability:

Exact limits and available features can vary depending on account status and organization settings, so if there are problems, check your login status first.

17Security Notes for Authentication Information

API Keys and access tokens should be treated similarly to passwords.

Never do:

- Commit API Key to GitHub - Paste API Key in README - Share API Key directly on Slack, Discord, etc. - Enter key in ways that remain in terminal history - Log in to suspicious Codex-like packages from unknown sources

When using API Key as an environment variable, add .env to .gitignore so it doesn't get committed to git:

.env .env.local *.key

18Troubleshooting Authentication

Problem 1. Codex keeps asking to log in even though I've logged in

First, check the status:

codex login status

If it says there's no login information, log in again. If it persists, log out and log in again:

codex logout codex login

Problem 2. Browser won't open

In environments where browser auto-launch doesn't work, use Device Auth:

codex login --device-auth

19Troubleshooting Authentication (Continued)

Problem 3. Cannot log in from a remote server

On SSH servers or headless environments, use the following method:

codex login --device-auth

Or API Key method:

printenv OPENAI_API_KEY | codex login --with-api-key

Problem 4. API Key doesn't work

Check: Is the environment variable name correct? • Is the actual value not empty? • Are there no spaces before or after the key? • Is the key not revoked or rotated? • Is API usage allowed in your organization?

echo "$OPENAI_API_KEY"

20Troubleshooting Authentication (Additional)

Problem 5. A different account is logged in

Check the current status:

codex login status

Remove existing authentication:

codex logout

Log in again:

codex login

Problem 6. Authentication fails in CI

In CI, usually register the API Key as a secret, then pass it via stdin:

printenv OPENAI_API_KEY | codex login --with-api-key

21Authentication Checklist for Beginners

Codex installation is complete
□
codex --version outputs normally
□
Ran codex login
□
Completed ChatGPT account login in browser
□
Verified login status with codex login status
□
Run codex logout after use on shared computer
□
If using API Key, don't expose in terminal or Git
□
On remote servers, use codex login --device-auth
□

22Recommended Authentication Flow

For beginners, proceed in this order:

codex --version codex login codex login status codex

For remote servers, use this flow:

codex --version codex login --device-auth codex login status codex

For automation environments, use this flow:

printenv OPENAI_API_KEY | codex login --with-api-key codex login status
Section 04 · Wrap-up

What to Remember from This Unit

Codex requires authentication after installation. For beginners, codex login with ChatGPT account is the simplest method. In server environments where you can't open a browser, use codex login --device-auth, and in automation environments, pass API Key via stdin.

Check login status with codex login status, log out with codex logout, and never expose API Keys and access tokens in code repositories or chat.
Next Section

Section 5. Quick Start: Starting Your First Session

5. Quick Start: Starting Your First Session

01Goals of the First Session

In your first session, you only need to learn the following flow.

  1. Move to the project folder.
  2. Run Codex.
  3. Have it explain the project structure.
  4. Request a small task.
  5. Review the changes.
  6. Run tests if needed.
  7. End the session.

You don't need to attempt large refactoring or automation from the start. The goal of the first session is to get a feel for how Codex works in your project.

02Prerequisites

First, you need to have the following items ready.

Codex Installation
codex --version
Codex Login
codex login status
Git Project
A project with .git folder
Terminal
macOS Terminal, iTerm2, Linux shell, PowerShell, etc.
Code Editor
VS Code, Cursor, Windsurf, etc.

Verify installation and login:

codex --version codex login status

If installation and login are working properly, you can start your first session.

03Navigate to Project Folder

Codex understands your project based on the folder where your terminal is located. First, navigate to your project folder.

cd ~/my-project

For a Git project, you can verify it like this:

git status

If it's a normal project, your current branch and change status will be displayed.

On branch main nothing to commit, working tree clean

For beginners, it's better to start practice on a test project or personal project, not a critical production project.

04Running Codex

Run Codex from your project folder.

codex

An interactive Codex screen will open inside your terminal. This screen is usually called TUI, short for Terminal UI.

Once Codex is running, you can make requests in natural language.

Explain what this project structure is like.

For the first request, it's better to have it read and explain the project rather than request code changes.

05First Request: Have It Explain Project Structure

Enter your first request like this:

Explain this project's structure in a way that beginners can understand. Organize the main folders, how to run it, testing methods, and core entry points.

Codex usually checks the following:

At this stage, focus on understanding the project without modifying files.

06Examples of Good First Questions

Here are examples of good first questions for understanding your project.

Technology Stack
Explain what technology stack this project is built with.
Local Execution
Tell me the sequence to run this project locally.
Running Tests
Find what command runs tests.
Role-based Organization
Organize core folders and files by their roles.

07Second Request: Ask for a Small Task

Once you understand the project structure, request a small task. For the first time, safe documentation edits or minor code improvements are good choices.

If README doesn't have a local execution method section, add one.

Or:

Check how input validation is done in the login API, and if changes are needed, explain what should be changed first.

For beginners, the first task should have a small change scope and low risk.

08Recommended First Tasks

README improvements
Low risk and easy diff review
Finding test commands
Understand project without code changes
Explaining specific functions
Safe since it's reading-focused
Adding small validation
Good for learning the code modification flow
Improving comments
Small change scope

Requests to avoid from the start:

In the first session, small and clear tasks are best.

09Complex Tasks Start with /plan

If a task is even slightly complex, don't execute it directly—use /plan.

/plan I want to add input validation to the login API. Find related files, check existing validation methods and test locations, then propose a step-by-step work plan first.

/plan makes Codex organize its approach before modifying files.

Small tasks affecting 1-2 files → can request directly / Tasks likely changing 3+ files → use /plan first

10When /plan Is Useful

Multiple files may change
Must check scope first
Don't know existing structure well
Can modify wrong files
Authentication, payment, permission tasks
High risk
Refactoring
Must predict impact scope
Adding tests
Must see existing test structure first

11Intervening While Codex Works

You can correct direction even while Codex is working.

Not that file—focus on src/auth/login.ts.

If you want to change test scope:

Instead of all tests, run only login-related tests first.

If you want to reduce scope:

For now, just analyze—don't modify code.

Beginners should understand that Codex doesn't always perfectly match your intent on the first try, and you can keep adjusting direction during work.

12Reviewing Changes: /diff

If Codex modifies files, you must review the changes.

/diff

/diff shows changes Codex made in the current session. Items to check:

Changed files
Did only intended files change?
Change scope
Too much code change?
Existing behavior
Existing APIs or UIs not broken?
Tests
Related tests added or modified?
Security
Sensitive information not exposed?
Style
Matches project code style?
If Codex modifies files, always check /diff.

13When to Always Check /diff

Especially check /diff after these tasks:

The most important habit for beginners is this:

If Codex modifies files, always check /diff.

14Running Tests

After reviewing changes, run related tests. You can have Codex find the test command.

Find the command to run related tests in this project.

Or request directly:

Run tests related to the part I just modified and summarize the results.

Example test commands:

npm test pytest pnpm test cargo test go test ./...

When tests fail, it's better to have Codex analyze the cause first rather than immediately asking to fix it.

15Requesting Work Summary

When work is done, request a summary from Codex.

Summarize the changes in this session. Organize changed files, key modifications, tests run, and remaining TODOs.

Good summary format:

Changed files: - src/auth/login.ts - src/auth/login.test.ts Key changes: - Added email format validation - Return 400 response for invalid email input - Preserved existing error response format Tests: - Ran npm test -- login - All related tests passed

This summary is also useful when writing commit messages or PR descriptions.

16Ending the Session

When work is done, exit Codex.

/quit

Or:

/exit

Return to the terminal and check Git status.

git status git diff

Review the changes again and commit if needed.

git add . git commit -m "Add login email validation"

Beginners should thoroughly review changes made by Codex before committing.

17Complete First Session Example Flow

Here's a complete example of a first session.

cd ~/my-project codex

Inside Codex, enter:

Explain this project's structure in a way that beginners can understand. Organize main folders, how to run it, testing methods, and core entry points.

Request a small task:

If README doesn't have a local execution method section, add one. Write it to match the existing README style.

Review changes:

/diff

Verify and summarize, then exit:

18Starting with a One-Line Command

Codex can start without opening an interactive TUI, directly passing a prompt.

codex "Explain this project's structure"

Or:

codex "Analyze why the test failed"

This method is useful for quick questions. However, beginners should start with interactive mode.

codex

In interactive mode, it's easier to follow what files Codex reads and what tasks it's trying to accomplish.

19Sample Prompts to Try in First Session (1)

Understanding the Project

You can use these prompts right in your first session:

Explain the entire structure of this project. Organize main folders and files by their roles.
Find and explain step-by-step how to run this project locally.
Tell me the testing execution method and main test folders.

Understanding Code

Trace how the login feature works through which files.
Explain the flow from API request to response in this project.
Find where the database connection configuration is.

20Sample Prompts to Try in First Session (2)

Safe Modifications

If README doesn't have an installation method section, add one. Keep the existing tone and format.
/plan I want to add input validation to the signup API. Find existing validation patterns first and propose a work plan.
If there's no unit test for this function, propose a test addition plan first.

Verification

Run tests related to the part I just modified.
If there are test failures, analyze the cause but don't fix immediately—tell me the fix plan.
Review if this change risks breaking existing behavior.

21Prompts to Avoid in First Session

Avoid requests that are too broad or vague.

Bad examples:

Improve this entire project for me.
Make all code quality good.
Optimize the architecture yourself.
Fix all tests and deploy too.

These requests have overly broad change scope and Codex may move in unintended directions.

Good examples:

/plan Analyze the login flow in src/auth and propose a refactoring plan to reduce duplicate validation logic. Don't modify code yet.
Improve only the local execution method section in README. Keep the format and don't change code.

22Recommended Safety Settings for First Session

For the first session, this combination is recommended:

sandbox_mode = "workspace-write" approval_policy = "on-request"
workspace-write
Allow read/write centered on current project
on-request
Request user approval for risky or out-of-scope actions

If you want to start more cautiously, you can run in read-only mode:

codex --sandbox read-only

Read-only mode is suitable for project analysis, structure explanation, and code review. If you want to actually modify files, use workspace-write.

codex --sandbox workspace-write --ask-for-approval on-request

23Things to Check After First Session

After your first session ends, check the following:

git status git diff

Check:

Revert unnecessary changes:

git checkout -- path/to/file

Delete unnecessary new files:

rm path/to/file

24First Session Checklist for Beginners

Project navigation
Moved to project folder
Status check
Verified current status with git status
Running Codex
Ran codex
Structure explanation
Requested project structure explanation
Small task
Requested one small task
Plan first
Used /plan for complex tasks
diff review
Reviewed /diff after changes
Testing/verification
Verified related tests or verification method
Work summary
Requested work summary
Exiting
Exited with /quit or /exit
Final check
Rechecked git status and git diff from terminal
Section 05 · Wrap-up

What to Remember from This Unit

The goal of the first session is to learn the Codex usage flow. You don't need to know all complex features from the start.

Navigate to project folder → run codex → request structure explanation → request small task → review /diff → run tests → exit

As you repeat this flow, remember these:

Next Section

Section 6. Codex Core Interfaces

6. Codex Core Interfaces

01Interfaces at a Glance

Codex is not a tool used in just one interface. You can use the same Codex agent across CLI, Desktop App, IDE Extension, Cloud, Chrome Extension and other interfaces.

CLI
Run Codex from the terminal
Desktop App
Manage multiple tasks visually
IDE Extension
Use Codex directly in your editor
Codex Cloud / Web
Delegate time-consuming tasks to the cloud
Chrome Extension
Web tasks requiring logged-in browser state

02Getting Started Guide for Beginners

Beginners don't need to use all interfaces from the start. Begin with CLI or IDE Extension, then expand to Desktop App or Cloud as work grows.

The most important thing is to establish a workflow that safely completes small tasks from start to finish.

03Interface Selection Criteria

For starters, choose based on these criteria:

Want to work quickly from the terminal → CLI Want to see and edit code in the editor → IDE Extension Want to run multiple tasks simultaneously and see diffs visually → Desktop App Want to delegate long-running tasks → Codex Cloud / Web Need to work on logged-in websites or admin pages → Chrome Extension

In practice, you'll mix these based on the situation.

04Real-World Usage Example

You might use it like this:

1. Analyze codebase structure with CLI 2. Modify current file with IDE Extension 3. Run large refactoring in parallel with Desktop App 4. Delegate long-term work to Cloud 5. Verify logged-in dashboard with Chrome Extension

05CLI: Terminal-Centered Interface

CLI is Codex's most basic usage method. Run the following command from your project folder:

codex

Or pass a starting prompt directly:

codex "Explain this project structure"

06When CLI Is Good

CLI works well in these situations:

Quick code analysis
Run immediately from terminal
Small bug fixes
Quickly verify change scope
Running tests
Naturally connects with shell commands
Checking git diff
Fits terminal workflow
Automation
Can connect with codex exec
CI/CD
Suitable for non-interactive execution
Server environments
Usable without GUI

07How to Start with CLI

Beginners should start with this flow:

cd my-project codex

Enter inside Codex:

Explain this project's structure and how to run it.

For complex tasks, plan first:

/plan I want to add input validation to the login API. Find related files and propose a work plan.

Review changes after modification:

/diff

08CLI Interactive TUI

When you run codex, an interactive screen opens inside the terminal. This is called TUI, or Terminal UI.

In TUI, you can:

Natural language requests
Instruct Codex on tasks
File references
Attach files with @
Shell commands
Execute with !command format
Slash commands
Use /plan, /diff, /status, etc.
Intervening mid-work
Adjust direction while working
Reviewing diffs
Check changes
Changing models
Switch models mid-session

09CLI TUI Example

Real usage example:

@src/auth/login.ts Explain the login flow in this file.
!npm test
/status

10Frequently Used Commands in CLI

Commands beginners should learn first:

/plan
Plan before execution
/diff
Review changes
/status
Check current session status
/model
Change model
/compact
Summarize long conversation
/review
Code review
/permissions
Check or adjust permissions
/resume
Resume previous session
/quit
Exit

Just learning these three initially is enough:

/plan /diff /status

11Desktop App: Task Management Interface

The Desktop App is a visual interface for using Codex. If CLI is terminal-centered, the Desktop App is more like an operations command center for managing multiple Codex tasks.

Key advantages of Desktop App:

12When Desktop App Is Good

Multiple tasks in parallel
Manage separately per thread
Large refactoring
Visually track work flow
Want to review diffs easily
Git change review is easy
Running Codex tasks in parallel
Can use worktree isolation
Team unfamiliar with terminal
GUI is more accessible
Manage automation tasks
View flow within the app

Suitable task examples:

13Can I Start with Desktop App Before CLI?

Yes, you can.

If you're unfamiliar with terminals, Desktop App might be more convenient. However, considering development automation and CI/CD, learning CLI eventually is good.

Recommended order:

Comfortable with terminal → Start with CLI Prefer editor and GUI → Start with IDE Extension or Desktop App Want to delegate multiple tasks simultaneously → Use Desktop App Want to automate → Learn CLI and codex exec

14IDE Extension: Using Codex Inside Your Editor

IDE Extension is the way to use Codex inside editors like VS Code, Cursor, and Windsurf.

Codex IDE Extension has these characteristics:

15When IDE Extension Is Good

Edit while viewing current file
Directly use editor context
Inline edit needed
Good for file location-centered tasks
Function-level modification
Quickly apply small changes
Fix test failures immediately
Good for compile-test loop
Questions during code review
Can explain based on selected code
Beginners prefer editor over terminal
Lower barrier to entry

Example requests:

Make exception handling in this function more robust. Find duplicate logic in current file and clean it up. Add tests for this component.

16Difference Between IDE Extension and CLI

Execution location
CLI
IDE Extension
Execution location
Terminal
Code editor
Advantages
Fast, strong in automation
Easy to work while viewing code
File selection
@file, search-centered
Current open file and selection-centered
Test execution
Naturally connects with shell commands
Connects with editor workflow
Recommended tasks
Repo analysis, automation, diff review
Current file modification, inline edit
Beginner difficulty
Requires terminal experience
Relatively easier

IDE Extension is good for modifying "the code you're currently viewing", while CLI is good for "analyzing the entire project or automating".

17Codex Cloud / Codex Web: Cloud Task Interface

Codex Cloud or Codex Web is the way to delegate tasks to Codex in a cloud environment rather than your local computer.

Codex Cloud characteristics:

18When Cloud Is Good

Long-running tasks
Don't need to wait locally
Multiple issues
Good for parallel delegation
Large refactoring
Can separate into independent tasks
PR creation
Can connect work results to PR
Reduce local resource burden
Run in cloud environment
Background tasks
Can proceed while doing other work

Suitable tasks:

19Cautions When Using Cloud

Cloud is powerful, but beginners don't need to delegate all tasks to Cloud initially.

Cloud is suitable for tasks meeting these conditions:

Conversely, it's better to do these initially with local CLI or IDE:

20Chrome Extension: Browser-Based Interface

Codex Chrome Extension is the interface to use when Codex needs to read or manipulate websites using Chrome.

Codex Chrome Extension characteristics:

21When Chrome Extension Is Good

Verify logged-in site
Use existing browser session
Admin page tasks
Web UI manipulation needed
SaaS tool verification
Can work screen-based without API
Internal dashboard inspection
Login state and UI context needed
CMS content verification
Web page-based modification flow
Bug reproduction
Can verify actual browser screen

Suitable tasks:

22Difference Between In-app Browser and Chrome Extension

Codex has both the Desktop App's in-app browser and Chrome Extension.

Location
In-app Browser: Inside Codex App
Chrome Extension: User's Chrome
Suitable tasks
In-app Browser: Local dev server, public page preview
Chrome Extension: Logged-in sites, internal tools
Login state
In-app Browser: Limited
Chrome Extension: Use user's browser state
Beginner usage
In-app Browser: For web UI feedback
Chrome Extension: For actual web work automation

Simply put:

Want to view my built web app screen with Codex → In-app Browser Codex needs to work on actually logged-in site → Chrome Extension

23Computer Use: When GUI Tasks Are Needed

Computer Use is a feature for when Codex needs to view and manipulate graphical interfaces.

Computer Use characteristics:

Suitable tasks:

Beginners don't need to use Computer Use initially. First learn CLI, IDE, and Desktop App, then use Computer Use when GUI tasks are absolutely necessary.

24Recommended Interfaces by Task

Project structure analysis
CLI
Current file modification
IDE Extension
Small bug fix
CLI or IDE
Large refactoring
CLI /plan or Desktop App
Multiple parallel tasks
Desktop App
Delegating long-term work
Codex Cloud
PR creation work
Codex Cloud or Desktop App
Web app screen review
Desktop App In-app Browser
Work on logged-in site
Chrome Extension
GUI app manipulation
Computer Use
Automation script
CLI codex exec
CI/CD connection
CLI codex exec

25Recommended Learning Order for Beginners

Beginners should learn in this order:

  1. Have CLI explain project structure
  2. Learn /plan and /diff in CLI
  3. Try modifying current file with IDE Extension
  4. Visually view changes in Desktop App
  5. Delegate small independent tasks to Cloud
  6. Use Chrome Extension when needed

Most important is creating a workflow that safely completes small tasks from start to finish, not using all interfaces from the start.

26CLI vs Desktop App Selection Criteria

Can finish quickly from terminal?
CLI
Multiple tasks simultaneously?
Desktop App
Want to see Git diff visually?
Desktop App
Will run as automation script?
CLI
Will attach to CI/CD?
CLI
Team unfamiliar with terminal?
Desktop App
Want fine-grained control?
CLI

Summary:

Fast direct development work → CLI Manage multiple tasks and review visually → Desktop App

27Using IDE and CLI Together

In practice, using IDE and CLI together is good.

Example flow:

  1. Analyze entire project structure with CLI
  2. Open related files in IDE
  3. Modify functions at function-level with IDE Extension
  4. Run tests with CLI
  5. Review diff with CLI or Desktop App
  6. Commit with Git

Real command example:

codex "Find how login feature works through which files"

Open related files in IDE:

Strengthen input validation in this function to match existing style.

Back to CLI:

npm test git diff

This way, you divide overall analysis to CLI, fine-grained modifications to IDE, and verification back to CLI.

28Safety Tips per Interface

CLI

Desktop App

IDE Extension

Codex Cloud

Chrome Extension

29Common Interface Usage Mistakes for Beginners

Delegating large tasks to Cloud from start
Result review can be difficult
Committing without checking /diff in CLI
Can miss unintended changes
Running too many parallel tasks in Desktop App
Merge conflicts and review burden increase
IDE viewing only current file, ignoring structure
Can miss impact scope
Granting Chrome Extension too many site permissions
Security risk increases
Using Computer Use unnecessarily
GUI manipulation may have low predictability

Beginners should apply the same principle across all interfaces: "make small requests, check diff, test".

30Interface Selection Summary

CLI The foundation. Quickly analyze, modify, and test from terminal. Desktop App Manage multiple tasks, worktrees, visual diffs, automation. IDE Extension Fast editing centered on current file and selection. Codex Cloud / Web Delegate long independent tasks to background. Chrome Extension Browser tasks on logged-in sites or internal tools. Computer Use Tasks requiring viewing and manipulating GUI apps.
Section 06 · Wrap-up

What to Remember from This Unit

Codex can be used from multiple interfaces: CLI, Desktop App, IDE Extension, Cloud, and Chrome Extension.
Next Section

Section 7. CLI Basics

7. Basic CLI Usage

01Basic CLI Execution

The most basic command is:

codex

Run it from your project folder.

cd ~/my-project codex

This opens an interactive Codex conversation screen in your terminal. You can request tasks from Codex in natural language.

Examples:

Explain the structure of this project. Analyze which files the login feature goes through. Find the cause of the failing test.

02Run with One-Line Prompt

You can also open the interactive screen and send your first request at the same time.

codex "Explain this project's structure"

Or:

codex "Analyze why the tests are failing"

This approach is good for quick questions or one-off tasks.

codex "Read package.json and tell me the run and test commands for this project"

However, beginners are recommended to open the interactive screen with just codex and proceed from there. It's easier to follow what Codex is doing in interactive mode.

03Why You Should Run from Your Project Folder

Codex understands the project based on your current terminal location.

Good example:

cd ~/projects/my-app codex

Bad example:

cd ~ codex

Running from outside the project makes it hard for Codex to find relevant files. Always verify your location before running Codex.

pwd

Check if it's a Git project.

git status

It's good to develop a habit of checking git status before running Codex.

04Specifying the Model

You can specify which model to use when running Codex.

codex -m gpt-5.5

Or specify it along with the prompt:

codex -m gpt-5.5 "Analyze the authentication structure of this project"

-m is the short form of --model.

codex --model gpt-5.5 "Review this code"

Model selection affects task difficulty and cost.

Simple questions
Fast model
General code edits
Default model
Complex debugging
Strong reasoning model
Security review
High reasoning effort
Large-scale refactoring
Strong model + /plan

Beginners can just use the default model at first.

05Setting Reasoning Effort

Codex lets you set how deeply the model should reason.

codex -c model_reasoning_effort="medium"

For complex issues, you can increase it:

codex -c model_reasoning_effort="high" "Find the cause of this race condition"

For security audits or complex architecture analysis:

codex -c model_reasoning_effort="xhigh" "Review this authentication module for security vulnerabilities"

However, higher reasoning effort uses more tokens and costs. A good beginner default is:

model_reasoning_effort = "medium"

06Specifying Sandbox Mode

Sandbox settings are important because Codex can read and modify real files.

codex --sandbox workspace-write

You can also run in read-only mode:

codex --sandbox read-only

There's also full access mode:

codex --sandbox danger-full-access

However, beginners should avoid using danger-full-access.

read-only
Read-only (for analysis and review)
workspace-write
Read/write in workspace (recommended default)
danger-full-access
Full system access (not recommended)

07Setting Approval Policy

The approval policy determines when Codex asks for user approval.

codex --ask-for-approval on-request

When used together with sandbox:

codex --sandbox workspace-write --ask-for-approval on-request
untrusted
Request approval for most non-read operations
on-request
Proceed with normal work, request approval for risky tasks
never
Proceed without requesting approval

The recommended beginner combination lets you work on actual tasks while stopping for confirmation on risky operations.

08When You Just Want to Analyze Safely

If you're seeing a project for the first time, starting in read-only mode is a good idea.

codex --sandbox read-only

In this mode, you can make requests like:

Explain this project's structure. Analyze which files the login feature uses. Find how to run tests. Review potential security issues without modifying code.

Read-only mode is safe for beginners since Codex can't modify files.

09Attaching Files: @

In the TUI, use @ to find and attach files to the Codex conversation.

@src/auth/login.ts Explain the login flow in this file.

Or:

@package.json Explain the scripts in this project.

Specifying files clearly helps Codex answer more accurately.

Good example:

@src/api/users.ts Find areas in this file where input validation is insufficient.

Bad example:

Find problems in the entire project.

The narrower the scope, the better Codex's results.

10Running Shell Commands: !

In the TUI, add ! to execute shell commands directly.

!npm test !git status !pnpm lint !pytest

This feature is useful for running commands directly during a Codex conversation and checking results.

!git diff !npm run test:unit

Note that command execution is subject to sandbox and approval settings. Risky commands may trigger approval requests.

11Opening External Editor

When you need to write a long prompt in the TUI, you can open an external editor. Ctrl+G is the shortcut to open the editor set in \$VISUAL or \$EDITOR.

Usage flow:

  1. Press Ctrl+G in Codex TUI
  2. External editor opens
  3. Write your long instructions
  4. Save and close
  5. Input appears in Codex input field

Useful for writing lengthy task instructions.

12Searching Previous Input History

In Codex TUI, you can recall previously entered prompts. Usually arrow keys browse draft history.

↑ Previous input ↓ Next input

Ctrl+R is used to search previous prompts and slash command history.

Ctrl+R

You can then find and reuse previous /plan, /diff, task requests, etc.

13Giving Additional Instructions While Codex Works

You can adjust direction while Codex is working. For example, if Codex is looking at the wrong file:

Focus on src/auth/login.ts instead, not that file.

If you want to narrow the scope:

This time, just analyze without modifying code.

If you want to change the test scope:

Run only login-related tests first instead of all tests.

The key point is that you don't have to hand off the work and abandon it—you can keep adjusting direction in the middle.

14Editing Previous Message

Press Escape twice to edit the previous message.

Use cases:

Example:

Original input: Fix the login feature.

After edit: /plan Analyze the login feature's input validation flow, propose what needs fixing and a test plan first. Don't modify code yet.

Beginners should correct vague requests right away.

15Starting a New Conversation

To start a new conversation within the same Codex session, use /new.

/new

Use cases:

Then your new request: Explain the deployment structure of this project.

16Resuming Previous Session

If you want to reopen a saved conversation, use /resume.

/resume

Or you can use resume options when running CLI.

Useful situations:

However, when continuing an old session, code state may have changed, so verify first.

Check the current git state and what files changed since the last session.

17Forking a Conversation

If you want to continue the current conversation in a different direction, use /fork.

/fork

Example use case:

Keep the current refactoring direction A and also compare with a more conservative direction B

Fork copies existing conversation context and continues in a new thread. Beginners don't need to use it often at first, but it's useful for comparing alternatives.

18Changing Model: /model

You can change models in the middle of a session too.

/model

Use cases:

You can also specify the model when running CLI.

codex -m gpt-5.5

During a session, use /model.

19Summarizing Long Conversations: /compact

When conversation gets long, context can fill up. Use /compact in this case.

/compact

/compact summarizes long conversation content to free up context space.

Use cases:

Beginners can use /compact in the middle of long work and then request: "Based on the summary of work so far, proceed with just the next step."

20Reviewing Changes: /diff

If Codex modified files, you must check with /diff.

/diff

Things to check:

Beginner principle: If Codex modified something, always check /diff.

21Requesting Code Review: /review

If you want to review the current working tree, use /review.

/review

Use cases:

More specific example:

/review Focus on security issues, missing tests, and API compatibility in these changes.

22Checking Current Status: /status

To check the current session state, use /status.

/status

What you can check varies by version and environment, but generally includes:

It's good to develop a habit of checking /status first when problems arise.

23Checking Permissions: /permissions

To check or adjust Codex permissions, use /permissions.

/permissions

Use cases:

Beginners should check current state first before raising permissions arbitrarily. If asked for risky permissions, verify the reason before deciding to grant them.

24Checking Apps and MCP

To check external tools connected to Codex, use:

/mcp /apps

/mcp is used to check configured MCP tools. /apps is used to explore ChatGPT connectors.

Beginners don't need to know about MCP or Apps at first. Learn them later when you need to connect external tools.

25Checking Skills

To check available skills or invoke them, use /skills.

/skills

Skills are useful for standardizing repetitive tasks. For example:

A good flow is to request directly via prompt at first, and manage as skills when patterns repeat.

26Checking Plugins

To check or manage installed plugins, use /plugins.

/plugins

Plugins are a system for extending Codex functionality. Beginners should first learn the basics, then use only plugins needed for the team or project.

27Difference Between Direct Shell Commands and Codex Requests

In the TUI, you can either run shell commands directly or request Codex to execute them.

Direct execution:

!npm test

Request from Codex:

Find and run the relevant tests, then summarize the results.
!npm test
User specifies the command directly
Natural language request
Codex finds appropriate commands and executes

Beginners find it easier to have Codex find commands at first.

28Relationship Between CLI Options and config

Codex reads config.toml settings, but you can override values via CLI options.

For example, even if config has a default model:

model = "gpt-5.5"

Specifying a different model at runtime makes the CLI option take priority for that execution.

codex -m gpt-5.4 "Review this code"

Inline config override is also possible.

codex -c model_reasoning_effort="high" "Analyze this bug"

Nested settings can also be specified.

codex -c 'sandbox_workspace_write.network_access=true' "Install dependencies"

Remember for beginners: Options you give directly at runtime take priority over config.

29Running with Profile

You can use profiles, which are bundles of settings for different task types.

codex --profile fast "Explain this function" codex --profile careful "Security review of this auth logic" codex --profile ci "Analyze why this test failed"

Profiles will be covered in detail in the configuration section later, but the basic concept is:

fast
Quick questions, simple edits
careful
Security, architecture, complex debugging
ci
Automation, CI/CD
pair
Real-time pairing

30Example: Read-Only Code Review Run

If you want to analyze a new project safely without modifications:

codex --sandbox read-only

Inside Codex:

Analyze the authentication flow in this project. Don't modify code, just identify security risks.

Or in one command:

codex --sandbox read-only "Analyze the authentication flow and list security risks without modifying code."

31Example: General Development Work Run

For everyday development, this combination works well:

codex --sandbox workspace-write --ask-for-approval on-request

Inside Codex:

/plan I want to add password length validation to the signup API. Check existing validation patterns and test locations, then propose a plan first.

After confirming plan: Proceed with the plan.

After changes: /diff

Testing: Run relevant tests and summarize results.

32Example: Quick Question Run

Simple questions can be handled in one command:

codex "Explain the scripts in package.json" codex "Find the command to run the dev server in this project" codex "Summarize the role of the src/auth folder"

This approach is fast, but interactive TUI is better for long tasks.

33Safe CLI Working Routine for Beginners

Beginners should repeat this routine:

  1. Check git status
  2. Run codex
  3. Request project or task scope explanation
  4. Use /plan if complex
  5. Approve changes
  6. Check /diff
  7. Run tests
  8. Request work summary
  9. /quit
  10. Verify git status and git diff in terminal again

Actual command flow:

git status codex

Inside Codex: /plan I want to add email validation to the login API. Check existing code style and test locations first.

After changes: /diff

After exiting: git status, git diff

34Common Beginner Mistakes in CLI

Running codex outside project
Hard to find relevant files
Requesting large tasks right away
Change scope becomes too broad
Requesting refactoring without /plan
Can be modified in wrong direction
Committing without /diff
Can miss unintended changes
Abusing danger-full-access
Risk to entire system
Skipping test execution
Can miss change errors
Using vague prompts
Results may not match expectations

35Good CLI Prompt Example ①

Project analysis

Explain this project's structure so beginners can understand. Organize the main folders, how to run it, how to test it, and key entry points.

Feature flow analysis

Trace which files a login request goes through until the response comes out. Explain without modifying code.

36Good CLI Prompt Example ②

Safe refactoring plan

/plan I want to reduce duplicate validation logic in the src/auth folder. Organize existing structure, impact scope, and test plan first. Don't modify files yet.

Small edit

If README doesn't have a local run section, add one. Keep existing style and format.

Test execution

Find and run test commands related to the changes I just made, and analyze failures if there are any.

37Bad CLI Prompt Examples

Avoid requests with broad and vague scope like these:

Fix all the code. Make this project better. Refactor everything. Optimize it however you want.

Better approach:

/plan Propose a way to reduce duplicate error handling logic in the src/api folder. Explain impact and test plan first, don't modify code yet.

38Basic CLI Commands Summary

codex
Run interactive CLI
codex "prompt"
Run with initial prompt
codex -m model-name
Specify model
codex --sandbox read-only
Run read-only
codex --sandbox workspace-write
Allow workspace writes
codex --ask-for-approval on-request
Request approval when needed
codex --profile fast
Use profile
codex -c key=value
Temporary config override

39Basic TUI Controls Summary

@
Search and attach files
!command
Execute shell command directly
Ctrl+G
Open external editor
Ctrl+R
Search previous input
Esc twice
Edit previous message
/plan
Plan mode
/diff
Review changes
/status
Check status
/quit
Exit
Section 07 · Wrap-up

What to Remember from This Unit

CLI is Codex's most basic and powerful usage method. Run codex from your project folder to open an interactive TUI where you can work with terminal and project files together.

3 key things beginners must remember:

Run from project folder → Start with /plan if complex → Review with /diff after changes

All advanced features (profile, MCP, plugin) can be learned later. Getting comfortable with the basic flow is most important.

Next Section

Section 8. Complete Slash Commands Guide

8. Complete Slash Commands Guide

01What Are Slash Commands?

Slash Commands are commands in Codex interactive CLI starting with /.

/plan /diff /status

If regular prompts are "requesting Codex in natural language", Slash Commands are commands for quickly executing session control, model changes, permission checks, diff review, work planning, review, and configuration checking.

02Main Slash Commands List

Slash Commands are typically used for:

Work planning
/plan
Review changes
/diff
Check session status
/status
Change model
/model
Summarize conversation
/compact
Check permissions
/permissions
Code review
/review
Exit session
/quit

Beginners only need to learn these 5: /plan, /diff, /status, /permissions, /quit.

03Basic Slash Command Usage

Typing / in Codex TUI shows the available commands list.

Solo execution example

/diff

Execution with description example

/plan I want to improve the error handling structure of the payment module. Propose impact scope and step-by-step plan first.

Some commands run standalone, others accept descriptions after them.

04Slash Command Full List (1/2)

/quit, /exit
Exit Codex (high importance)
/new
Start new conversation (medium)
/resume
Resume previous conversation (medium)
/fork
Branch current conversation to new thread (medium)
/model
Change model (high)
/compact
Summarize long conversation (high)
/diff
Review changes (very high)

05Slash Command Full List (2/2)

/review
Code review (high)
/plan
Plan work before execution (very high)
/goal
Manage ongoing work goals (medium)
/vim
Switch Vim edit mode (low)
/hooks
Explore and switch hooks (medium)
/mention
Attach files (medium)
/init
Generate AGENTS.md scaffold (high)

06Slash Command Full List (3/3)

/status
Check session status (very high)
/permissions
Check and adjust permissions (very high)
/personality
Adjust response style (low)
/mcp
Check MCP tools (medium)
/apps
Explore ChatGPT connectors (low)
/ps
Check background terminals (medium)
/skills
Check and invoke skills (medium)

07Remaining Slash Commands

/plugins
Manage plugins (medium)
/title
Set terminal window title (low)
/config
Check current config (high)
/statusline
Set TUI footer (low)
/feedback
Send logs and feedback (low)
/logout
Log out (medium)

08/quit or /exit

Exits the Codex CLI.

/quit or /exit

Both end the session.

Use cases

After exiting, it's good to verify changes again in terminal:

git status git diff

09/new

Starts a new conversation within the current Codex session.

/new

Use cases

Starting completely different work
Prevents previous context from interfering
Conversation became too long
Reorganizes into new flow
Want to try experimental requests
Separates from existing work flow

Note: /new doesn't undo Git changes. File modifications persist, so verify with /diff or git diff if needed.

10/resume

Reopens a previously saved conversation.

/resume

Use cases

After resuming, verify code state hasn't changed:

Check the current git state and what files changed since the last session.

11/fork

Branches current conversation to a new thread.

/fork

/fork is used when you want to experiment in a different direction while maintaining current conversation context.

Usage examples

Beginners don't need to use it often at first, but it's useful for comparing alternatives.

12/model

Changes the model for the current session.

/model

Use cases

Simple questions
Switch to fast model
Complex bug analysis
Switch to strong model
Security review
Use high-reasoning model
Cost reduction
Use cheaper model

Beginners can just use the default model at first.

13/compact

Summarizes long conversation content to free up context space.

/compact

Codex uses conversation content, read files, command output, and work plans as context. When conversation gets long, context fills up and Codex may miss previous content.

Use cases

14/diff

Reviews changes made in the current session.

/diff

One of the most critical commands for beginners. If Codex modifies files, you must run /diff.

Things to check

Changed files
Did only intended files change?
Change scope
Is there too much code changed?
Logic
Does it preserve existing behavior?
Tests
Were tests added or modified?

15/diff Follow-up Usage

After reviewing changes, you can request more from Codex:

Review if there are unnecessary changes in this diff. Keep only the README edits from these changes and revert the code changes.

Common follow-up requests

16/review

Reviews the current working tree or changes.

/review

Use cases

You can make more specific requests too:

/review Focus on security issues, missing tests, and existing API compatibility in these changes.

17/plan

Plans work before modifying files directly.

/plan I want to add input validation to the login API. Find related files, check existing validation patterns and test locations, then propose a step-by-step plan first.

/plan is the most critical command for beginners. For complex work, verify the plan before executing.

18/plan Usage Guidelines

When should you use /plan?

Multiple files will change
Understand scope first
Unfamiliar codebase
Understand structure first
Auth/payment/permission work
High risk
Large-scale refactoring
Broad impact

Beginner guideline

Use /plan first if 3+ files will likely change.

19/goal

Creates or manages ongoing work goals.

/goal

/goal is used to create, pause, resume, or delete maintained work goals.

Use cases

Beginners should learn /plan first and use /goal when long-term work is needed.

20/vim, /hooks, /mention

/vim

Switches Vim edit mode in TUI composer.

/vim

For users familiar with Vim key bindings.

/hooks

Explores or switches Codex lifecycle hooks. Manages automatic actions that run before or after specific events.

/mention

Attaches files to conversation.

@src/auth/login.ts Explain the login flow in this file.

21/init

Creates AGENTS.md scaffold for the project.

/init

AGENTS.md is a file where you write rules Codex should follow in the project.

Content that can be included

# AGENTS.md ## Development Rules - Run tests after code changes. - Keep existing public API behavior. - Follow the existing code style. - Add tests for new behavior.

/init is very useful when first using Codex in a project.

22/status

Checks current session status.

/status

Things you can check

One of the first things to check when problems arise.

23/permissions

Checks or adjusts current permissions and approval settings.

/permissions

Use cases

Beginners should check status first with /permissions before raising permissions arbitrarily. Verify reason if asked for risky permissions.

Don't use danger-full-access as a beginner default.

24/personality, /mcp, /apps

/personality

Adjusts Codex communication style. Options include friendly, pragmatic, none and similar styles.

/mcp

Checks configured MCP tools. Manages connections with external tools like GitHub, Figma, Sentry, databases etc.

/apps

Explores ChatGPT connectors or connectable apps. Check status of connected external business tools.

25/ps, /skills, /plugins

/ps

Shows background terminals. Use when Codex is running background terminal tasks.

/skills

Checks available skills or invokes them. Skills are reusable work knowledge that help Codex perform specific tasks better.

/plugins

Explores and manages installed plugins. Check installed plugins, enable/disable, explore marketplace plugins.

26/title, /config, /statusline

/title

Sets terminal window title.

/title auth-refactor

Useful when multiple Codex sessions are open to distinguish windows.

/config

Prints current applied config values and sources. Check what config is active and detect user/project config conflicts.

/statusline

Sets TUI footer. Organize information like model, context, git branch nicely.

27/feedback, /logout

/feedback

Sends logs and feedback to Codex maintainers.

/feedback

Use to report Codex bugs or unusual behavior. Verify no sensitive info is included before sending.

/logout

Logs out from Codex.

/logout or from terminal: codex logout

28Slash Commands Beginners Must Learn First

You don't need to learn all commands from the start. Start with these 7:

/plan
Don't execute complex tasks immediately, plan first
/diff
Review what Codex changed
/status
Check current session status
/permissions
Check permissions and sandbox status
/review
Review changes
/compact
Organize long conversation
/quit
Exit

29Beginner Basic Routine

Most work is safe if you follow this routine:

1/plan Verify work plan
2/diff Review changes
3/review Review changes in detail
4/status Check status if problems arise
5/quit Exit

30Slash Command Recommendations by Task Type

Analyzing new project
/plan, /status
Small code edit
/diff, /review
Large refactoring
/plan, /goal, /compact, /diff
Security check
/review, /permissions, /plan
Long debugging
/compact, /status, /ps
Fixing permission issues
/permissions, /config
Checking external tools
/mcp, /apps

31Good /plan Usage Example

Authentication refactoring

/plan I want to refactor the login flow in the src/auth folder. Analyze current structure, duplicate logic, risks, and test plan first. Don't modify code yet.

Adding tests

/plan I want to add tests for the signup API. Check existing test structure first, then propose what cases should be added.

32Good /review Usage Example

General review

/review

Security-focused review

/review Focus on auth bypass, missing permission checks, and sensitive data exposure risks.

Test-focused review

/review Focus on insufficient testing and missing edge cases.

33Good /diff Follow-up Request Example

After viewing /diff, you can request more:

Find unnecessary changes in this diff. Summarize these changes as a commit message. Write a PR description based on this diff. Tell me which parts of this change need testing. Review if these changes could break existing behavior.

34Combining Slash Commands and Regular Prompts

Bad example

/plan /review

Good example

/plan I want to organize the error handling in the payment module. Analyze current structure, propose change scope and test plan first.
/review Focus on security issues, performance degradation, and missing tests in these changes.

Commands work alone, but results improve when you add criteria.

35Slash Command Cautions

1. /new doesn't undo changes

/new only starts a new conversation. File changes persist, verify with /diff or git diff.

2. /compact is not a silver bullet

/compact summarizes long conversation but some details may compress. Keep important requirements in AGENTS.md or separate docs.

3. Don't arbitrarily raise permissions at /permissions

When Codex requests more permissions, verify the reason and check if narrower permissions solve it.

36More Cautions

4. /review doesn't replace human review

/review is powerful but final review should be human. Especially for auth, payment, security, database changes.

5. /goal is for long-term work

Simple work needs only /plan. Use /goal when multi-stage long-term goals exist.

37Slash Command Real Routine - Safe Code Editing

Basic routine

/plan Create work plan → Verify plan → Proceed with edits → /diff → /review → Run tests → Summarize → /quit

Specific example

/plan I want to add email format validation to the login API. Check existing validation patterns and test structure first.

38Slash Command Real Routine - Debugging and Setup

Long debugging routine

/status → /plan → Analyze possible causes → Run tests → /compact → Make fixes → /diff → /review

Project initial setup routine

/init → Edit AGENTS.md → /config → /permissions → /status

39Slash Command Quick Reference

/quit, /exit
Exit Codex
/new, /resume, /fork
Manage conversations
/model, /compact
Session settings
/diff, /review, /plan
Core work commands
/goal, /vim, /hooks
Advanced features
/mention, /init
Project management
/status, /permissions, /config
Status checks
/personality, /mcp, /apps
External connections
/ps, /skills, /plugins
Tool management
/title, /statusline
UI settings
/feedback, /logout
Account management
Section 08 · Wrap-up

What to Remember from This Unit

Slash Commands are powerful tools for controlling sessions, reviewing code, and planning work in Codex CLI.

The most critical for beginners is the /plan → /diff → /review routine. These three alone enable safe and efficient work.

Next Section

Section 10. Model Selection Guide

9. Understanding config.toml

01Codex Configuration Priority

Codex interprets settings in this order. Higher positions have higher priority.

1
CLI flags, --config — Temporary settings applied only for this run
2
Project .codex/config.toml — Settings for current project or subdirectory only
3
--profile profile file — Settings for specific work mode
4
User config — Personal default settings
5
System config — System-wide default settings
6
Built-in defaults — Codex built-in defaults

For example, even if you set a default model in ~/.codex/config.toml, running with CLI options wins for that execution:

codex --model gpt-5.5

Or override any key directly:

codex --config model='"gpt-5.5"' codex --config sandbox_workspace_write.network_access=true

--config values parse as TOML, not JSON. Be careful with string quoting.

02User Config

User config is personal default settings.

Default location:

~/.codex/config.toml

Codex CLI and IDE extensions share the same config layer. So default model, approval policy, sandbox settings, and MCP server settings configured in CLI can apply the same way in IDE extensions.

User config typically contains:

model = "gpt-5.5" approval_policy = "on-request" sandbox_mode = "workspace-write" web_search = "cached"
model
Default model to use
approval_policy
How to request approval before commands
sandbox_mode
File system and network access scope
web_search
Web search usage method
[mcp_servers.*]
MCP server connection settings
[features]
Feature flag settings

approval_policy can use untrusted, on-request, never, and sandbox_mode can use read-only, workspace-write, danger-full-access.

03Project Config

Project config applies only to specific repos or subdirectories.

Location:

<repo>/.codex/config.toml

Codex traverses from project root to current directory looking for .codex/config.toml. When same key appears multiple times, the config closest to current directory wins. However, project config only loads when project is trusted. In untrusted projects, project .codex/ layer, project hooks, and rules are ignored.

Example:

my-app/ .codex/config.toml frontend/ .codex/config.toml

If current location is my-app/frontend, frontend/.codex/config.toml is closer so applies first for same keys.

Project config should contain only project work methods:

model_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = false

Settings bound to machine or personal accounts like provider, auth, telemetry, notification may be ignored in project config.

04System Config

System config applies system-wide defaults. Unix location:

/etc/codex/config.toml

Priority is lower than User config. When system admin sets defaults, users can override same keys in ~/.codex/config.toml and User config wins.

System config is "common defaults" rather than "forced policy".

Example:

approval_policy = "on-request" sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = false

For values organizations must block, use requirements.toml instead of System config.

05Managed requirements.toml

requirements.toml is not a regular config file but admin-enforced constraints. Even if users specify different values in config.toml, profiles, or CLI options, when conflicting with requirements, Codex restores compatible values and notifies user.

Can restrict values like:

allowed_approval_policies = ["untrusted", "on-request"] allowed_sandbox_modes = ["read-only", "workspace-write"] allowed_web_search_modes = ["disabled", "cached"]

Example above blocks:

approval_policy = "never" sandbox_mode = "danger-full-access" web_search = "live"

Requirements layer priority:

1
Cloud-managed requirements
2
macOS MDM requirements_toml_base64
3
System requirements.toml

Important: requirements.toml sets "allowed range" rather than "configured values".

06Understanding CODEX_HOME

CODEX_HOME is Codex's local state root directory. Default:

~/.codex

Usually contains:

~/.codex/ config.toml auth.json history.jsonl log/ sessions/ skills/

You can set CODEX_HOME via environment variable, but the target directory must pre-exist.

mkdir -p ~/.codex-work CODEX_HOME=~/.codex-work codex

Then Codex uses instead of default ~/.codex/config.toml:

~/.codex-work/config.toml

Useful in practice for separating accounts, organizations, and test environments.

07Basic config.toml Structure

In TOML, writing root keys first then tables is more readable. Basic structure:

# 1. Root settings model = "gpt-5.5" model_reasoning_effort = "medium" approval_policy = "on-request" sandbox_mode = "workspace-write" web_search = "cached" # 2. Sandbox detail settings [sandbox_workspace_write] network_access = false writable_roots = [] # 3. Environment variable pass policy [shell_environment_policy] inherit = "core" include_only = ["PATH", "HOME", "USER", "SHELL"] # 4. Feature flags [features] hooks = true undo = true # 5. MCP server config example [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] enabled = true

Common values:

approval_policy
"on-request" — Ask user when needed
sandbox_mode
"workspace-write" — Allow writes in workspace
web_search
"cached" — Cache-based web search
model_reasoning_effort
"medium" or "high" — Reasoning strength
sandbox_workspace_write.network_access
false — Block network in sandbox

08Minimal Config for Beginners

Start without opening too much:

model = "gpt-5.5" approval_policy = "on-request" sandbox_mode = "workspace-write" web_search = "cached" [sandbox_workspace_write] network_access = false

Intent is simple:

on-request
Ask on risky or out-of-scope work
workspace-write
Can work within project
network_access = false
Prevent arbitrary network access
web_search = "cached"
Enable basic search but limit live fetch

Beginners should avoid danger-full-access and approval_policy = "never" combo.

09Recommended Config for Professionals

Professionals want both productivity and safety:

model = "gpt-5.5" model_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" web_search = "cached" hide_agent_reasoning = true [sandbox_workspace_write] network_access = false writable_roots = [] [shell_environment_policy] inherit = "core" include_only = [ "PATH", "HOME", "USER", "SHELL", "LANG", "LC_ALL", "TERM" ] [features] hooks = true undo = true shell_snapshot = true [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] enabled = true startup_timeout_sec = 10 tool_timeout_sec = 60

Professional guidelines:

Default workspace-write
Enable project work but block full system
Approval on-request
Explicitly verify risky work
Network blocked by default
Enable per-project or approval-based
MCP in User config priority
Provider/auth is more stable in user config than project config
Project differences in .codex/config.toml
Separate only per-repo reasoning strength and sandbox by repo

10Config Conflict: Step 1 (CLI Options)

When settings don't apply as expected, check in this order:

Step 1: Check if CLI options were given

CLI options and --config have highest priority.

codex --model gpt-5.5 codex --config sandbox_mode='"read-only"'

Test without options:

codex

11Config Conflict: Step 2 (Project Config)

Step 2: Check project config in current directory

Nearby .codex/config.toml takes priority over user config.

pwd find .. -path "*/.codex/config.toml" -print

If project is untrusted, project config may be ignored. Check trusted status too.

12Config Conflict: Step 3 (Profile)

Step 3: Check if --profile is used

Using profile overlays this file on top of user config:

~/.codex/<profile-name>.config.toml

Example:

codex --profile deep-review

After Codex 0.134.0, uses separate profile-name.config.toml files instead of [profiles.name] in config.toml.

13Config Conflict: Step 4 (CODEX_HOME)

Step 4: Verify actual CODEX_HOME

Changing CODEX_HOME changes which config file is read:

echo $CODEX_HOME

If empty, default is:

~/.codex/config.toml

If set, check:

$CODEX_HOME/config.toml

14Config Conflict: Step 5 (Requirements)

Step 5: Check requirements policy

Even after all config changes, management policy might be blocking:

Check file:

/etc/codex/requirements.toml

On Windows:

%ProgramData%OpenAICodex equirements.toml

Check especially:

allowed_approval_policies = ["on-request"] allowed_sandbox_modes = ["workspace-write"] allowed_web_search_modes = ["disabled", "cached"]

Requirements is unyielding by users. On conflict, Codex restores compatible values.

15Config Conflict: Step 6 (Project Ignored Keys)

Step 6: Check if project config uses ignored keys

Some keys in project .codex/config.toml are always ignored:

Keys to avoid in project:

openai_base_url = "..." model_provider = "..." notify = [...] profile = "..." [model_providers.foo] [otel]

Put these in user config:

~/.codex/config.toml

16Config Conflict: Step 7 (TOML Syntax)

Step 7: Verify TOML syntax

Common mistakes:

# Wrong: string quotes missing model = gpt-5.5 # Correct model = "gpt-5.5"
# Wrong: mixing root keys under table confuses [sandbox_workspace_write] network_access = false model = "gpt-5.5"

For readability, write root keys first then [table].

Section 09 · Wrap-up

What to Remember from This Unit

config.toml sets Codex default behavior. Most basic location is ~/.codex/config.toml, and per-project differences go in <repo>/.codex/config.toml.

Priority flows top to bottom and is strong. CLI options are strongest, project config beats user config. Organization security policy is managed via requirements.toml, and these values can't be bypassed by normal config.

CLI options → Project settings → Profiles → User settings → System settings → Built-in defaults
Next Section

Section 10. Model Selection Guide

10. Model Selection Guide

01First, Clarification: Models and Reasoning Effort Are Different

In Codex, these two settings are different.

model = "gpt-5.5" model_reasoning_effort = "xhigh"

model specifies which AI model to use. model_reasoning_effort specifies how deeply that model should think.

So, "using Codex 5.5 xhigh" precisely means:

Use the gpt-5.5 model while raising reasoning effort to xhigh.

02Current Model List to Use as Baseline in Codex

The models covered as core in the current Codex guide are:

gpt-5.5
Default recommended model. Complex coding, computer use, knowledge work, research
gpt-5.4
Recommended model. Performance and cost balance
gpt-5.4-mini
Recommended model. Fast and cheap routine coding, subagents
gpt-5.3-codex
Codex-specialized model. Code review, cloud work, professional agentic coding
gpt-5.3-codex-spark
Research preview. Pro users' near-instant coding iteration
gpt-5.2
Alternative model. Previous generation replacement

03gpt-5.5: Default Recommended Model

gpt-5.5 is the primary model you should choose first in Codex. It's the latest frontier model suitable for complex coding, computer use, knowledge work, and research workflows.

Recommended situations:

Large feature implementation
Plan, modify, verify flow is stable
Refactoring
Must view multiple files and dependencies together
Bug tracking
Root cause analysis and fix strategy needed
Document, spreadsheet, slide generation
Knowledge work quality is good inside Codex
Tasks involving browser or app interaction
Good for computer use and tool use
Solving uncertain problems
High-level reasoning required

Recommended setting:

model = "gpt-5.5" model_reasoning_effort = "medium"

On difficult tasks you can raise to xhigh, but it's better to use xhigh only for work where mistakes are costly, like large refactoring, long-term planning, complex debugging, and security reviews.

04gpt-5.4: Balance of Cost and Performance

gpt-5.4 is a cost and performance balance model one step below gpt-5.5. As a professional workhorse frontier model, it combines stronger reasoning, tool use, and agentic workflow capability with the coding ability of gpt-5.3-codex.

Recommended situations:

General feature addition
Don't need gpt-5.5 level
Medium-scale bug fixes
Cost and quality balance
Repetitive code modifications
Sufficient quality and better usage efficiency
Test enhancement
Lower burden on large-scale work
Quick experimentation
Can save advanced model usage

Configuration example:

model = "gpt-5.4" model_reasoning_effort = "medium"

05gpt-5.4-mini: Fast Routine Work and Subagent Model

gpt-5.4-mini is suitable for lightweight and fast work. It's a fast and efficient mini model fit for responsive coding tasks and subagents, providing higher usage limits in routine local messages.

Recommended situations:

Simple function modification
No need for heavy reasoning
Type error fixes
Narrow scope
Document phrasing fixes
Can be processed quickly
Test name changes
Simple repetitive work
Subagent parallel exploration
Good cost and speed efficiency
Simple pattern changes across many files
Prevent advanced model waste

Configuration example:

model = "gpt-5.4-mini" model_reasoning_effort = "low"

Beginners can remember: "simple work with mini, complex work with 5.5".

06gpt-5.3-codex: Code Review, Cloud Work, Professional Coding Model

gpt-5.3-codex is, as its name suggests, a Codex-specialized model. It's the industry-leading coding model for complex software engineering, and its coding ability is reflected in gpt-5.4. Cloud tasks and code reviews run on gpt-5.3-codex.

Recommended situations:

PR review
Core model of Codex code review
Cloud task
Directly connected to cloud work
Complex codebase analysis
Strong in agentic coding
Long-running tasks
Specialized in code change flow
Test failure analysis
Good for code-centric judgment

Configuration example:

model = "gpt-5.3-codex" model_reasoning_effort = "high"

07gpt-5.3-codex-spark: Ultra-Fast Research Preview Model for Pro

gpt-5.3-codex-spark is not so much a "highest quality model" but a special model for fast coding iteration. It's a text-only research preview model optimized for near-instant, real-time coding iteration and is provided to ChatGPT Pro users.

Recommended situations:

Real-time code ideas
Response speed is critical
Small modification iteration
Fast round-trip is key
UI text, simple code sketches
Speed over deep reasoning
Prototype exploration
Immediacy is important

Execution example:

codex -m gpt-5.3-codex-spark

Spark is a research preview, guided for Pro users only, and is a model chosen for fast iteration inside Codex rather than a generally used model in APIs.

08When do gpt-5.2 and Legacy Models Show Up?

gpt-5.2 is currently classified as an alternative model in Codex model documentation. It's a previous generation general-purpose model that can be used as an alternative choice for difficult debugging or agentic tasks requiring deep contemplation.

But there's no need to make it a central model for beginner guides.

Also, names like gpt-5.1-codex-mini shouldn't be included in the current table of contents. In the full API model list, GPT-5.1 Codex mini is marked as deprecated.

Summary:

gpt-5.5
Core model
gpt-5.4
Secondary core model
gpt-5.4-mini
Core model for lightweight work
gpt-5.3-codex
Core Codex-specialized model
gpt-5.3-codex-spark
Pro research preview with separate explanation
gpt-5.2
Brief explanation as alternative
gpt-5.1-codex-mini
Removed from table of contents as legacy/deprecated

09xhigh is Not a Model Name but Reasoning Intensity

Using gpt-5.5 and xhigh together is a very powerful combination in practice.

model = "gpt-5.5" model_reasoning_effort = "xhigh"

This combination is good for:

Large-scale refactoring
Review scope more deeply
Complex bug analysis
Narrow down root cause candidates more persistently
Security review
Reduce likelihood of omission
Architecture design
Tradeoff review is important
Migration planning
Must consider stages and risks together
Long document generation
Maintaining structure and consistency is important

Conversely, xhigh may be overkill for these tasks:

Simple text edits
low
Simple type errors
low or medium
Adding small functions
medium
Changing test names
low
Organizing imports
minimal or low

10Model Selection Table by Task Type

Analyzing unfamiliar codebase
gpt-5.5 + high
Large refactoring planning
gpt-5.5 + xhigh
Complex bug fixes
gpt-5.5 + high or xhigh
General feature addition
gpt-5.5 or gpt-5.4 + medium
Simple code fixes
gpt-5.4-mini + low
Adding tests
gpt-5.4 or gpt-5.4-mini + medium
PR review
gpt-5.3-codex + high
Codex Cloud task
gpt-5.3-codex + default
Fast code iteration
gpt-5.3-codex-spark + default
Documentation and guides
gpt-5.5 + high
Security review
gpt-5.5 + xhigh
Subagent parallel exploration
gpt-5.4-mini + low or medium

11Beginner Recommended Combinations

Beginners should avoid changing models too much from the start. One combination is enough:

model = "gpt-5.5" model_reasoning_effort = "medium"

This combination offers the best balance of quality, speed, and cost.

If you want to be safer:

model = "gpt-5.5" model_reasoning_effort = "high"

For truly critical work:

model = "gpt-5.5" model_reasoning_effort = "xhigh"

Beginner recommendation rule is simple.

Not sure
gpt-5.5 + medium
Important code change
gpt-5.5 + high
High cost of failure
gpt-5.5 + xhigh
Light repetitive work
gpt-5.4-mini + low

12Professional Recommended Combinations

Professionals should split profiles by task type.

For basic work

model = "gpt-5.5" model_reasoning_effort = "medium"

For deep analysis

model = "gpt-5.5" model_reasoning_effort = "xhigh"

For fast routine work

model = "gpt-5.4-mini" model_reasoning_effort = "low"

For code review

model = "gpt-5.3-codex" model_reasoning_effort = "high"

For cost-saving general work

model = "gpt-5.4" model_reasoning_effort = "medium"

13Setting Default Model in config.toml

Set the default model in ~/.codex/config.toml.

# ~/.codex/config.toml model = "gpt-5.5" model_reasoning_effort = "medium"

If you want to use it strongly like your style:

# ~/.codex/config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh"

However, handling all work with xhigh can increase response time and usage consumption. xhigh is described as for the most difficult asynchronous agentic tasks or evals testing model intelligence limits.

Example professional profile:

# ~/.codex/deep.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh"

Execution:

codex --profile deep

14Changing Models in CLI and IDE

In the CLI, use -m or --model to start a new session with a specific model.

codex -m gpt-5.5 codex -m gpt-5.4 codex -m gpt-5.4-mini codex -m gpt-5.3-codex

In the CLI you can use -m or --model flag, and during an active CLI session you can switch models with the /model command. In IDE extensions, use the model selector below the input box.

In an active session:

/model

Override just once:

codex --model gpt-5.5

To override reasoning effort one-time too:

codex -m gpt-5.5 -c model_reasoning_effort='"xhigh"'

15How to Choose Based on Cost, Speed, Quality

Model selection can be judged in this order:

Step 1: Is it critical work?

If critical, use gpt-5.5.

model = "gpt-5.5" model_reasoning_effort = "high"

More critical:

model = "gpt-5.5" model_reasoning_effort = "xhigh"

Step 2: Is it repetitive work?

If repetitive and simple, use gpt-5.4-mini.

model = "gpt-5.4-mini" model_reasoning_effort = "low"

Step 3: Is it code review or cloud work?

For code review and cloud tasks, gpt-5.3-codex is important.

Step 4: Is speed the top priority?

If you're a Pro user and need near-instant coding iteration, consider gpt-5.3-codex-spark. Spark is not Fast mode but a separate model, provided as a research preview.

Step 5: Want to run faster?

Fast mode is not a separate model but a speed setting that runs supported models faster. Fast mode currently supports gpt-5.5 and gpt-5.4 and consumes more credits.

In the CLI:

/fast on /fast off /fast status

You can also set it as a default in config.

service_tier = "fast" [features] fast_mode = true
Section 10 · Wrap-up
Most Codex work starts with gpt-5.5. Use gpt-5.4-mini for lightweight repetitive work, and gpt-5.3-codex is important for code review and cloud work. xhigh is not a model name but reasoning intensity.
Next Section

Section 11. Reasoning Effort

11. Reasoning Effort

01What is Reasoning Effort?

Reasoning effort is a setting that determines how deeply the model should think before generating an answer.

If choosing a model in Codex is deciding "who will work," reasoning effort is deciding "how carefully they will work."

For example:

model = "gpt-5.5" model_reasoning_effort = "xhigh"

This means "use the gpt-5.5 model at the highest reasoning intensity."

02How Reasoning Models Work

Reasoning models use internal reasoning tokens to decompose problems, review multiple approaches, and plan tool use before writing the final answer. This is especially suitable for complex problem-solving, coding, scientific reasoning, and multi-step agentic workflows.

The important point is that these reasoning tokens are not shown directly to users. However, according to API documentation, reasoning tokens consume context window space and are charged as output tokens.

So, raising reasoning effort usually creates these changes:

Quality
Can improve on complex tasks
Speed
May get slower
Cost
May increase due to reasoning tokens
Stability
Planning, review, tool use may become more careful
Over-reasoning
May become unnecessarily long on simple tasks

03Codex Config Key: model_reasoning_effort

The default reasoning intensity in Codex is set in config.toml.

model_reasoning_effort = "medium"

According to Codex configuration reference, model_reasoning_effort supports these values. However, xhigh support varies by model.

minimal low medium high xhigh

Basic example

model = "gpt-5.5" model_reasoning_effort = "medium"

Deep analysis example

model = "gpt-5.5" model_reasoning_effort = "xhigh"

04minimal: Think Little and Be Fast

minimal is the lowest reasoning effort in Codex config.

Recommended situations:

Simple text edits
No deep judgment needed
Organizing imports
Rule-based work
Short explanation requests
Fast response is important
Finding simple file location
Search is more important than reasoning
Fixed format conversion
Almost no creative judgment

Example

model = "gpt-5.4-mini" model_reasoning_effort = "minimal"

However, if code changes connect to actual file edits, it's safer to use at least low.

05low: Light Reasoning Work

low is suitable for fast work, but causes a bit more thinking than minimal.

Recommended situations:

Modifying small functions
Simple context judgment needed
Type error fixes
Error cause confirmation needed
Changing test names
Simple but prevent mistakes
Code style cleanup
Rule application focused
Document summary
Compression more important than deep analysis

In practice, low is good for "light but annoying if wrong." The gpt-5.4-mini + low combination is especially good for fast iteration or subagent work.

06medium: Default Recommended Balance Point

medium is the most reasonable default for most users.

The GPT-5.5 documentation states that the default reasoning effort is medium, and it's the balance point between quality, reliability, latency, and cost.

Recommended situations:

General feature addition
Moderate planning and implementation needed
Normal difficulty bug fixes
Root cause analysis needed
Writing tests
Code understanding and validation needed
Writing documentation
Structuring needed
Work on new projects
Too low may miss things

Beginner basic recommendation

model = "gpt-5.5" model_reasoning_effort = "medium"

07high: Complex Coding and Analysis

high is a setting that makes the model solve complex problems more carefully.

Recommended situations:

Feature addition spanning multiple files
Impact scope review needed
Analyzing test failure causes
Need to compare root cause candidates
Refactoring planning
Structural judgment needed
Code review
Need to check for omissions and side effects
API design
Interface and extensibility judgment needed
Pre-deployment review
Cost of mistakes is high

Example

model = "gpt-5.5" model_reasoning_effort = "high"

08xhigh: Deepest Reasoning for Highest Difficulty Work

xhigh is the strongest reasoning intensity.

The GPT-5.5 documentation says to use high or xhigh when quality improvement justifies added latency and cost. In particular, xhigh is suitable for the most difficult asynchronous agentic tasks or evals testing model intelligence limits.

Recommended situations:

Large-scale refactoring
Review entire structure and side effects
Security review
Reduce omission risk
Complex incident analysis
Compare multiple root cause candidates
Architecture design
Review pros, cons, and future extensibility
Migration planning
Stage-by-stage risk management
Long document and guide writing
Maintain structural consistency
Critical automation design
Cost of failure is high

However, xhigh is not always the right answer. The GPT-5.5 documentation explains that higher reasoning effort is not always better, and over-exploration or quality degradation can occur if the criterion is weak or tool access is open.

09Difference Between none and minimal

In the API documentation, GPT-5.5 reasoning effort values are none, low, medium, high, xhigh.

But in Codex config.toml's model_reasoning_effort values are:

minimal low medium high xhigh

So in Codex config files, use minimal.

API reasoning.effort values
none, low, medium, high, xhigh
Codex model_reasoning_effort values
minimal, low, medium, high, xhigh

As a Codex user, remember to use minimal as the baseline in config.toml.

10Plan Mode-Specific Setting: plan_mode_reasoning_effort

Plan Mode often needs deeper reasoning than general answers. So Codex has a separate Plan Mode override: plan_mode_reasoning_effort.

Example

model = "gpt-5.5" model_reasoning_effort = "medium" # Think deeper in /plan mode plan_mode_reasoning_effort = "high"

This setting is quite useful in practice. Work fast on general tasks, deliberate on planning.

Recommended combinations:

General effort
Plan Mode effort
Use case
low
medium
Fast workers
medium
high
General professionals
high
xhigh
Careful design and review focus
xhigh
xhigh
Maximum caution mode

11Difference from reasoning_summary

model_reasoning_summary is different from model_reasoning_effort.

model_reasoning_effort
Determines how deeply the model thinks
model_reasoning_summary
Determines how much reasoning-related summary to show

According to Codex configuration reference, model_reasoning_summary values are:

auto concise detailed none

Example

model = "gpt-5.5" model_reasoning_effort = "high" model_reasoning_summary = "concise"

Beginners usually prefer the default auto or concise concise. Showing reasoning summary in detail does not make the model think deeper. The setting that makes it think deeper is model_reasoning_effort.

12Difference from verbosity

model_verbosity is also different from model_reasoning_effort.

model_reasoning_effort
Depth of thinking
model_verbosity
Length and detail of final answer

For example, this setting means "think deeply but answer briefly."

model = "gpt-5.5" model_reasoning_effort = "xhigh" model_verbosity = "low"

Conversely, this setting means "think moderately and explain in detail."

model = "gpt-5.5" model_reasoning_effort = "medium" model_verbosity = "high"

Practical combinations:

Deep judgment + short conclusion
xhigh + low verbosity
Learning explanation
medium/high + high verbosity
Code review
high + medium verbosity
Documentation writing
high + high verbosity

13Impact on Token Cost and Speed

Raising reasoning effort may increase internal reasoning tokens. According to API documentation, reasoning tokens are not visible to users but consume context window and are charged as output tokens.

So this formula applies:

Higher reasoning effort = Deeper review possible = Longer wait time possible = Higher token usage possible

However, GPT-5.5 has improved to produce stronger results with fewer reasoning tokens at the same reasoning effort compared to previous models.

Practical guide:

Must finish quickly
minimal or low
Quality and speed balance
medium
Important code change
high
High cost of failure
xhigh

14Recommended Settings by Task Type

Recommended reasoning effort varies by task type.

Simple Q&A
minimal or low
Text editing
minimal
Organizing imports
minimal
Fixing small functions
low
Resolving type errors
low or medium
Adding general features
medium
Writing tests
medium
Analyzing unfamiliar codebase
high
Tracing bug causes
high
Multi-file refactoring
high or xhigh
Security review
xhigh
Architecture design
xhigh
Migration planning
xhigh
Plan Mode
high or xhigh

15Beginner Recommended Settings and Professional Profiles

Beginner basic settings:

model = "gpt-5.5" model_reasoning_effort = "medium" model_reasoning_summary = "auto" model_verbosity = "medium"

Recommended professional profile setup:

For basic work
medium + plan_mode high
For deep analysis
xhigh + xhigh
For fast work
gpt-5.4-mini + low
For code review
gpt-5.3-codex + high
Maximum caution mode
gpt-5.5 + xhigh

Beginners need to remember only one standard.

minimal = fastest / low = light work / medium = default recommended / high = complex work / xhigh = highest difficulty with high cost of failure
Section 11 · Wrap-up

What to Remember from This Unit

Reasoning effort is a setting that determines "thinking depth" of the model. In Codex, the basic key is model_reasoning_effort, and available values are minimal, low, medium, high, xhigh.

Beginner recommendation:

model = "gpt-5.5" model_reasoning_effort = "medium" plan_mode_reasoning_effort = "high"

The one principle to remember: if the task is simple, set it low; if complex and high cost of failure, set it high.

Next Section

Section 12. Understanding Codex Costs

12. Understanding Codex Costs

01One-Sentence Summary of Codex Cost Structure

Codex costs work as follows: Consume included usage from your ChatGPT plan first, then when you exceed the limit, additional costs are charged via credits or API token billing. Codex is included in Free, Go, Plus, Pro, Business, Edu, and Enterprise plans, but usage limits and additional billing methods vary by plan.

ChatGPT login usage = plan included usage + credits if needed API Key usage = OpenAI API token billing Business/Enterprise = seat + workspace credits + admin spend control

02Codex Inclusion by ChatGPT Plan

Free
Limited inclusion (Codex credits not available for purchase, Plus upgrade encouraged)
Go
Lightweight work inclusion (Codex credits not available for purchase, Plus upgrade encouraged)
Plus
Included (can purchase credits if exceeded), about 30,000 KRW/month
Pro 5x
5x Plus usage, about 150,000 KRW/month
Pro 20x
20x Plus usage, about 300,000 KRW/month
Business
Included as standard seat or Codex seat
Enterprise / Edu
Contract-based, flexible pricing or per-seat usage limit
API Key
Separate from subscription, API token billing

03Free / Go

Codex is included in both Free and Go. Free is for exploring quick coding tasks, and Go is for lightweight coding tasks.

Free
0 KRW/month, limited Codex experience
Go
About 12,000 KRW/month, lightweight Codex work

The important limitation is that Free and Go users cannot purchase additional Codex credits when limits are exceeded; instead, they're encouraged to upgrade to Plus. Free and Go users receive an upgrade prompt rather than a credit purchase option.

04Plus

Plus costs about 30,000 KRW/month and includes Codex web, CLI, IDE extension, iOS, cloud-based integrations, automatic code review, Slack integration, GPT-5.5, GPT-5.4, GPT-5.3-Codex, and GPT-5.4-mini.

Price
About 30,000 KRW/month
Local Codex
Supported
CLI / IDE
Supported
Cloud task
Supported, based on GPT-5.3-Codex
Code review
Supported, based on GPT-5.3-Codex
Additional credits
Supported
Recommended for
Individuals who have focused coding sessions a few times per week

Plus users first consume included usage, and when limits are reached, can purchase credits to continue. Credits can be managed in Codex Settings > Usage > Credits or the Usage Dashboard.

05Pro 5x / Pro 20x

Pro splits into two tiers.

Pro 5x
About 150,000 KRW/month, 5x Plus usage
Pro 20x
About 300,000 KRW/month, 20x Plus usage

Pro at about 150,000 KRW provides 5x higher usage than Plus, and Pro at about 300,000 KRW provides 20x higher usage than Plus. The existing about 300,000 KRW Pro is maintained, and about 150,000 KRW Pro is a lower-priced Pro option.

Pro offers all Plus Codex features plus access to GPT-5.3-Codex-Spark research preview. Spark is described as a fast day-to-day coding model for Pro users.

06Business

Business has a two-seat structure.

Standard ChatGPT seat
ChatGPT + Codex included, fixed monthly charge, minimum 2 seats
Codex seat
Codex only, usage-based billing, no minimum

Standard ChatGPT seat pricing is typically about 37,500 KRW/user/month, or about 30,000 KRW/user/month with annual billing. Codex seat is Codex only with usage-based billing and no fixed monthly cost; workspace credits are needed.

Business is pay-as-you-go, allowing standard or usage-based Codex seats to be assigned, and usage can be expanded with workspace credits.

07Enterprise / Edu / Gov / Health

Enterprise and Edu are contract-based. With flexible pricing, there's no fixed rate limit and usage expands based on credits. However, Enterprise/Edu without flexible pricing typically have per-seat usage limits similar to Plus for most features.

Enterprise / Edu with flexible pricing
Credits-based expansion
Enterprise / Edu without flexible pricing
Mostly similar per-seat limits as Plus
Business / Enterprise workspace
Workspace credits, admin analytics, spend controls

When using flexible pricing in Business, Edu, or Enterprise, you can purchase additional workspace credits to continue using Codex.

08Cost Structure When Using API Key

When using Codex with an API Key, ChatGPT plan included usage does not apply; instead, OpenAI Platform API pricing is applied. With an API Key, you can use Codex in CLI, SDK, and IDE extension, but cloud-based features like GitHub code review and Slack are not available. Billing is based on token usage and API pricing.

CLI
Supported
SDK / codex exec
Supported
IDE extension
Supported
Codex Cloud task
Not supported
GitHub code review
Not supported
Slack integration
Not supported
Billing
Based on OpenAI API tokens
Recommended for
CI/CD, automation, script execution

API key authentication supports local Codex workflows but limits or disables features that depend on ChatGPT workspace or cloud services. Usage is billed at standard API rates on your OpenAI Platform account.

09Codex Credit Billing Method

Starting April 2, 2026, Codex pricing changed from average per-message billing to token-based credit pricing aligned with API token usage. This change applies to Plus, Pro, Business, and new Enterprise, and from April 23, 2026, also applies to existing Enterprise, Edu, Health, Gov, and ChatGPT for Teachers.

Billing calculation has three units:

Input tokens
Prompts, code, context going into Codex
Cached input tokens
Input tokens with discount applied via prompt caching
Output tokens
Answers, code generated by Codex, including reasoning output

The official rate card shows credits per 1M input tokens, 1M cached input tokens, 1M output tokens per model. Actual credit usage varies by each task's input/cached input/output token ratio.

Calculation:

Total credits = input_tokens / 1,000,000 × input_rate + cached_input_tokens / 1,000,000 × cached_input_rate + output_tokens / 1,000,000 × output_rate

10Codex Credit Rate Card by Model

GPT-5.5
Input: 125 credits / 1M, Cached: 12.50 credits / 1M, Output: 750 credits / 1M
GPT-5.4
Input: 62.50 credits / 1M, Cached: 6.250 credits / 1M, Output: 375 credits / 1M
GPT-5.4-Mini
Input: 18.75 credits / 1M, Cached: 1.875 credits / 1M, Output: 113 credits / 1M
GPT-5.3-Codex
Input: 43.75 credits / 1M, Cached: 4.375 credits / 1M, Output: 350 credits / 1M
GPT-5.2
Input: 43.75 credits / 1M, Cached: 4.375 credits / 1M, Output: 350 credits / 1M
GPT-5.3-Codex-Spark
Research preview (rate TBD)
GPT-Image-2.0 image
Input: 200 credits / 1M, Cached: 50 credits / 1M, Output: 750 credits / 1M
GPT-Image-2.0 text
Input: 125 credits / 1M, Cached: 31.25 credits / 1M, Output: 250 credits / 1M

One GPT-5.5 Codex task typically consumes about 5-45 credits, but actual usage varies by task size and token mix.

11Plan Usage Limits per 5 Hours · Plus

The official table's unit is 5-hour rolling window. Local messages and cloud tasks share the same 5-hour window, and additional weekly limits may apply.

Plus:

GPT-5.5
Local Messages: 15–80, Cloud Tasks: Not available, Code Reviews: Not available
GPT-5.4
Local Messages: 20–100, Cloud Tasks: Not available, Code Reviews: Not available
GPT-5.4-mini
Local Messages: 60–350, Cloud Tasks: Not available, Code Reviews: Not available
GPT-5.3-Codex
Local Messages: 30–150, Cloud Tasks: 10–60, Code Reviews: 20–50

Plus limits vary within the range by model, task size, local/cloud execution, and context size.

12Plan Usage Limits per 5 Hours · Pro 5x / 20x

Pro 5x (5x Plus):

GPT-5.5
Local Messages: 80–400, Cloud Tasks: Not available, Code Reviews: Not available
GPT-5.4
Local Messages: 100–500, Cloud Tasks: Not available, Code Reviews: Not available
GPT-5.4-mini
Local Messages: 300–1750, Cloud Tasks: Not available, Code Reviews: Not available
GPT-5.3-Codex
Local Messages: 150–750, Cloud Tasks: 50–300, Code Reviews: 100–250

Pro 20x (20x Plus):

GPT-5.5
Local Messages: 300–1600, Cloud Tasks: Not available, Code Reviews: Not available
GPT-5.4
Local Messages: 400–2000, Cloud Tasks: Not available, Code Reviews: Not available
GPT-5.4-mini
Local Messages: 1200–7000, Cloud Tasks: Not available, Code Reviews: Not available
GPT-5.3-Codex
Local Messages: 600–3000, Cloud Tasks: 200–1200, Code Reviews: 400–1000

13Business Limits · Fast Mode

Business: Shows the same range as Plus. However, Business can combine standard ChatGPT seats, Codex seats, workspace credits, and spend controls, so actual cost management differs from individual Plus.

GPT-5.5
Local Messages: 15–80
GPT-5.4
Local Messages: 20–100
GPT-5.4-mini
Local Messages: 60–350
GPT-5.3-Codex
Local Messages: 30–150, Cloud Tasks: 10–60, Code Reviews: 20–50

Fast mode is not a separate model but a speed setting that runs supported models faster. Speed increases about 1.5x, while GPT-5.5 consumes 2.5x credits compared to Standard, and GPT-5.4 consumes 2x credits. With API key usage, Fast mode credits don't apply; standard API pricing applies instead.

14GPT-5.3-Codex-Spark Costs

GPT-5.3-Codex-Spark is a research preview model for Pro users. Spark is a text-only research preview model optimized for near-instant, real-time coding iteration.

Currently, Spark's credit rate is not final and is marked as research preview. Spark is Pro-user-exclusive research preview and is not available in the API at launch. Usage limits may adjust based on demand.

Status
Research preview
Target
ChatGPT Pro users
Type
Ultra-fast text-only coding iteration
API
Not supported in API at launch
Credit rate
Not final
Usage limit
Separate limit, adjustable based on demand

15Image Generation Costs · Cost Differences by Task

Image generation: Codex image generation is included in the same general usage limit as other Codex usage. Image generation can consume included limits 3-5x faster than similar non-image turns, and after limits are exceeded, it's deducted from credits. Image generation is not available on the Free plan.

ChatGPT plan usage
Consumes Codex general usage limit
After exceeding limit
Deducted from credits
Free
Image generation not available
API Key
API pricing applies
Average consumption
Can consume 3-5x faster than similar turn

Cost differences by task: Even the same "1 message" doesn't cost the same. Small scripts or routine functions may consume only part of the allowance, but large codebase, long-running tasks, or extended sessions maintaining lots of context consume much more per message.

16Factors That Increase Costs

Large repository
Increased input context
Long conversation
Maintains previous context
Large AGENTS.md
Increased instructions per turn
Many MCP servers
Increased tool definitions and context
High reasoning effort
May increase output/reasoning tokens
Fast mode
Credit multiplier applied
Image generation
May consume 3-5x versus general turn
Cloud task
Separate limit, based on GPT-5.3-Codex
Code review
Per-PR uses GPT-5.3-Codex

17Hidden Token Overhead

Codex costs aren't determined only by directly typed sentences. In reality, these items can be included in input or output tokens:

System instructions
Codex base instructions
AGENTS.md
Project instructions
File context
Read file contents
Tool output
Shell, test, grep, git results
MCP tool definitions
Connected MCP server tool descriptions
Reasoning tokens
Model internal reasoning output tokens
Diff / patch content
Change descriptions and code
Long session context
Long session maintenance cost

Ways to save usage limits: reduce AGENTS.md size, limit MCP server count, remove unnecessary context, switch to smaller models.

18Where to Check Costs

Codex web / app
Codex Settings > Usage Dashboard
Codex CLI
/status
Plus / Pro credits
Codex Settings > Usage > Credits
Business workspace
Workspace settings → Billing
Business auto reload
Workspace credit automatic reload
API Key
OpenAI Platform usage / billing dashboard

Check current limits in the Codex usage dashboard. During a CLI session, view remaining limits with /status. In Business credits, add credits from workspace billing and set automatic reload and monthly recharge limits.

19Cost Optimization Strategy · Model, MCP, Session

1. Don't fix the default model as gpt-5.5 xhigh unconditionally

gpt-5.5 + xhigh is right for important design, security review, large refactoring, but is overkill for simple repetitive work. GPT-5.5 has about 6.67x higher credit rate on input basis and about 6.64x higher on output basis compared to GPT-5.4-mini.

Architecture / security / large refactoring
gpt-5.5 high/xhigh
General feature implementation
gpt-5.5 medium or gpt-5.4 medium
Simple fixes
gpt-5.4-mini low
Parallel subagents
gpt-5.4-mini
GitHub PR review
gpt-5.3-codex

2. Keep AGENTS.md small

AGENTS.md can be injected repeatedly into each task context, so longer files increase input tokens. In large projects, it's good to manage with nesting inside the repository so only needed context is injected.

3. Turn on MCP servers only when needed

Many MCP servers increase tool definitions and context, consuming more message limits. Always on: GitHub, filesystem (frequently used MCPs). Turn on as needed: Figma, Sentry, Jira, Linear, DB-related MCPs.

20Cost Optimization Strategy · Fast Mode, Files, Team Management

4. Don't keep Fast mode on as default

Fast mode is about 1.5x faster but GPT-5.5 uses 2.5x credits and GPT-5.4 uses 2x credits. Recommendations: on for real-time pair coding, off for simple documentation, on just before deadline edits.

5. Compress long sessions with /compact

Longer conversations increase context costs. Manage with: separate by task → remove unnecessary file context → /compact → new session.

6. Don't attach many large files at once

Attaching many large files with @file increases input tokens significantly. Better approach: find related file candidates first → then present modification targets and reasons → approve → then open only those files.

Team Cost Management Checklist

In Business/Enterprise: seat types (standard vs Codex), monthly workspace credits pre-charge, auto reload settings (minimum/target balance), default model policy (gpt-5.4 default, gpt-5.5 for critical), Fast mode default off, standard MCPs only active, AGENTS.md per-app separation, Cloud tasks for long work only, PR review scope limited, analytics reviewed regularly.

21Plan Selection Guide

Occasional testing
Free / Go
Individual developer, 2-3x/week focused use
Plus (about 30,000 KRW/month)
Daily production Codex development
Pro 5x (about 150,000 KRW/month)
Parallel projects, long agent work
Pro 20x (about 300,000 KRW/month)
Team usage
Business
Security, audit, SSO, large organization
Enterprise / Edu
CI/CD automation
API Key or Enterprise access token

For individuals, Plus is the baseline starting point. If using Codex daily for extended periods, Pro 5x is right. If running multiple tasks in parallel, Pro 20x fits. For teams, separate standard ChatGPT seat and usage-based Codex seat.

Section 12 · Wrap-up

What to Remember from This Unit

Codex costs are managed by plan-included usage limits and additional billing methods. They have shifted to token-based credit pricing, and the same task costs very differently depending on context size, model choice, and session length.

Use gpt-5.5 for critical work, gpt-5.4 for general work, gpt-5.4-mini for simple repetition, while minimizing AGENTS.md and MCP, managing Fast mode and long sessions carefully to spend costs efficiently.
Next Section

Section 13. Splitting Work Modes with Profiles

13. Divide Work Modes with Profiles

01Why profiles are necessary

Codex work is never the same type.

Simple edits
Fast response, low cost
Important refactoring
Deep reasoning, safe approval
Code review
Read-only, high analysis power
CI automation
Non-interactive execution, no approval prompt
Pair coding
Adequate speed and explanation
Security review
Conservative permissions, high reasoning

If you type this out with long CLI options every time, it's inefficient.

codex -m gpt-5.5 -c model_reasoning_effort='"xhigh"' -c approval_policy='"on-request"' -c sandbox_mode='"read-only"'

With profiles, you can shorten it to this.

codex --profile deep

02The precise meaning of Codex profiles

A Codex profile is a named settings layer.

When you pass --profile profile-name, Codex first reads the default user config ~/.codex/config.toml, then overwrites it with ~/.codex/profile-name.config.toml. A profile file is not a copy of the entire default config—it's an override file that only contains parts different from defaults.

Example default config

# ~/.codex/config.toml model = "gpt-5.5" model_reasoning_effort = "medium" approval_policy = "on-request" sandbox_mode = "workspace-write"

Example profile file

# ~/.codex/deep.config.toml model_reasoning_effort = "xhigh" sandbox_mode = "read-only"

Execution result

codex --profile deep

Final applied settings:

model = "gpt-5.5" model_reasoning_effort = "xhigh" approval_policy = "on-request" sandbox_mode = "read-only"

03Profile file location and naming rules

Profile files go under CODEX_HOME.

Default CODEX_HOME:

~/.codex

Profile file format:

~/.codex/.config.toml

Examples:

~/.codex/fast.config.toml ~/.codex/careful.config.toml ~/.codex/deep.config.toml ~/.codex/review.config.toml ~/.codex/ci.config.toml ~/.codex/pair.config.toml

Profile names can use letters, numbers, hyphens, and underscores.

Good names:

fast deep-review xhigh ci pair_mode

Names to avoid (spaces and special characters):

deep review review/prod ci.prod

04Profile application priority

Profiles sit in the middle of the overall settings priority.

1. CLI flags / --config overrides
Highest
2. Project config .codex/config.toml
3. Profile file ~/.codex/profile-name.config.toml
4. User config ~/.codex/config.toml
5. System config /etc/codex/config.toml
6. Built-in defaults
Lowest

For example, even if the profile has model = "gpt-5.4-mini", the CLI value wins if specified directly.

codex --profile fast --model gpt-5.5

The final model is gpt-5.5.

05Legacy profile approach that should not be used anymore

Do not nest profiles inside ~/.codex/config.toml the old way.

Wrong legacy approach

# No longer recommended profile = "deep" [profiles.deep] model = "gpt-5.5" model_reasoning_effort = "xhigh"

Since Codex 0.134.0, --profile no longer reads [profiles.profile-name] inside config.toml. Profiles must be moved to separate files: ~/.codex/profile-name.config.toml.

Correct approach

# ~/.codex/deep.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh"
codex --profile deep

06Set up base user config first

To use profiles well, first establish stable defaults.

# ~/.codex/config.toml model = "gpt-5.5" model_reasoning_effort = "medium" plan_mode_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" model_reasoning_summary = "auto" model_verbosity = "medium" web_search = "cached" [features] shell_snapshot = true

These defaults are for "everyday work". Profile files should only contain values that differ from here.

07`fast` profile

The fast profile is for quick iteration work.

Model
gpt-5.4-mini
Reasoning
low
Permissions
workspace write
Approval
on-request
Use
Simple edits, wording changes, type errors, repetitive work
# ~/.codex/fast.config.toml model = "gpt-5.4-mini" model_reasoning_effort = "low" plan_mode_reasoning_effort = "medium" approval_policy = "on-request" sandbox_mode = "workspace-write" model_reasoning_summary = "none" model_verbosity = "low"

Execution

codex --profile fast codex -p fast

Recommended tasks

README wording edits Small function renaming Import cleanup Type error fixes Test name changes Simple CSS edits

08`careful` profile

The careful profile is for safe general development.

Model
gpt-5.5
Reasoning
high
Permissions
workspace write
Approval
on-request
Use
General feature implementation, bug fixes, test writing
# ~/.codex/careful.config.toml model = "gpt-5.5" model_reasoning_effort = "high" plan_mode_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" model_reasoning_summary = "auto" model_verbosity = "medium"

Execution

codex --profile careful

Recommended tasks

Add new API endpoint Analyze bug causes Write tests Modify multiple files Small refactoring

09`xhigh` / `deep` profile

The deep profile is the utmost caution mode. Codex 5.5 xhigh combination is clean when set to this profile.

# ~/.codex/deep.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh" plan_mode_reasoning_effort = "xhigh" approval_policy = "on-request" sandbox_mode = "workspace-write" model_reasoning_summary = "concise" model_verbosity = "medium"

Execution

codex --profile deep

You can also create a separate read-only deep profile.

# ~/.codex/deep-readonly.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh" sandbox_mode = "read-only"
codex --profile deep-readonly

Recommended tasks

Large refactoring plans Security reviews Incident root cause analysis Architecture design Migration strategy Important PR review

10`review` profile

The review profile is dedicated to code review.

Review is usually reading and judging files without modifications, so read-only is appropriate.

# ~/.codex/review.config.toml model = "gpt-5.3-codex" model_reasoning_effort = "high" plan_mode_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "read-only" model_reasoning_summary = "concise" model_verbosity = "medium"

Review directly from CLI

codex --profile review

Inside a session

/review

If you want to always lock the review model, you can put it in the base config.

# ~/.codex/config.toml review_model = "gpt-5.3-codex"

11`ci` profile

The ci profile is for non-interactive automation.

In CI, users cannot click approval buttons, so approval_policy = "never" is often used. However, this setting requires careful consideration.

# ~/.codex/ci.config.toml model = "gpt-5.4" model_reasoning_effort = "medium" plan_mode_reasoning_effort = "medium" approval_policy = "never" sandbox_mode = "workspace-write" model_reasoning_summary = "none" model_verbosity = "low"

Execution example

codex exec --profile ci "analyze the failing tests and propose a minimal fix"

More conservative CI profile

# ~/.codex/ci-readonly.config.toml model = "gpt-5.4" model_reasoning_effort = "medium" approval_policy = "never" sandbox_mode = "read-only"

Combinations to avoid in CI:

approval_policy = "never" sandbox_mode = "danger-full-access"

12`pair` profile

The pair profile is for pair coding.

The goal is to provide both explanation and code change quality without being too slow.

# ~/.codex/pair.config.toml model = "gpt-5.5" model_reasoning_effort = "medium" plan_mode_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" model_reasoning_summary = "auto" model_verbosity = "medium"

Execution

codex --profile pair

Recommended tasks

Design new feature together Explain code while reading Review plan before changes Trace test failures together Request improvements while viewing diff

13`auto` profile

The auto profile is for work that allows some autonomous execution locally.

Unlike CI which is fully non-interactive, use it when you want to reduce constant prompting.

# ~/.codex/auto.config.toml model = "gpt-5.4" model_reasoning_effort = "medium" plan_mode_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" model_reasoning_summary = "auto" model_verbosity = "medium"

The above setting is named auto but it's not fully automatic. Truly running without prompts requires approval_policy = "never", but that's only recommended in isolated environments like CI.

More aggressive auto profile

# ~/.codex/auto-never.config.toml model = "gpt-5.4" model_reasoning_effort = "medium" approval_policy = "never" sandbox_mode = "workspace-write" model_reasoning_summary = "none" model_verbosity = "low"

Check before using

git status codex --profile auto-never

14How to run profiles

Basic execution:

codex --profile fast codex --profile careful codex --profile deep codex --profile review

Short option

codex -p fast codex -p deep

Non-interactive execution

codex exec --profile ci "run tests and summarize failures"

Temporarily change model only

codex --profile careful --model gpt-5.4

One-time arbitrary setting override

codex --profile deep -c model_reasoning_effort='"high"'

15Difference between one-time override and profiles

User config
Default values you always use. ~/.codex/config.toml
Profile
Recurring work modes. ~/.codex/deep.config.toml
CLI override
Change this run only. -c model_reasoning_effort='"high"'
Project config
Rules for specific repo. .codex/config.toml

Example:

codex --profile deep -c sandbox_mode='"read-only"'

In this case, the profile is deep, but only for this run, sandbox_mode changes to read-only. By priority, CLI override wins over profile.

16Difference between permission profiles and config profiles

Codex uses the word "profile" for two different things.

Config profile
Overall Codex settings layer. codex --profile deep
Permission profile
Filesystem and network permission policy. default_permissions = "project-edit"

This section covers config profiles.

Permission profiles are a beta feature for finer control over filesystem and network access scope for local commands. Permission profiles don't compose with existing sandbox_mode.

Beginners should stick to the existing sandbox_mode and approval_policy approach through Chapter 14 (Sandbox and Approval).

17Profile template for beginners

Beginners don't need to create too many profiles. Three are enough.

Base config

# ~/.codex/config.toml model = "gpt-5.5" model_reasoning_effort = "medium" plan_mode_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" model_reasoning_summary = "auto" model_verbosity = "medium"

Quick work

# ~/.codex/fast.config.toml model = "gpt-5.4-mini" model_reasoning_effort = "low" plan_mode_reasoning_effort = "medium" model_reasoning_summary = "none" model_verbosity = "low"
codex --profile fast

Careful work

# ~/.codex/careful.config.toml model = "gpt-5.5" model_reasoning_effort = "high" plan_mode_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write"
codex --profile careful

Utmost caution work

# ~/.codex/deep.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh" plan_mode_reasoning_effort = "xhigh" approval_policy = "on-request" sandbox_mode = "workspace-write" model_reasoning_summary = "concise"
codex --profile deep

Beginner rules

Everyday work → base config Light work → fast Important work → careful High-cost failures → deep

18Profile management strategy for professionals

Professionals should split into at least five.

fast = quick iteration careful = general work deep = utmost caution review = code review ci = automation

File structure

~/.codex/config.toml ~/.codex/fast.config.toml ~/.codex/careful.config.toml ~/.codex/deep.config.toml ~/.codex/review.config.toml ~/.codex/ci.config.toml

Recommended mapping

Simple wording or type fixes
fast
General feature implementation
careful
Complex bug analysis
deep
PR review
review
GitHub Action / CI
ci
Design and work together
pair
Bulk simple automation
auto or ci

In teams, separate personal profiles from project config.

Personal model preference
~/.codex/config.toml
Personal work modes
~/.codex/*.config.toml
Repo common rules
/.codex/config.toml
Coding style
AGENTS.md
Organizational mandatory policy
/etc/codex/config.toml or managed requirements

19Profile conflict debugging

If a profile doesn't apply as expected, check in this order.

Step 1: Check file name

ls ~/.codex

Correct filename:

deep.config.toml

Incorrect filenames:

deep.toml profile-deep.config.toml deep.config

Step 2: Remove legacy approach

If this remains inside ~/.codex/config.toml, remove it:

profile = "deep" [profiles.deep] model = "gpt-5.5"

Step 3: Check CLI override

When run like this, CLI model takes priority over profile:

codex --profile fast --model gpt-5.5

Step 4: Check project config

Check if the current repo has project config:

find . -path "*/.codex/config.toml" -print

Project config takes priority over profile.

Step 5: Check project trust

If project config doesn't apply, check if it's a trusted project. Codex ignores config and project-local hooks from untrusted projects for security.

Step 6: Check keys that shouldn't be in project config

In project-local .codex/config.toml, profile, profiles, provider, notification, telemetry-related keys, etc. are ignored. Profile selection must use CLI --profile profile-name and ~/.codex/profile-name.config.toml.

Wrong project config

# /.codex/config.toml profile = "deep"

Correct execution

codex --profile deep
Section 13 · Wrap-up

Profiles are separate files that save work modes

Codex profiles are not just option collections. For each recurring work pattern, you save the optimal settings ahead of time in separate files and pull them up with a single command.

Use ~/.codex/config.toml for your everyday defaults, and separate profile files for settings that vary by task.

Beginners can start with just fast, careful, and deep. In professional work, you can add review, ci, and pair for more nuanced responses.

Next Section

Section 14. Sandbox and Approval System

14. Sandbox and Approval System

01Difference between Sandbox and Approval

Sandbox and Approval are different security mechanisms.

Sandbox
Limit what Codex can technically do
Approval
Decide whether to ask the user when Codex tries to exceed that range

Sandbox is a technical boundary, Approval is a confirmation procedure.

Example:

sandbox_mode = "workspace-write" approval_policy = "on-request"

This setting means Codex can read, modify, and run regular commands within the current workspace, and requests approval for modifications outside the workspace or network access.

02Overall Codex security model structure

Codex's local execution security consists of three layers.

Sandbox
Restrict filesystem, network, and command execution scope
Approval
Confirm before executing work outside boundaries
Rules / Permission profiles
Control specific commands, paths, and networks more finely

Codex CLI and IDE extension enforce sandbox policy via OS-level mechanisms. Defaults are: no network access, write permissions limited to the active workspace.

03Core sandbox_mode values

In config.toml, sandbox is configured with sandbox_mode.

sandbox_mode = "workspace-write"

Three supported values:

read-only
Can read files but modifications and command execution require approval
workspace-write
Can read, modify, and run regular commands within workspace
danger-full-access
Remove sandbox restrictions

04read-only mode

read-only is the most conservative mode. Codex can examine and explain files but requires approval to modify or run commands.

sandbox_mode = "read-only" approval_policy = "on-request"

Recommended situations:

Analyzing unfamiliar codebases
Understand structure without modifications
Security review
Prevent accidental file changes
PR review
Focus on reading and judging
Checking important production repos
Minimize change risk

05read-only mode · Configuration example

Execution example:

codex --sandbox read-only --ask-for-approval on-request

Profile example:

# ~/.codex/review.config.toml model = "gpt-5.5" model_reasoning_effort = "high" sandbox_mode = "read-only" approval_policy = "on-request"

06workspace-write mode

workspace-write is the most frequently used default mode for local development. Codex can read, modify, and execute routine local commands within the current workspace. Modifications outside the workspace or network access require approval requests.

sandbox_mode = "workspace-write" approval_policy = "on-request"

Recommended situations:

General feature implementation
File modifications needed
Bug fixes
Repeated test execution and fixes
Refactoring
Multiple file modifications possible
Documentation updates
File modifications within workspace

07workspace-write mode · Configuration example

Beginner basic recommendation:

# ~/.codex/config.toml sandbox_mode = "workspace-write" approval_policy = "on-request"

CLI execution:

codex --sandbox workspace-write --ask-for-approval on-request

08danger-full-access mode

danger-full-access removes sandbox restrictions. It eliminates filesystem and network boundaries, granting Codex full access. Use only when you want to give full access to Codex.

sandbox_mode = "danger-full-access"

Most dangerous combination:

sandbox_mode = "danger-full-access" approval_policy = "never"

This combination means no sandbox, no approval request, full access allowed.

Acceptable use cases:

Disposable VM
Must be able to discard the VM itself
Docker isolated environment
Host volumes and secrets must be restricted
CI temporary runner
Permissions and network must be restricted externally
Test-only sandbox machine
No sensitive files, accounts, or tokens

Should not use as default on regular local development machines.

09approval_policy core values

Approval policy determines when Codex pauses and asks the user.

approval_policy = "on-request"

Supported values:

untrusted
Commands outside trusted set require approval
on-request
Proceed within sandbox, request approval for outside boundaries
never
No approval request, best effort within given sandbox
granular
Control surface per approval type finely

10untrusted policy

untrusted is a conservative approval policy. Codex asks before running commands not in the trusted set. Only known-safe read operations run automatically; commands that change state or trigger external execution paths require approval.

sandbox_mode = "workspace-write" approval_policy = "untrusted"

Recommended situations:

Unfamiliar repos
Unknown what scripts do
Security-sensitive projects
Restrict command execution conservatively
External contributed code
Package script risks
Operations-related repos
Failure cost is high

11on-request policy

on-request is the most practical default. Codex basically works within sandbox, asking only when it needs to go outside. Default permissions are also workspace-write + on-request + user reviewer combination.

sandbox_mode = "workspace-write" approval_policy = "on-request"

Recommended situations:

General development
Balance convenience and safety
Feature implementation
Can modify files within workspace
Running tests
Can auto-run regular commands
Beginner default
Pauses for risky work and asks

12on-request policy · Basic recommendation

Recommended basic configuration:

sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user"

13never policy

never is a policy that doesn't show approval prompts. Important: never doesn't mean removing sandbox—it means removing prompts. Codex still does its best only within configured sandbox constraints.

Safe example:

sandbox_mode = "read-only" approval_policy = "never"

Meaning: Read-only possible, no approval request, no modifications or out-of-bounds work

CI example:

sandbox_mode = "workspace-write" approval_policy = "never"

Meaning: Modifications within workspace possible, no approval request, work outside workspace fails or is restricted

Dangerous example:

sandbox_mode = "danger-full-access" approval_policy = "never"

Should not use this combination on regular local machines.

14Granular approval policy

Granular approval controls whether to surface prompts or auto-reject per approval type.

approval_policy = { granular = { sandbox_approval = true, rules = true, mcp_elicitations = true, request_permissions = false, skill_approval = false } }

Controllable items:

sandbox_approval
Allow sandbox escalation approval prompt
rules
Allow approval from rules' prompt decision
mcp_elicitations
Allow MCP elicitation prompt
request_permissions
Allow request_permissions tool prompt
skill_approval
Allow skill script approval prompt

Beginners don't need granular from the start. Most cases are covered by approval_policy = "on-request".

15approvals_reviewer: user and auto_review

You can also configure who reviews approval prompts.

approvals_reviewer = "user"

Supported values:

user
User reviews directly
auto_review
Use reviewer subagent

Default:

approval_policy = "on-request" approvals_reviewer = "user"

Auto-review example:

approval_policy = "on-request" approvals_reviewer = "auto_review" sandbox_mode = "workspace-write"

Important: Auto-review doesn't change sandbox boundaries—it only changes the reviewer for approval requests.

16Network access configuration

In workspace-write mode, network access is off by default. To allow it, add this setting:

sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = true

Recommended default:

[sandbox_workspace_write] network_access = false

Situations where network should be enabled:

Dependency installation
npm install, pip install
External API testing
Call staging APIs
Package registry access
npm, PyPI, crates.io
Document fetch
Download external docs

Note: Network access for web_search and shell commands are different.

17Extend write scope with writable_roots

workspace-write only allows writing within the current workspace by default. For other directories, add writable_roots.

sandbox_mode = "workspace-write" [sandbox_workspace_write] writable_roots = [ "/Users/me/.pyenv/shims", "/Users/me/dev/shared-package" ]

Good use examples:

Modify shared package outside monorepo
Shared package path
Need local tool shim
.pyenv/shims
Save generated output
Specific output folder

Bad use example:

[sandbox_workspace_write] writable_roots = ["/"]

This essentially undermines the sandbox purpose significantly.

18Change permissions during session with /permissions

In Codex CLI, you can switch permission modes during a session with /permissions.

/permissions

Usage flow:

  1. Analyze code in read-only
  2. Review plan
  3. Switch to workspace-write with /permissions
  4. Modify files
  5. Check diff

Good pattern for beginners:

19Allow, confirm, or block specific commands with Rules

Rules determine allow, confirm, or block for specific command prefixes.

allow
Allow without prompt
prompt
Confirm before execution
forbidden
Block execution

Usage examples:

It's more appropriate to use rules for specific command prefixes (allow, prompt, forbid) than to broaden permissions.

20Permission profiles vs. existing sandbox approach

Codex also has beta permission profiles.

Existing approach:

sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = false

Permission profile approach:

default_permissions = ":workspace"

Warning: Do not use default_permissions together with sandbox_mode or [sandbox_workspace_write]. Use one or the other.

Beginner basis: Through Chapter 14, learning just sandbox_mode + approval_policy approach is enough. Permission profiles are advanced/beta permission models covered separately.

21Frequently used safe combinations ① · ②

1. Beginner basic combination

sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user"

Effect: Can work within workspace, modifications outside/network access require approval

2. Read-only review combination

sandbox_mode = "read-only" approval_policy = "on-request"

Effect: Analysis possible, modifications or command execution require approval

Recommended: Code review, security analysis, first-time repo, production code checking

22Frequently used safe combinations ③ · ④

3. Quiet read-only CI

sandbox_mode = "read-only" approval_policy = "never"

Effect: Read-only, no approval prompt, no modifications

4. Auto-modifying CI

sandbox_mode = "workspace-write" approval_policy = "never"

Effect: Can modify within workspace, no approval prompt, workspace-outside work restricted

Recommended conditions: CI runner isolated, secret exposure limited, changes reviewed via PR diff

23Frequently used safe combinations ⑤

5. Conservative professional combination

sandbox_mode = "workspace-write" approval_policy = "untrusted"

Effect: File modifications possible, untrusted commands require approval

24Dangerous combinations

Danger 1. full access + never

sandbox_mode = "danger-full-access" approval_policy = "never"

Risk: No filesystem restriction, no network restriction, no approval

Danger 2. network access always enabled

sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = true

Risk: Increased possibility of prompt injection via external docs, package scripts, API responses

25Dangerous combinations · Continued

Danger 3. writable root set too broadly

[sandbox_workspace_write] writable_roots = ["/"]

Risk: workspace-write protection meaning mostly disappears

Instead add only needed folders narrowly:

[sandbox_workspace_write] writable_roots = ["/Users/me/dev/shared-package"]

Danger 4. Full access with many host secrets in CI

sandbox_mode = "danger-full-access" approval_policy = "never"

Risk: Increased exposure possibility for CI secrets, deploy keys, cloud tokens, package tokens

In CI, default to workspace-write or read-only, and restrict network and secret access at runner level.

26Recommended configuration for beginners

Beginners should start with this configuration.

# ~/.codex/config.toml sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user" [sandbox_workspace_write] network_access = false

What each setting means:

workspace-write
Can modify files in current project
on-request
Asks for risky or out-of-scope work
user
User judges approval directly
network_access = false
Block external network for shell commands

For unfamiliar repos, use a read-only profile:

# ~/.codex/readonly.config.toml sandbox_mode = "read-only" approval_policy = "on-request" approvals_reviewer = "user"

Execution: codex --profile readonly

27Recommended profiles for professionals

For general development

# ~/.codex/dev.config.toml model = "gpt-5.5" model_reasoning_effort = "medium" sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user" [sandbox_workspace_write] network_access = false

Execution: codex --profile dev

For deep analysis

# ~/.codex/deep-readonly.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh" plan_mode_reasoning_effort = "xhigh" sandbox_mode = "read-only" approval_policy = "on-request" approvals_reviewer = "user"

Execution: codex --profile deep-readonly

28Recommended profiles for professionals · Continued

For careful modifications

# ~/.codex/deep-edit.config.toml model = "gpt-5.5" model_reasoning_effort = "xhigh" plan_mode_reasoning_effort = "xhigh" sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user" [sandbox_workspace_write] network_access = false

Execution: codex --profile deep-edit

For network-enabled work

# ~/.codex/net.config.toml model = "gpt-5.5" model_reasoning_effort = "high" sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user" [sandbox_workspace_write] network_access = true

Execution: codex --profile net

Do not use this profile as your default.

29Sandbox and approval in CI/CD

In CI/CD, humans cannot click approval buttons, so approval_policy = "never" is often used. However, maintain sandbox.

Read-only CI:

# ~/.codex/ci-readonly.config.toml sandbox_mode = "read-only" approval_policy = "never"

Auto-modifying CI:

# ~/.codex/ci-edit.config.toml sandbox_mode = "workspace-write" approval_policy = "never" [sandbox_workspace_write] network_access = false

Execution:

codex exec --profile ci-readonly "review this diff and report risks" codex exec --profile ci-edit "fix lint errors only"

CI settings to avoid:

sandbox_mode = "danger-full-access" approval_policy = "never"

Only review this combination exceptionally if the CI runner is strongly isolated and secrets and network are restricted externally.

30Troubleshooting checklist

1. Codex cannot modify files

Check: sandbox_mode = "read-only"

Fix: sandbox_mode = "workspace-write" + approval_policy = "on-request"

2. Cannot modify files outside workspace

Check: sandbox_mode = "workspace-write"

Fix: Add writable_roots in [sandbox_workspace_write]

3. npm install or pip install fails

Check: network_access = false

Fix: network_access = true (enable only when needed)

4. Approval prompt doesn't appear at all

Check: approval_policy = "never"

Fix: approval_policy = "on-request"

5. Approval prompts appear too frequently

Check: sandbox_mode = "read-only" + approval_policy = "untrusted"

Fix: sandbox_mode = "workspace-write" + approval_policy = "on-request"

6. Project settings not applying

Check: Is the project trusted state? Is .codex/config.toml in current repo? Is CLI override higher priority covering it?

7. .git or .codex doesn't modify

Recommendation: Run git commit yourself, let Codex handle diff generation and testing only

Section 14 · Wrap-up

Chapter 14 Core Summary

Sandbox defines what you can do.

Approval defines when to ask.

Remember:

read-only = for analysis / workspace-write = for general development / danger-full-access = isolated externally only / untrusted = conservative confirmation / on-request = basic recommendation / never = CI/automation only
Next Section

Section 15. How to Use AGENTS.md

15. How to Use AGENTS.md

01What is AGENTS.md

AGENTS.md is a Markdown file that tells Codex your project's work rules.

If humans have README.md, AI coding agents have AGENTS.md.

README.md
Project explanation for humans
AGENTS.md
Work instructions for AI agents

According to official Codex documentation, AGENTS.md is durable project guidance that moves with the repository and applies before Codex starts work.

02Why AGENTS.md is needed

AGENTS.md saves rules you'd repeat constantly.

Instead of saying this every time:

This project uses pnpm. Run tests with pnpm test. Update docs when changing API. Never read or modify .env files. Check lint and typecheck before PR.

You leave it once in the repository root. Official Best Practices documentation explains that good AGENTS.md should contain repo layout, execution method, build/test/lint commands, engineering convention, PR expectations, constraints, do-not rules, and verification standards.

03How Codex reads AGENTS.md

Codex creates an instruction chain on startup. Discovery order is:

Scope
Files read
Global scope
${CODEX_HOME}/AGENTS.override.md or ${CODEX_HOME}/AGENTS.md
Project scope
AGENTS.override.md, AGENTS.md, fallback files from project root to current work directory
Merge order
Merge from root toward current directory
Priority
Files closer to current directory merge later, so are stronger

Default CODEX_HOME is ~/.codex. Codex merges ~/.codex/AGENTS.md → repo/AGENTS.md → repo/apps/web/AGENTS.md in order.

04Global AGENTS.md

Global AGENTS.md applies to all projects—your personal baseline instructions.

Location: ~/.codex/AGENTS.md

Example:

# ~/.codex/AGENTS.md ## Working agreements - Respond in English. - Present a simple plan before code changes. - Always ask before deleting important files or major refactoring. - Explain why before adding new production dependencies and suggest alternatives.

Good for global file: Response language, explanation style, approval preferences, personal habits, preferred package manager

Not good for global file: Specific repo test commands, specific team coding conventions, specific service deployment procedures

05Project AGENTS.md

Project AGENTS.md sits in the repo root—shared team instructions.

Location: repo-root/AGENTS.md

Example structure:

Official documentation explains that repository-level AGENTS.md tells Codex project rules while inheriting global defaults.

06Nested AGENTS.md and the "closer is stronger" principle

Large repos or monorepos shouldn't stop at root.

Example structure:

repo/ AGENTS.md apps/ web/ AGENTS.md admin/ AGENTS.md services/ payments/ AGENTS.md

When Codex starts in services/payments, it reads in this order: ~/.codex/AGENTS.md → repo/AGENTS.md → repo/services/payments/AGENTS.md. Files closer to current directory merge later and override earlier ones.

07AGENTS.override.md

AGENTS.override.md takes priority over regular AGENTS.md in the same directory.

When both exist in same dir: Codex uses AGENTS.override.md, ignoring AGENTS.md.

Situation
Usage
Temporary experiment
Add experiment rules with AGENTS.override.md
Exception for specific subproject
Use nested override
Personal temporary full override
~/.codex/AGENTS.override.md
Suspend team rules temporarily
Override explicitly

Warning: AGENTS.override.md is powerful. If you created it temporarily, remove it after work.

08Configure fallback filename settings

If your team already uses other instruction files, you can make Codex read those too.

Configuration example:

# ~/.codex/config.toml project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] project_doc_max_bytes = 65536

With this, Codex searches each directory in this order: AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md

09project_doc_max_bytes and instruction size limits

Codex stops adding files when instruction chain total reaches project_doc_max_bytes. Default is 32 KiB.

Configuration example:

# ~/.codex/config.toml project_doc_max_bytes = 65536

But blindly increasing size isn't the answer.

Problem
Explanation
Context increases
More instructions enter each task
Cost increases
Input tokens increase
Conflicts increase
Old and new rules mix
Instruction may be ignored
Core rules buried in length

Official Best Practices also recommend keeping main file concise, and splitting planning, code review, architecture into task-specific markdown.

10Create draft with /init

In Codex CLI, you can create a starter AGENTS.md with /init.

/init

Official Best Practices explain that /init slash command scaffolds a starter AGENTS.md, and you should edit the result to match your team's actual build, test, review, and ship practices.

Recommended flow:

  1. Run Codex at repo root
  2. Execute /init
  3. Review generated AGENTS.md
  4. Edit with actual commands and rules
  5. Team review then commit

11Basic template

Most straightforward template structure:

Project overview
Purpose, key tech stack, important directories
Commands
Install, dev server, test, lint, typecheck, build
Repository layout
Main directories and their roles
Coding conventions
Code style, doc updates, dependency policy
Testing rules
Adding tests, scope, final verification
Safety rules
Env vars, credentials, deployment protection
PR expectations
Change summary, test results, risk disclosure

12Direct coding style

Keep coding style short and concrete.

Good example:

## Coding conventions - Avoid any in TypeScript; include reason as comment if needed. - React components use named export. - Don't put business logic directly in API route handlers; separate into src/domain. - Prioritize Tailwind utility for CSS; extract repeated patterns to components. - Follow style of existing files first.

Bad example: "Write good code", "Make it clean", "Keep it maintainable" is too abstract. Codex needs rules it can actually judge.

13Direct testing, build, lint commands

Codex needs exact commands for verification after work.

Good example:

## Commands - Install dependencies: pnpm install - Run unit tests: pnpm test - Run a single test file: pnpm test -- path/to/file.test.ts - Run lint: pnpm lint - Run type checks: pnpm typecheck - Build production bundle: pnpm build

Monorepo example:

- Web app dev: pnpm --filter web dev - Web app tests: pnpm --filter web test - API tests: pnpm --filter api test - All checks: pnpm turbo run lint test typecheck

14Explicitly state forbidden actions

Explicitly write what Codex should not do.

Basic do-not list:

## Do not - Do not run deployment commands. - Do not rotate, print, or modify secrets. - Do not edit .env* files. - Do not rewrite migration history. - Do not delete user data or test fixtures unless explicitly requested. - Do not introduce new production dependencies without explaining why. - Do not make broad formatting-only changes in unrelated files.

Or more strongly:

## High-risk actions Ask for explicit confirmation before: - Running database migrations - Deleting files - Changing authentication or authorization logic - Modifying payment, billing, or money movement code - Adding dependencies - Changing CI/CD configuration

AGENTS.md is behavior guidance, not a technical enforcement mechanism.

15Security, secrets, and data guidance

Always be specific about security rules.

Example:

## Security and secrets - Do not read, print, copy, or modify .env, .env.*, private keys, certificates, or credential files. - If a task requires secrets, stop and ask the user. - Never paste tokens, API keys, cookies, or credentials into logs or responses. - Treat production data as sensitive. - Do not make network calls to production services unless explicitly requested.

Data project example:

- Do not modify files in data/raw/. - Write processed data to data/processed/. - Write reports to reports/. - Do not include personally identifiable information in generated examples.

16Write PR review guidance

If your team uses Codex as a reviewer, write review criteria separately.

Simple approach:

## Review expectations When reviewing code: - Focus on correctness, security, test coverage, and maintainability. - Prefer actionable findings over style opinions. - Include file paths and concrete examples. - Mention missing tests when behavior changes. - Do not approve changes that fail typecheck or tests.

Separate-file approach: Add "Follow docs/code_review.md when reviewing pull requests" to AGENTS.md, and Codex can follow those guidelines during review.

17Split AGENTS.md in monorepos

In monorepos, keep root small and put details in subfolders.

Recommended structure:

repo/ AGENTS.md apps/ web/ AGENTS.md mobile/ AGENTS.md services/ api/ AGENTS.md payments/ AGENTS.md packages/ ui/ AGENTS.md

Root covers repository-wide rules and layout; each subfolder handles its module's specific rules. Closest file wins, so subprojects get tailored guidance.

18Use with multiple AI coding tools

AGENTS.md is not Codex-only—it's an open format for multiple AI coding tools.

If you have existing files:

Existing file
How to handle
CLAUDE.md
Move core rules to AGENTS.md
.cursorrules
Integrate project rules into AGENTS.md
.github/copilot-instructions.md
Common rules to AGENTS.md, GitHub-only rules keep separate
CONTRIBUTING.md
Keep human guidance, move agent execution rules to AGENTS.md
README.md
Keep intro and quickstart, move AI work rules to AGENTS.md

Migration: rename existing file to AGENTS.md and create symbolic link for backward compatibility.

19Difference between AGENTS.md, config.toml, Rules, and Skills

Four confusing concepts must be distinguished.

Item
Role
AGENTS.md
Project work guidance (test commands, code style, forbidden actions)
config.toml
Codex runtime settings (model, reasoning, sandbox, approval, MCP)
Rules
Command allow/confirm/block (forbid rm -rf, confirm npm install)
Skills
Repeated workflow packages (PR review skill, test-writing skill)

Distinction guide: What should I follow? → AGENTS.md | Which model/permissions? → config.toml | Which commands block? → Rules | How to package workflows? → Skills

20Good AGENTS.md example

Good AGENTS.md structure:

## Project overview TypeScript monorepo using pnpm workspaces... ## Commands - Install: pnpm install - Tests: pnpm test (or pnpm --filter web test) ## Coding conventions - Use TypeScript strict types - Keep business logic out of route handlers ## Safety rules - Do not read or modify .env* files ## PR expectations - Summarize changed files, mention tests run, list risks

Why this example is good: Commands are actually executable | Forbidden actions are clear | Test criteria exist | File structure disclosed | Action rules outnumber abstract statements

21Bad AGENTS.md example

Bad example:

## Rules - Be smart. - Write clean code. - Make it scalable. - Use best practices. - Always improve everything. - Never make mistakes.
Problem
Explanation
Too abstract
No actual judgment criteria
No verification commands
Codex doesn't know what to run
No scope limit
Can trigger unrelated refactoring
No forbidden actions
Can't stop risky work

Worse pattern: "Always refactor", "Fix everything you see", "Run any needed commands"—this causes unnecessary large changes and dependency updates.

22Maintenance approach

AGENTS.md is not write-once. Update when:

Situation
Action
Codex repeats same mistake
Add rule
Test command changes
Update Commands
New package added
Update Repository layout
PR feedback repeats
Add Review expectations
Security issue found
Strengthen Safety rules
File grows too long
Split into sub-AGENTS.md or separate docs

Real maintenance routine: Codex makes same mistake twice → Fix root cause with short rule → Add to AGENTS.md → See effect on next task → Separate to sub-docs when too long

23Troubleshooting checklist

1. Codex doesn't seem to read AGENTS.md

codex --ask-for-approval never "Summarize the current instructions."

2. Wrong guidance applies

Check: ~/.codex/AGENTS.override.md, repo/AGENTS.override.md, override in subdirs. Rename or remove as needed.

3. Subfolder guidance not applying

codex --cd services/payments "Show which instruction files are active."

4. Fallback file ignored

Check: project_doc_fallback_filenames configured, start new session.

5. Guidance gets cut off

Fix: Increase project_doc_max_bytes or shorten root, split by subfolder.

Section 15 · Wrap-up

What to remember from this section

AGENTS.md tells Codex your project's work rules.

Basic location: ~/.codex/AGENTS.md (personal) → repo/AGENTS.md (team) → repo/subdir/AGENTS.md (subdirectory)

Core template sections: Project overview, Commands, Repository layout, Coding conventions, Testing rules, Safety rules, PR expectations

Keep it short, be concrete, make it executable, manage by repeated mistakes.

Include in AGENTS.md: Project structure, execution commands, test/lint/build commands, coding conventions, forbidden actions, security rules, PR review criteria

Don't include: Overly abstract language, outdated commands, personal preferences not fitting all repos, secrets or credentials, security policies that should be technically enforced

Next Section

Section 16. Hooks

16. Hooks

01What Are Hooks?

Hooks are an extension system that automatically runs user scripts at specific points during Codex execution.

Simply put:

Official documentation describes hooks as an extension framework for injecting deterministic scripts into the Codex lifecycle. For example, you can check if an API key is attached to a prompt, log conversation contents, run validation scripts at the end of a turn, or inject additional context from specific directories.

At the moment Codex tries to do something → hook executes → can allow, block, warn, or inject additional context

If AGENTS.md is "guidelines to follow", hooks are "automatic checks that run at predetermined times".

02When Hooks Are Needed

Hooks are suitable for these situations.

Block dangerous commands
Automatically block commands like rm -rf, git push, deploy
Prevent secret leaks
Check if API keys appear in prompts or commands
Enforce team policies
Restrict use of specific files, directories, commands
Auto validation
Notify if lint/test is needed when work ends
logging / analytics
Log session start, prompt submission, tool usage
directory-specific context
Inject additional work rules in specific directories
enterprise policy
Administrators can enforce common hooks

Writing "don't do this" in AGENTS.md is guidance, but blocking it with hooks is execution control. For important policies, it's safer to use hooks, sandbox, approval, and rules together rather than relying on AGENTS.md alone.

03Hooks Are Enabled by Default

Hooks are enabled by default. To disable, set [features].hooks = false in config.toml.

Enable again:

[features] hooks = true

Organization administrators can also force hooks off in requirements.toml.

[features] hooks = false

04Hook File Locations

Codex looks for hooks next to the active config layer. The four most commonly used locations in practice are:

~/.codex/hooks.json ~/.codex/config.toml <repo>/.codex/hooks.json <repo>/.codex/config.toml
~/.codex/hooks.json
Personal global hooks
~/.codex/config.toml
Inline hooks in personal config
<repo>/.codex/hooks.json
Project-specific hooks
<repo>/.codex/config.toml
Inline hooks in project config

Project-local hooks are loaded only when the project .codex/ layer is in a trusted state.

05hooks.json Method and config.toml Inline Method

Hooks can be configured in two ways.

First: hooks.json file

{ "hooks": { "PreToolUse": [ { "matcher": "^Bash$", "hooks": [ { "type": "command", "command": "python3 .codex/hooks/pre_tool_use_policy.py", "timeout": 30, "statusMessage": "Checking Bash command" } ] } ] } }

06config.toml Inline Method

Second is the inline approach in config.toml.

[[hooks.PreToolUse]] matcher = "^Bash$" [[hooks.PreToolUse.hooks]] type = "command" command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"' timeout = 30 statusMessage = "Checking Bash command"

Recommendation:

hooks.json
When there are many hooks or the team manages hooks separately
inline [hooks]
When keeping config and hook settings in one file simply

07Hook Configuration Structure

Hook configuration has three levels.

Event → Matcher group → Hook handler

Examples:

PreToolUse
Which lifecycle event to run on
matcher
Which tool, trigger, or source to react to
hooks
List of actual handlers to run
type = "command"
Current handler type being run
command
Shell command to execute
timeout
Maximum execution time, in seconds
statusMessage
Status message to display in UI

08Matcher Pattern

matcher is a regex string that determines when a hook runs. "*", "", or omitting the matcher matches all occurrences of that event.

Commonly used matchers:

Bash ^Bash$ ^apply_patch$ Edit|Write mcp__filesystem__read_file mcp__filesystem__.* startup|resume|clear|compact manual|auto

Matcher targets by event:

PreToolUse
tool name
PermissionRequest
tool name
PostToolUse
tool name
PreCompact / PostCompact
manual or auto
SessionStart
startup, resume, clear, compact
SubagentStart / SubagentStop
subagent type

09Hook Trust Review and /hooks

Non-managed command hooks must be reviewed and trusted by the user before execution. Codex records trust based on the current hash of the hook definition, so if hook content changes, it becomes a review target again.

Managing hooks from CLI:

/hooks

You can do the following in /hooks:

Check hook source Review new or modified hooks Trust hooks Disable individual non-managed hooks

Managed hooks come from management sources like system, MDM, cloud, or requirements.toml. These hooks are policy-marked as trusted and cannot be disabled by users from the hook browser.

10Full Lifecycle Event List

Currently, the config reference examples these lifecycle hook events:

SessionStart
After session start, resume, clear, compact
UserPromptSubmit
Right before user prompt is sent to the model
PreToolUse
Right before tool execution
PermissionRequest
Right before Codex shows an approval prompt
PostToolUse
After tool execution
PreCompact
Right before conversation compact
PostCompact
Right after conversation compact
SubagentStart
When subagent starts
SubagentStop
When subagent stops
Stop
When a turn ends

11SessionStart

SessionStart runs when a session starts.

Matcher targets:

startup resume clear compact

Input includes source. If you print plain text to stdout, it becomes additional developer context. JSON output can provide additionalContext.

Use cases: Inject team rules at session start, provide additional context per work directory, insert recent work notes summary

12UserPromptSubmit

UserPromptSubmit runs right before the user prompt is passed to the model.

Input includes the prompt submitted by the user. This event currently doesn't use matchers and configured matchers are ignored. Plain text stdout becomes additional developer context, and you can also block the prompt itself with decision: "block".

Use cases: Check if API keys are in the prompt, block high-risk requests like production DB deletion, inject additional guidance context based on prompt content

13UserPromptSubmit Block Example

Block output example:

{ "decision": "block", "reason": "Prompt appears to contain a secret. Remove it before continuing." }

You can also pass block reason via exit code 2 and stderr.

14PreToolUse

PreToolUse runs right before supported tools like Bash, apply_patch, MCP tools are executed.

Input includes tool_name, tool_use_id, tool_input. For Bash and apply_patch, use tool_input.command.

Use cases: Block dangerous Bash commands, block specific file modifications, restrict MCP tool calls, inject additional context before command execution, rewrite supported tool inputs

15PreToolUse Block Output

Block output example:

{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Destructive command blocked by hook." } }

Supported tool calls can be rewritten with permissionDecision: "allow" and updatedInput.

16PermissionRequest

PermissionRequest runs right before Codex requests approval from the user.

For example, it runs when shell escalation or managed-network approval is needed. It doesn't run for commands that don't need approval. This hook can allow, deny, or pass the request to normal approval flow without deciding.

Approval output:

{ "hookSpecificOutput": { "hookEventName": "PermissionRequest", "decision": { "behavior": "allow" } } }

17PermissionRequest Denial Output

Denial output:

{ "hookSpecificOutput": { "hookEventName": "PermissionRequest", "decision": { "behavior": "deny", "message": "Blocked by repository policy." } } }

When multiple hooks return a decision, deny wins. If there's no deny and at least one allow, the approval prompt doesn't show and proceeds.

18PostToolUse

PostToolUse runs after tool execution.

It runs after Bash, apply_patch, MCP tool calls, and even when a Bash command ends with non-zero status. However, you cannot undo the side effects of an already-executed tool.

Use cases: Inspect command output, turn test failure results into model-visible feedback, detect changes to generated files, warn after forbidden file changes

Important limitation: PostToolUse cannot undo already-executed work. Use PreToolUse if blocking is your goal.

19PreCompact / PostCompact

PreCompact runs right before conversation compact. PostCompact runs right after compact. Matcher targets are manual or auto.

Use cases: Save important TODOs before compact, check summary quality after compact, update memo files in long sessions

If PreCompact hook returns continue: false, it can stop before compact. If PostCompact hook returns continue: false, it can stop after compact.

20SubagentStart / SubagentStop

SubagentStart runs when a subagent starts. SubagentStop runs when a subagent stops.

In SubagentStart, plain text stdout can become additional developer context for the subagent. SubagentStop expects JSON stdout on exit 0, and plain text output is invalid.

Use cases: Inject additional instructions per subagent, provide separate security standards to review subagent, trigger additional execution if subagent results are insufficient

21Stop

Stop runs when a turn ends.

Matcher is currently not used. Exit 0 expects JSON stdout and plain text output is invalid. decision: "block" doesn't reject the turn but auto-generates a continuation prompt for Codex to keep going.

Use cases: Force additional check if tests didn't run, enforce checklist before work ends, inspect last assistant message, force continued writing if required report format is missing

22Stop Hook Caution

Stop hooks can create infinite continuation loops. You must check input fields like stop_hook_active to limit repetition.

Official hook input includes stop_hook_active, letting you check if that turn was already continued by a Stop hook.

23Hook Input JSON Structure

All command hooks receive a single JSON object via stdin. Common fields are:

session_id
Current Codex session id
transcript_path
Session transcript path (string or null)
cwd
Session working directory
hook_event_name
Current hook event name
model
Active model slug
permission_mode
Current permission mode
turn_id
Codex turn id provided in turn-scoped hooks

24Reading Hook Input (Python)

Reading input in a Python hook:

#!/usr/bin/env python3 import json import sys payload = json.load(sys.stdin) event = payload.get("hook_event_name") cwd = payload.get("cwd") model = payload.get("model")

25Hook Output JSON Structure

Several events support common output fields.

{ "continue": true, "stopReason": "optional", "systemMessage": "optional", "suppressOutput": false }

General success: exit 0 + no stdout

Block or continuation: exit 2 + print reason to stderr, or output event-specific JSON to stdout

26Hook Output Caution

Actual support range differs per event.

PreToolUse
continue: false not currently supported
PermissionRequest
updatedInput, updatedPermissions, interrupt are future reserved
PostToolUse
Cannot undo side effects
Stop
JSON stdout required, plain text invalid
SubagentStop
JSON stdout required, plain text invalid

27Practical Example: Block Dangerous Bash Commands

Goal: Auto-block commands like rm -rf, git push, deploy, kubectl delete, terraform apply.

.codex/hooks.json:

{ "hooks": { "PreToolUse": [ { "matcher": "^Bash$", "hooks": [ { "type": "command", "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/block_dangerous_bash.py\"", "timeout": 10, "statusMessage": "Checking Bash safety policy" } ] } ] } }

28Practical Example: block_dangerous_bash.py

.codex/hooks/block_dangerous_bash.py:

#!/usr/bin/env python3 import json import re import sys payload = json.load(sys.stdin) tool_input = payload.get("tool_input") or {} command = tool_input.get("command", "") dangerous_patterns = [ r"\brm\s+-rf\b", r"\bgit\s+push\b", r"\bkubectl\s+delete\b", r"\bterraform\s+apply\b", ]

29Practical Example: Check for Secrets in Prompt

.codex/hooks.json:

{ "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/check_prompt_secret.py\"", "timeout": 10, "statusMessage": "Checking prompt for secrets" } ] } ] } }

Input includes the prompt submitted by the user. UserPromptSubmit runs right before the prompt is sent to the model.

30Practical Example: Encourage Testing at Work End

The Stop hook runs when a turn ends. You can make Codex verify again if tests are needed.

.codex/hooks.json:

{ "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_require_tests.py\"", "timeout": 10, "statusMessage": "Checking completion criteria" } ] } ] } }

31Plugin-bundled Hooks

Plugins can also include lifecycle hooks.

Default plugin hook location:

hooks/hooks.json

Or you can specify hook path in .codex-plugin/plugin.json.

These environment variables are provided to plugin hook commands:

PLUGIN_ROOT
Installed plugin root
PLUGIN_DATA
Plugin's writable data directory
CLAUDE_PLUGIN_ROOT
Compatibility plugin root
CLAUDE_PLUGIN_DATA
Compatibility plugin data

32Managed Hooks and requirements.toml

Organization administrators can enforce managed hooks in requirements.toml.

Note: Codex does not deploy scripts in managed_dir. The organization's MDM or device-management system must install and update scripts.

Managed hooks come from sources like system, MDM, cloud, or requirements.toml, are policy-trusted, and cannot be disabled by users from the hook browser.

33Hook Security Caution (1)

1. Hooks execute local commands

Hook commands are executed in the session's cwd.

Pattern to avoid:

{ "type": "command", "command": "curl https://example.com/install.sh | sh" }

34Hook Security Caution (2)

2. Project-local hooks don't run until trust review

Malicious repos can plant .codex/hooks.json, so Codex doesn't execute non-managed hooks right away and requires review/trust procedures.

Recommendation: Review full hook command in /hooks, check absolute paths and script content, look for suspicious network calls, trust after review

35Hook Security Caution (3-4)

3. Multiple matching hooks all execute

If matching hooks exist in multiple files, all run. Don't assume multiple security hooks guarantee a specific order.

4. PostToolUse is not undo

PostToolUse can inspect tool execution after the fact, but cannot revert the side effects of already-executed commands. Use PreToolUse for blocking.

36Hook Security Caution (5-7)

5. Don't rely on transcript format

Hook input's transcript_path is for convenience. Transcript format is not a stable interface for hooks and may change.

6. Don't put secrets in hook scripts

Don't hardcode API_KEY; read from environment variables with os.environ.get().

7. Use short timeouts

Default timeout is 600 seconds if omitted. Long-running hooks slow down Codex workflows. "timeout": 10 is recommended.

37Troubleshooting (1-2)

1. Hook doesn't run

Check: Is [features] hooks = false in config.toml? Or check if /hooks shows trust is needed.

2. Project hook is ignored

Cause: Project is untrusted. Project-local hooks load only when project .codex/ layer is trusted. Check project trust status in /hooks and restart the session.

38Troubleshooting (3-5)

3. Hook seems to run twice

Cause: hooks.json and config.toml inline hooks exist simultaneously, user hook and project hook match simultaneously, or plugin hook also matches. Solution: Use either hooks.json or inline [hooks] per layer.

4. Other hook runs even though PreToolUse blocked

Normal behavior. Multiple matching command hooks on the same event start concurrently, so important blocking logic should be in one hook.

39Troubleshooting (6-7)

5. Command already ran even though PostToolUse blocked

Normal behavior. PostToolUse is after-tool hook, so move command pre-execution blocking to PreToolUse.

6. Stop hook loops infinitely

Cause: Stop hook keeps returning decision: block. Solution: Use if payload.get("stop_hook_active"): sys.exit(0) to prevent infinite loops.

40Command Won't Run on Windows

Use commandWindows or TOML alias command_windows.

[[hooks.PreToolUse.hooks]] type = "command" command = "python3 .codex/hooks/check.py" command_windows = 'py -3 .codex\hooks\check.py' timeout = 10
Section 16 · Wrap-up

What to Remember from This Unit

Hooks are a system that runs command scripts at specific points in the Codex lifecycle.

Key locations: ~/.codex/hooks.json, ~/.codex/config.toml, <repo>/.codex/hooks.json, <repo>/.codex/config.toml

The most important principles are block with PreToolUse, post-execution check with PostToolUse, work-end validation with Stop.

Beginners need only learn three: UserPromptSubmit (prompt inspection), PreToolUse (pre-execution blocking), PostToolUse (post-execution inspection).

Next Section

Section 17. MCP: Model Context Protocol

17. MCP: Model Context Protocol

01What Is MCP?

MCP is a standard protocol for AI applications to connect to external tools, data sources, and workflows.

Simply put:

MCP = Codex's standard way to connect to external tools

Through MCP, Codex can:

GitHub
View and manage PRs, issues, repository info
Figma
Read design files
Sentry
Check error logs
Browser / Playwright
Control and inspect browsers
Docs MCP
Search latest developer documentation
Internal DB / API
Query internal systems or run workflows

02What MCP Does in Codex

In Codex, MCP is an extension layer that adds external context and tools beyond basic built-in tools.

Codex built-in abilities:

Read files Modify files Run shell commands Review diffs Run tests

Abilities extended by MCP:

Manipulate GitHub PRs/issues Read Figma designs Check Sentry errors Open browsers and take screenshots Search external documentation Query internal systems

03MCP Basics: Host, Client, Server

The MCP standard consists of three main components.

Host
AI application. Here, Codex
Client
Connector inside Host that connects to MCP servers
Server
External system providing tools and context

From Codex perspective:

Codex = Host Codex internal MCP connection = Client GitHub/Figma/Sentry/Context7 MCP = Server

04MCP Transport Supported by Codex

There are two main types of MCP servers Codex supports.

STDIO
Run MCP server process as local command
Streamable HTTP
Connect to MCP server at URL via HTTP

Distinction:

STDIO MCP = run server process on my computer Streamable HTTP = connect to external or local MCP server via URL

05MCP Configuration Location

MCP configuration goes in config.toml.

Default location:

~/.codex/config.toml

Per-project location:

/.codex/config.toml

Note: Project MCP settings in .codex/config.toml apply only in trusted projects.

Untrusted projects skip the project-scoped .codex/ layer.

06Add MCP Servers via CLI

You can add MCP servers via CLI.

Basic form:

codex mcp add --

With environment variables:

codex mcp add --env VAR1=VALUE1 --env VAR2=VALUE2 --

Example:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Check and help:

/mcp codex mcp --help

07Configure MCP Servers in config.toml

Fine-tuned configuration goes in config.toml.

Basic structure:

[mcp_servers.] ...

Example:

# ~/.codex/config.toml [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] enabled = true startup_timeout_sec = 20 tool_timeout_sec = 60

08STDIO MCP Server Configuration

STDIO servers are MCP servers run as local commands.

Basic example:

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

Commonly used fields in STDIO:

command
Command to run MCP server
args
Arguments to pass to command
env
Environment variables to pass directly to server
env_vars
Environment variables to allow/forward from current environment
cwd
Working directory to start server in
startup_timeout_sec
Server startup timeout
tool_timeout_sec
Tool execution timeout
enabled
Server enabled/disabled

09STDIO Environment Variable Example

Example of setting environment variables.

[mcp_servers.mytool] command = "node" args = ["server.js"] cwd = "/Users/me/dev/my-mcp-server" env_vars = ["MY_LOCAL_TOKEN"] [mcp_servers.mytool.env] NODE_ENV = "production"

env_vars accepts plain variable name or { name = "...", source = "local" | "remote" } object.

String entry uses local source by default; source = "remote" is used only in executor-backed remote stdio.

10Streamable HTTP MCP Server Configuration

Streamable HTTP servers are MCP servers accessed via URL.

Basic example:

[mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

HTTP header example:

[mcp_servers.company_docs] url = "https://mcp.company.internal/mcp" bearer_token_env_var = "COMPANY_MCP_TOKEN" [mcp_servers.company_docs.http_headers] X-Workspace = "engineering" [mcp_servers.company_docs.env_http_headers] X-User-Token = "COMPANY_USER_TOKEN"

11HTTP Field Meanings

Fields for Streamable HTTP servers:

url
MCP server URL
bearer_token_env_var
Environment variable name to read bearer token from
http_headers
Static headers written directly in config
env_http_headers
Read header values from environment variables

It's safer not to write secrets directly in http_headers, but use bearer_token_env_var or env_http_headers instead.

12Bearer Token and HTTP Header Configuration

Bearer token approach: put token in environment variable and config only references the variable name.

Set environment variable:

export FIGMA_OAUTH_TOKEN="..."

Config setting:

[mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Bad example (writing token directly):

[mcp_servers.figma.http_headers] Authorization = "Bearer actual_token_value"

Why: Even if config.toml is accidentally committed, the token value itself is safe.

13OAuth MCP Server Login

MCP servers supporting OAuth log in via CLI.

codex mcp login

OAuth callback configuration:

mcp_oauth_callback_port = 5555 mcp_oauth_callback_url = "https://devbox.example.internal/callback"

If not set, Codex uses an ephemeral port.

OAuth credential storage method:

mcp_oauth_credentials_store = "auto"

Possible values: auto, file, keyring

14OAuth Scope Configuration

You can restrict permissions by specifying OAuth scopes.

Example:

[mcp_servers.github] url = "https://example.com/mcp" scopes = ["repo:read", "issues:read"]

mcp_servers.<id>.scopes defines OAuth scopes to request during that MCP server authentication.

It's safe to add write scope only when necessary.

15MCP Tool Allowlist / Denylist

When an MCP server provides many tools, it's good to enable only needed ones.

Allowlist:

[mcp_servers.chrome_devtools] url = "http://localhost:3000/mcp" enabled_tools = ["open", "screenshot"]

Denylist:

[mcp_servers.chrome_devtools] url = "http://localhost:3000/mcp" enabled_tools = ["open", "screenshot", "evaluate"] disabled_tools = ["evaluate"]

disabled_tools applies after enabled_tools.

16Tool Allowlist Field Meanings

Tool control fields:

enabled_tools
Allowlist of tools to use from this server
disabled_tools
Denylist to disable again after allowlist applies
enabled = false
Keep config but disable server

17MCP Tool Approval Mode

You can set approval policy per MCP tool.

Server default:

[mcp_servers.chrome_devtools] url = "http://localhost:3000/mcp" default_tools_approval_mode = "prompt"

Override specific tool:

[mcp_servers.chrome_devtools.tools.open] approval_mode = "approve"

Value meanings:

auto
Codex handles based on tool nature and policy
prompt
Ask user before tool execution
approve
Approve without prompt

18Approval Mode Practical Example

To auto-approve read-only tools only:

[mcp_servers.docs] command = "npx" args = ["-y", "@upstash/context7-mcp"] default_tools_approval_mode = "prompt" [mcp_servers.docs.tools.search] approval_mode = "approve" [mcp_servers.docs.tools.read] approval_mode = "approve"

Basic principle: Keep write/delete risky tools as prompt.

19Read-Only MCP Configuration Method

Codex MCP configuration doesn't have a single universal read_only = true option applying to all servers.

To operate close to read-only, combine these four things:

Restrict OAuth scopes
Request read-only scopes only
enabled_tools
Allowlist only read tools
disabled_tools
Block write/delete/update tools
default_tools_approval_mode = "prompt"
Check risky tools each time

20Read-Only MCP Example

GitHub read-only example:

[mcp_servers.github] url = "https://example-github-mcp.company/mcp" scopes = ["repo:read", "issues:read"] enabled_tools = ["repos/list", "pull_requests/read", "issues/read"] disabled_tools = ["repos/delete", "pull_requests/merge", "issues/write"] default_tools_approval_mode = "prompt"

Key: Read-only MCP is created with server auth permission + tool allowlist + approval mode.

21MCP Server Instructions

MCP servers can return instructions field during initialization.

Codex reads this instructions as server-wide guidance and uses it with that server's tools.

Example:

This server provides read-only access to internal API documentation. Use search_docs before read_doc. Do not call write or admin tools. Rate limit: at most 5 requests per minute.

Good content for server instructions:

Tool usage order
Search first, then read
Restrictions
Don't use write tools
rate limit
Request limit per minute
Data sensitivity
Don't output customer info
Auth scope
read-only access

First 512 characters are important for Codex to decide server use, so write self-contained.

22Plugin-Provided MCP Servers

Plugins can include MCP servers too.

Example:

[plugins."sample@test".mcp_servers.sample] enabled = true default_tools_approval_mode = "prompt" enabled_tools = ["read", "search"] [plugins."sample@test".mcp_servers.sample.tools.search] approval_mode = "approve"

Distinction:

Regular MCP
[mcp_servers.<id>]
Plugin MCP
[plugins.<plugin>.mcp_servers.<server>]
Transport configuration
User sets directly vs plugin manifest defines
User management
User sets command/url directly vs enabled/tool policy only

23Run Codex Itself as MCP Server

Codex can also run itself as an MCP server for other agents or tools to use.

codex mcp-server

Use cases:

Beginners don't need this feature right away. Usually "connecting MCP servers to Codex" comes first, and "exposing Codex itself as MCP server" is advanced automation.

24How MCP Affects Token Cost

MCP servers are convenient but can increase cost and context usage.

Cost-increasing factors:

More MCP servers
Tool definitions and instructions included in context
More tools
Model must pick from more tool descriptions
Long server instructions
Context increases per session
Large tool output
Tool results enter conversation context
Multiple MCPs simultaneously
Increased context pollution risk

25Cost Optimization

To reduce costs, configure like this:

Disable unnecessary servers:

[mcp_servers.big_server] enabled = false

Allow only needed tools:

[mcp_servers.github] enabled_tools = ["pull_requests/read", "issues/read"] disabled_tools = ["pull_requests/merge", "issues/write"]

Recommendation:

26Recommended MCPs for Beginners

Recommended order for beginners:

1st priority
OpenAI Docs / Context7 — for doc search, relatively safe
2nd priority
GitHub read-only — useful for PR/issue context
3rd priority
Figma read-only — useful for frontend work
4th priority
Sentry read-only — useful for error analysis
5th priority
Browser / Playwright — powerful but needs permission management

Beginner basics:

27GitHub MCP

GitHub MCP is useful for giving Codex GitHub API context like repositories, PRs, issues.

Recommended uses:

PR analysis
Check PR description, comments, changed files
issue triage
Summarize issues, suggest label candidates
release note
Organize by merged PRs
review support
Check GitHub thread context

Risks:

PR merge
Actual changes if misexecuted
issue/comment write
Creates public record
repo setting changes
Risky if permissions are broad
token scope excess
Exposes unnecessary write permission

28GitHub Read-Only Example

GitHub MCP safe configuration example:

[mcp_servers.github] url = "https://example-github-mcp.company/mcp" scopes = ["repo:read", "issues:read"] enabled_tools = ["repos/list", "pull_requests/read", "issues/read"] default_tools_approval_mode = "prompt"

29Figma MCP

Figma MCP is useful for reading design files and reflecting them in implementation.

Recommended uses:

Design analysis
Check frames, components, spacing
UI implementation
Write React components based on Figma
Design QA
Check implementation vs design differences
asset check
Reference colors, typography, layout

Basic example:

[mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Recommended policy:

[mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN" default_tools_approval_mode = "prompt"

Figma is safe to operate read-focused.

30Sentry MCP

Sentry MCP is useful for providing production error, stack trace, issue context to Codex.

Recommended uses:

Error root cause analysis
Track code location by stack trace
regression check
Compare recent deployment with error increase
issue summary
Turn Sentry issue into development task
test candidate derivation
Suggest regression prevention tests

Note: Sentry may contain sensitive data like user info, URLs, request body, token fragments.

31Sentry MCP Configuration

Recommended configuration:

[mcp_servers.sentry] url = "https://example-sentry-mcp.company/mcp" bearer_token_env_var = "SENTRY_MCP_TOKEN" enabled_tools = ["issues/search", "issues/read", "events/read"] default_tools_approval_mode = "prompt"

32Browser / Playwright / Chrome DevTools MCP

Browser MCPs are useful for opening and inspecting web apps in real browsers.

Recommended uses:

UI test
Open page, click, screenshot
debugging
Check console errors
layout check
Explore visual regression
E2E support
Check Playwright flows

Chrome DevTools example:

[mcp_servers.chrome_devtools] url = "http://localhost:3000/mcp" enabled_tools = ["open", "screenshot"] default_tools_approval_mode = "prompt" startup_timeout_sec = 20 tool_timeout_sec = 45 [mcp_servers.chrome_devtools.tools.open] approval_mode = "approve"

Note: Browser MCPs can access login sessions, cookies, admin pages, internal dashboards, so prompt default is safer.

33OpenAI Docs / Context7 MCP

Doc search MCPs are the safest starting point for beginners.

Context7 example:

[mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] enabled = true default_tools_approval_mode = "approve"

CLI add:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Why recommended:

34MCP Security Checklist ①

1. Don't write token directly in config

Bad example:

[mcp_servers.company.http_headers] Authorization = "Bearer actual_token"

Good example:

[mcp_servers.company] bearer_token_env_var = "COMPANY_MCP_TOKEN"

2. Keep write tools as prompt by default

[mcp_servers.github] default_tools_approval_mode = "prompt"

Auto-approve read tools only:

[mcp_servers.github.tools.pull_requests_read] approval_mode = "approve"

35MCP Security Checklist ②

3. Turn off unnecessary tools

[mcp_servers.github] enabled_tools = ["pull_requests/read", "issues/read"] disabled_tools = ["pull_requests/merge", "issues/write"]

4. Don't keep many MCP servers on all the time

[mcp_servers.figma] enabled = false

5. Trust project MCPs only in trusted projects

If project .codex/config.toml contains MCP servers, verify server command or URL is safe first.

36MCP Security Checklist ③

6. Minimize OAuth scope

[mcp_servers.github] scopes = ["repo:read", "issues:read"]

Add write scope only when necessary.

7. Specify startup timeout and tool timeout

startup_timeout_sec = 20 tool_timeout_sec = 45

Defaults: startup timeout 10 sec, tool timeout 60 sec

37MCP Troubleshooting Checklist ①

1. Server not showing in /mcp

Check:

/mcp

Look for:

2. STDIO server fails to start

Check:

38MCP Troubleshooting Checklist ②

3. HTTP MCP authentication fails

Check:

echo $FIGMA_OAUTH_TOKEN

Look for:

4. OAuth callback fails

For fixed port:

mcp_oauth_callback_port = 5555

For specific redirect URI:

mcp_oauth_callback_url = "https://devbox.example.internal/callback"

39MCP Troubleshooting Checklist ③

5. Too many tools shown and Codex gets confused

Solution:

[mcp_servers.big_server] enabled_tools = ["search", "read"] disabled_tools = ["write", "delete", "admin"]

Or disable server itself:

[mcp_servers.big_server] enabled = false

6. Tool execution often hangs

Auto-approve read tools:

[mcp_servers.docs.tools.search] approval_mode = "approve" [mcp_servers.docs.tools.read] approval_mode = "approve"

Keep risky tools as prompt:

[mcp_servers.github.tools.merge] approval_mode = "prompt"

40MCP Troubleshooting Checklist ④

7. Cost increased because of MCP

Cause:

Solution:

[mcp_servers.figma] enabled = false [mcp_servers.github] enabled_tools = ["pull_requests/read", "issues/read"]

41Beginner Basic MCP Config

Simplest and safest configuration:

# ~/.codex/config.toml [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] enabled = true default_tools_approval_mode = "approve" startup_timeout_sec = 20 tool_timeout_sec = 60

Use case:

42Careful Production Config

Configuration managing multiple MCPs selectively:

# ~/.codex/config.toml [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] enabled = true default_tools_approval_mode = "approve" startup_timeout_sec = 20 tool_timeout_sec = 60 [mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN" enabled = false default_tools_approval_mode = "prompt" startup_timeout_sec = 20 tool_timeout_sec = 45 [mcp_servers.chrome_devtools] url = "http://localhost:3000/mcp" enabled = false enabled_tools = ["open", "screenshot"] default_tools_approval_mode = "prompt" startup_timeout_sec = 20 tool_timeout_sec = 45 [mcp_servers.chrome_devtools.tools.open] approval_mode = "approve"

Operation method:

43GitHub Read-Only Focused Config

Configuration centered on GitHub:

[mcp_servers.github] url = "https://example-github-mcp.company/mcp" bearer_token_env_var = "GITHUB_MCP_TOKEN" scopes = ["repo:read", "issues:read"] enabled_tools = [ "repos/list", "pull_requests/read", "issues/read" ] disabled_tools = [ "pull_requests/merge", "issues/write", "repos/delete" ] default_tools_approval_mode = "prompt" [mcp_servers.github.tools."pull_requests/read"] approval_mode = "approve" [mcp_servers.github.tools."issues/read"] approval_mode = "approve"

Goal:

Section 17 · Wrap-up

MCP: Model Context Protocol Core Summary

MCP is a standard extension system connecting Codex to external tools. You can add external context like GitHub, Figma, Sentry, and doc search when basic built-in tools aren't enough.

Supported transport:

Default config location is ~/.codex/config.toml (global) or <repo>/.codex/config.toml (project, trusted only).

Beginners should start with doc search MCP (Context7), then gradually add GitHub, Figma, Sentry, Browser as read-only, which is safe.

Most important principle:

More attached MCPs make Codex more powerful, but context cost and security risk grow too. Always enable only needed servers, narrow tools with allowlist, and keep write tools as prompt.
Next Section

Section 18. Skills System

18. Skills System

01What Are Skills?

A Skill is a task-specific knowledge package that tells Codex "handle this kind of work this way".

Skill examples suitable for repeated work:

Core is "knowledge" not "repeatable work procedure". The purpose of Skill is to capture procedures Codex should follow during actual work, not just a simple instruction manual.

02Why Skills Are Needed

If you keep copy-pasting the same prompt, convert it to a Skill.

Four reasons Skills are needed:

Work quality consistency
Codex repeatedly follows same review standard, same test standard
Prompt shortening
User just says "review this PR" and Codex can select related Skill
Team knowledge sharing
Not personal knowhow but stored in repo .agents/skills, team uses same method
Complex procedure capture
More complex than AGENTS.md, optimized for specific task execution

03Packaging Reusable Work Knowledge

Skill is especially effective in these situations.

"Test writing Skill" example includes: test framework, file naming rules, unit/integration test distinction, mock allowance scope, test execution command, failure cause check order, result report format.

04Skill Structure

Basic structure is:

my-skill/ SKILL.md scripts/ references/ assets/ agents/ openai.yaml

SKILL.md is required; scripts/, references/, assets/, agents/openai.yaml are optional. SKILL.md must contain at minimum name and description metadata.

Simplest Skill can be made with just metadata (name, description) and procedure.

05SKILL.md Required Fields

description is very important. Codex uses this to auto-select Skills.

Good description example:

Review pull requests, diffs, branches, or code changes for correctness, security, test coverage, maintainability, and risky behavior. Use when the user asks for PR review, code review, diff review, or merge readiness.

Bad description example:

Helps with code.

Bad description is too broad for Codex to decide when to use this Skill.

06Skill Invocation Methods

Codex uses Skills in two ways.

Explicit invocation

User directly calls a specific Skill.

$pr-review Review this diff for me.

Implicit invocation

User doesn't mention Skill name; Codex picks appropriate Skill based on task content.

Review risky parts of this PR.

For implicit invocation to work, description needs trigger words like "PR", "review", "diff", "code change".

07Skill MCP Dependency

Skill defines work procedure; MCP connects to external tools and systems. Together they're powerful.

Example: "Sentry incident analysis Skill" defines procedure, MCP server fetches Sentry data.

You can declare MCP tool dependencies in Skill's agents/openai.yaml.

dependencies: tools: - type: "mcp" value: "openaiDeveloperDocs" description: "OpenAI Docs MCP server"

Skills accessing external systems must verify permission, authentication, data exposure scope.

08Practical Example: PR Review Skill

PR review Skill is a representative one most teams see immediate benefit from.

Folder structure:

.agents/ skills/ pr-review/ SKILL.md references/ review-checklist.md

PR review Skill review priority:

  1. Correctness bugs
  2. Security vulnerabilities
  3. Data loss or migration risk
  4. Broken API contracts
  5. Missing or weak tests
  6. Performance regressions
  7. Maintainability problems
  8. Style issues (affects comprehension only)

09Practical Example: PR Review Skill (continued)

Required Process

  1. Inspect the diff before giving conclusions
  2. Identify the purpose of the change
  3. Check whether the implementation matches the stated purpose
  4. Look for edge cases
  5. Verify whether tests cover the changed behavior
  6. Recommend exact fixes when possible

Output format

Summary, Critical findings, Major findings, Minor findings, Test gaps, Merge recommendation (Block / Approve after fixes / Approve).

Usage example

$pr-review Review diff between current branch and main.

10Practical Example: Test Writing Skill

Test writing Skill is useful for fixing team test style.

Test writing process:

  1. Identify the behavior being tested
  2. Check existing test patterns before adding new tests
  3. Prefer the repository's existing test utilities and fixtures
  4. Add the smallest meaningful test set
  5. Include regression tests for fixed bugs
  6. Avoid over-mocking unless the codebase already uses that pattern
  7. Run the relevant test command if available
  8. Report what was tested and what remains untested

Test selection rules

Pure functions: prefer unit tests / API behavior: prefer integration tests if existing pattern exists / Bug fixes: add regression tests / UI behavior: follow existing component test pattern

11Good Skill Writing

Good Skill is not long but increases task success rate.

Good Skill characteristics:

Bad Skill patterns: scope too broad like "develop well" / include whole project rules in Skill / include AGENTS.md content in Skill / external tool access too broad / long background description only without execution / output format missing so results differ each time

12Skill Writing Approach

Approach Skill writing in this order:

  1. Pick one repeated task
  2. Gather prompts you actually use frequently
  3. Organize where Codex makes mistakes often
  4. Make task order a checklist
  5. Fix desired output format
  6. Create SKILL.md
  7. Apply to 2-3 real tasks
  8. Polish description and procedure
  9. If worth sharing with team, make it repo Skill or plugin

13Skills Management Strategy

Skills become important to manage as they grow. If too many Skills are installed, the initial Skill list is limited, so description must be short and clear.

Skill location by use:

$HOME/.agents/skills
Skill individual uses across all projects
.agents/skills
Skill shared in specific repo or team
/etc/codex/skills
Default Skill for shared machine, container, org level
plugin
Reusable package for many teams or users

14Skills Management Strategy (continued)

Management principles:

Cleanup criteria when Skills grow:

To disable specific Skill, set enabled = false in ~/.codex/config.toml.

Section 18 · Wrap-up

What to Remember from This Unit

Skills transform Codex from "tool you direct every time" to "work agent remembering and reusing team's repeated work methods".

First three Skills worth making:

1. PR Review Skill / 2. Test Writing Skill / 3. Release Note Writing Skill

Beginners don't need to make complex Skills from the start. Just move one frequently-used prompt to SKILL.md, apply it to real work, then gradually polish description, procedure, and output format.

Next Section

Section 19. Plugins

19. Plugins

01What are Plugins?

A Codex Plugin is a bundle of features that Codex can use. One Plugin can contain the following elements:

- Skills - Apps / connectors - MCP servers - Hooks - Assets - Plugin manifest

In simple terms:

Skill = Work method MCP = Connect external tools Hook = Automatic rules at specific points Plugin = Skill + MCP + Hook + app integration bundled as an installable package

Beginners can think of a Plugin as "an additional work pack you install in Codex."

02Difference Between Plugins and Skills

Skills and Plugins look similar but have different roles.

Category
Content
Core purpose
Skills: Define work procedures / Plugins: Distribution and installation
Contents
Skills: SKILL.md, references, scripts / Plugins: skills, apps, MCP servers, hooks, assets
Scope of use
Skills: Individual/project level / Plugins: Individual, team, workspace, marketplace level
Best situations
Skills: Standardize repeated prompts / Plugins: Multiple people install and use the same feature
Example
Skills: PR review Skill / Plugins: PR review Skill + GitHub MCP + hooks

In other words, Skill defines "how Codex should work," and Plugin "makes that work method easy for others to install and use."

03Plugin discovery

Plugin discovery is the process where Codex finds a list of available Plugins to install.

In the Codex app, you can explore curated plugins, plugins shared in your workspace, and plugins you created in the Plugins screen. In the CLI, you can open the plugin browser with the /plugins command after running Codex.

codex /plugins

The basic flow for finding plugins is:

  1. Open the Plugins list in the Codex app or CLI.
  2. Search for the plugin you need or explore by marketplace.
  3. Check the plugin details.
  4. Install it.
  5. If needed, complete authentication for external apps.
  6. Use the Plugin in a new thread.

04Ways to Use Plugins

There are two ways to use a Plugin.

First, just tell Codex what you want.

Summarize unread Gmail threads from today for me.

Second, specify a particular Plugin or bundled Skill.

@Gmail Summarize only the important unread emails from today.

Codex can choose the appropriate tool from installed ones even without you specifying the Plugin directly. If you want to use a specific Plugin or Skill, you can specify it with @.

05Plugin marketplace

A Plugin marketplace is a JSON catalog containing a list of installable Plugins. Codex can read not only the official curated marketplace but also repo marketplaces, legacy-compatible marketplaces, and personal marketplaces.

Representative locations are as follows:

Official Plugin Directory $REPO_ROOT/.agents/plugins/marketplace.json $REPO_ROOT/.claude-plugin/marketplace.json ~/.agents/plugins/marketplace.json

Examples of personal or team marketplaces are as follows:

{ "name": "team-codex-plugins", "interface": { "displayName": "Team Codex Plugins" }, "plugins": [ { "name": "team-pr-review", "source": { "source": "local", "path": "./plugins/team-pr-review" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Productivity" } ] }

06Add marketplace from CLI

You can also add a marketplace directly from the CLI.

codex plugin marketplace add owner/repo codex plugin marketplace add owner/repo --ref main codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins codex plugin marketplace add ./local-marketplace-root

codex plugin marketplace supports add, list, remove, and upgrade, and can take GitHub shorthand, Git URL, SSH URL, or local marketplace root as the source.

07Workspace plugin sharing

Workspace plugin sharing is the ability to share a Plugin you created with members of the same ChatGPT workspace.

The sharing flow is as follows:

  1. Open Plugins in the Codex app.
  2. Go to Created by you.
  3. Open the detail page of the Plugin you want to share.
  4. Select Share.
  5. Add workspace members or copy the share link.
  6. Invite with access permissions configured.

The person who receives the share can find the Plugin in the Shared with you area of the Plugin Directory.

It's good to set operating standards like this:

Personal experimental Plugin → Not shared Team internal repeated Plugin → Workspace sharing Standard Plugin by repo → repo marketplace Organization-wide standard Plugin → managed marketplace or organization policy Publicly shareable Plugin → Review public / curated distribution

08Plugin hooks

A Plugin can include hooks. You can place a hooks/ directory in the Plugin root and include lifecycle hooks configuration in it.

The expected structure is as follows:

my-plugin/ .codex-plugin/ plugin.json skills/ my-skill/ SKILL.md hooks/ hooks.json .mcp.json .app.json assets/

Plugin hooks are useful in the following situations:

09Plugin enable / disable

Plugin installation and activation are separate states.

To completely remove an installed Plugin, select uninstall from the Plugin browser.

To keep an installed Plugin but turn it off, you can configure it in ~/.codex/config.toml like this:

[plugins."gmail@openai-curated"] enabled = false

After configuration, restart Codex.

From a management perspective, these criteria work well:

Frequently used Plugin → enabled = true Occasionally used Plugin → Enable only when needed Security-sensitive Plugin → Disabled by default Team standard Plugin → Enable based on repo or workspace standard Experimental Plugin → Enable only in personal config

10How to Manage Plugins in Your Team

At the team level, you shouldn't just keep adding Plugins. Plugins are convenient because they can bundle Skills, MCP, apps, and hooks together, but this also increases security and maintenance responsibilities.

Team operation principles are as follows:

  1. Create it as a Skill first.
  2. Once repeated use value is confirmed, bundle it as a Plugin.
  3. If external tool access is needed, minimize MCP permissions.
  4. Only include hooks when strict policy enforcement is needed.
  5. Standardize the installation path with marketplace.json.
  6. Be clear about version, author, repository, and license information.
  7. Document what data your team accesses before installing.
  8. Remove deprecated Plugins from marketplace or change to NOT_AVAILABLE.

11Plugin manifest example

The Plugin manifest is placed in .codex-plugin/plugin.json. This manifest serves three purposes: Plugin identification, connecting bundled components, and providing metadata displayed on the installation screen.

{ "name": "team-pr-review", "version": "0.1.0", "description": "Bundle team PR review skills and review automation.", "author": { "name": "Engineering Team", "email": "[email protected]" }, "repository": "https://github.com/example/team-codex-plugins", "license": "MIT", "keywords": ["review", "quality", "pull-request"], "skills": "./skills/", "mcpServers": "./.mcp.json" }

New teams don't need to build an elaborate Plugin system from the start. The best sequence is:

  1. Step 1: Add team Skills to .agents/skills
  2. Step 2: Bundle only high-usage Skills as Plugins
  3. Step 3: Create repo marketplace.json
  4. Step 4: Have team members install from /plugins
  5. Step 5: Add MCP only to Plugins that need external tools
  6. Step 6: Share only validated Plugins via workspace sharing

12Verify if Plugin is installed

When a Plugin isn't working, check systematically. The first thing to verify is the Plugin's installation status.

From the CLI, open /plugins to check installation status.

codex /plugins

If not installed, reinstall from the Plugin Directory or marketplace.

13Check if Plugin is in disabled state

If ~/.codex/config.toml shows the following, the Plugin is off:

[plugins."plugin-name@marketplace-name"] enabled = false

To use it, change it to true or remove the entry and restart Codex.

Also verify that the marketplace is properly recognized:

codex plugin marketplace list

If using a Git-based marketplace, update to the latest:

codex plugin marketplace upgrade

14marketplace.json path and plugin.json verification

For a repo marketplace, the location is typically:

$REPO_ROOT/.agents/plugins/marketplace.json

source.path must be a relative path from the marketplace root, typically starting with ./.

The correct location for the Plugin manifest is as follows:

my-plugin/ .codex-plugin/ plugin.json

Note that .codex-plugin/ should contain only plugin.json, while skills/, hooks/, assets/, .mcp.json, and .app.json should be at the Plugin root.

15Authentication issues and MCP verification

If a Plugin includes external apps like Gmail, Slack, or Google Drive, authentication may be required. Some Plugins require authentication during installation, while others require it on first use.

If the Plugin includes .mcp.json, you should also verify that the MCP server runs normally.

Check items are:

It's safer to use the Plugin in a new thread after installation.

Section 19 · Wrap-up

What to Remember from This Unit

Plugins are installable packages for deploying Codex features at the team and organizational level.

Create work methods with Skills, bundle them as Plugins, and distribute via Marketplace. Share with your team through workspace sharing and manage enable / disable with config.toml.

Recommended first Plugins for beginners:

It's safest to start with a simple Plugin containing just one Skill, then add MCP, hooks, and app integration once you confirm it's actually used repeatedly.

Next Section

Section 20. Plan Mode and Collaboration

20. Plan Mode and Collaboration

01What is Plan Mode?

Plan Mode is a mode that makes Codex do the following work before implementation:

1. Understand the requirements 2. Examine related files and structure 3. Ask clarifying questions about ambiguities 4. Propose the scope of changes 5. Plan the execution order 6. Organize risks and verification methods 7. Move to implementation once the user approves

You can enable Plan Mode with /plan or Shift + Tab.

Basic usage:

codex /plan

02How to Run Plan Mode

You can simply enter /plan or provide the request along with it from the start.

Slash command input:

/plan Create a migration plan to change login logic to OAuth-based.

When you enter /plan and press Enter, the current conversation switches to Plan Mode. You can also provide an inline prompt at the same time. However, you cannot use /plan while work is already running.

03Difference Between Direct Execution and Plan Mode

Direct execution reads and modifies files right away.

Fix the bug where the error message doesn't show on login failure.

Plan Mode, on the other hand, designs before implementing.

/plan Review the login failure handling flow and propose a plan to improve the error message display structure.

04Direct Execution vs. Plan Mode Comparison

In practice, you can divide as "small fixes by direct execution, structural changes by Plan Mode."

Purpose
Direct: Fix right away | Plan Mode: Analyze and plan first
Suitable work
Direct: Small, clear bug fixes | Plan Mode: Refactoring, migration, design changes
Risk level
Direct: Changes fast but direction can be misaligned | Plan Mode: Slower but reviewable
User intervention
Direct: Focus on reviewing resulting diff | Plan Mode: Intervene from the planning stage
Recommended situation
Direct: Single file, single bug | Plan Mode: Multiple files, multiple steps, vague requirements

05When to use /plan

In the following situations, it's better to use /plan first rather than execute directly.

06/plan is suitable example

For example, the following requests are better suited for Plan Mode than direct execution:

/plan Create a plan to gradually migrate from REST API to GraphQL.
/plan Find points where duplicate payments could occur in the current payment flow and create an improvement plan.
/plan Create a plan to extract a shared UI component package from this monorepo.

Conversely, if the scope is small and clear, you can execute directly:

The Button component is missing the disabled style. Add it.

07Using Plan Mode in large refactoring

Bad request: Too broad, Codex doesn't know what criteria to use to change the structure.

Cleanly refactor this project structure.

Good request: Clearly conveys goals and constraints.

/plan It looks like the roles of src/api and src/services are mixed. Analyze the current structure and create a step-by-step refactoring plan to clean up the service layer while maintaining the public API. Include validation commands for each step so tests don't break.

08Items to include in a large refactoring plan

In refactoring, "what not to change" is as important as "what to change."

  1. Summary of current structure
  2. Problems
  3. What not to change
  4. What to change
  5. Execution order by step
  6. Expected diff range for each step
  7. Tests and verification commands
  8. Rollback strategy
  9. PR separation criteria

Example constraints:

Don't change public API, DB schema, or route paths, only clean up the internal structure.

09Clarifying vague requirements

The biggest advantage of Plan Mode is turning vague requirements into executable tasks.

Vague state:

The dashboard is too slow, improve it.

Create a diagnosis plan with Plan Mode:

/plan Create a dashboard performance improvement plan. First, don't guess bottlenecks. Organize which files and metrics to look at first. Ask me clarifying questions if needed.

10Plan review criteria

The essence of Plan Mode is "create a plan, then the user reviews and decides whether to execute." After receiving a plan, review it by these criteria:

Goal understanding
Did it accurately understand the goal?
Scope check
Is the scope of change not too wide?
Risk files
Is it avoiding risky files?
Test plan
Is there a test plan?
Recovery strategy
Is rollback possible?
PR separation
Do PRs need to be separated?

11Example execution request after plan review

After review, it's better to divide execution into small units rather than run everything at once:

Good. Execute only Step 1 first. Don't proceed with Step 2 and beyond yet.
The plan looks good. But exclude the DB migration and proceed only through service layer cleanup.
Execute Steps 1 and 2, report the test results, then stop.
This plan is too large. Split it into 3 PRs and reorganize.

Following this flow allows you to quickly redirect Codex if it goes off course.

12Control workflow with Enter and Tab

When Codex is running, you can control the workflow with Enter and Tab.

Enter
Interrupt current running task (immediately stop or give correction instruction)
Tab
Schedule next task (run after current task completes)

For example, if Codex is creating a plan but missed an important constraint, add it immediately with Enter:

Wait, don't change the public API at all and create the plan again.

13Schedule next task with Tab

If you want Codex to review immediately after completing the current task, you can schedule the next command with Tab:

/review

Or you can queue test execution:

!pnpm test

Intervention criteria during work:

Use Enter
When current direction is wrong or important constraints are missed
Use Tab
When you want to schedule review, testing, or follow-up questions for next

14How to write collaborative prompts

To use Plan Mode well, you should let Codex narrow down the problem together with you, rather than demanding immediate answers.

Bad prompt:

Improve the entire structure.

Good prompt:

/plan Analyze the current src/modules structure and create a refactoring plan to reduce import cycles. Keep the public API and route paths unchanged. First classify candidate files for change and stage them in order of decreasing risk. Include test commands to run at each step.

15Basic structure of collaborative prompts

The basic structure of a collaborative prompt is:

  1. Goal
  2. Current problem
  3. What not to change
  4. Priority
  5. Verification method
  6. Request for questions
  7. Desired output format

A good prompt clarifies goals and constraints and specifically instructs what to check first and what questions to ask.

16Collaborative prompt template

A template you can use in real situations:

/plan Create a plan to achieve [goal]. Current problem: - [Problem 1] - [Problem 2] Constraints: - [What cannot be changed] - [Behavior to maintain] Requests: - First identify related files. - Ask clarifying questions about unclear points. - Present a step-by-step plan before implementing.

17Real-world example 1: Authentication refactoring

Shows how to write prompts in real situations:

/plan I want to clean up the authentication logic. Goal: - Separate login, token refresh, and logout flows - Maintain existing API response format - Gradually change so tests don't break Constraints: - No DB schema changes - No public route changes - Preserve existing refresh token behavior Requests: - Classify authentication-related files first. - Separate risky changes from safe changes. - Plan to split into 2-3 PRs.

18Real-world example 2: Performance improvement

Plan Mode is particularly useful when bottlenecks are unclear, like performance improvements:

/plan I want to improve dashboard initial load speed. Goal: - Reduce first-screen render time - Remove unnecessary API calls - Minimize UX changes Constraints: - Don't change the design - Maintain API contract Requests: - First create an investigation plan to find bottleneck candidates. - Propose measurable metrics. - Don't implement right away. First tell me what data to check.

19Real-world example 3: Migration

Technical migration has large scope and risk, so Plan Mode is essential:

/plan Create a plan to migrate the test environment from Jest to Vitest. Constraints: - Don't change all tests at once - Have a parallel period so CI doesn't break - Identify jest-specific mock usage points first Output: - Impact scope - Step-by-step migration plan - Risk factors - PR separation plan - Verification commands

20Core patterns of Plan Mode

Use based on task complexity:

Small fixes
Direct execution
Ambiguous work
/plan
Large refactoring
/plan then step-by-step approval
Risky changes
/plan + test plan + rollback criteria
Long-term work
/plan then connect with /goal

21Most practical execution pattern

Splitting into multiple steps allows you to quickly redirect even if direction goes wrong.

1Create plan with /plan
2User adjusts scope
3Approve Step 1 only
4Review diff
5Run tests
6Proceed to next step

22Core message for beginners

When summarized to one sentence, the concept of Plan Mode is:

Don't fix right away. Create a plan first, and once I approve, proceed step by step from Step 1.

Just following this principle lets you use Codex much more safely and predictably.

Section 20 · Wrap-up

What to Remember from This Unit

Plan Mode is a collaboration mode for safely handling complex tasks. It's not just making Codex think longer, but allowing the user to review work direction, reduce risks, and control execution units.

By following the flow of planning → scope adjustment → step-by-step approval → verification → proceed to next step, you can quickly redirect Codex if it goes off course.

Next Section

Section 21. Goal Mode

21. Goal Mode

01What is Goal Mode?

Goal Mode is a feature that makes Codex continue multiple stages of work based on a single persistent goal. If Section 20's Plan Mode is a "mode for creating a plan first," Goal Mode is more like a "mode for pushing that plan through to completion."

The basic form is:

/goal Finish the migration and keep tests green

Korean example:

/goal Complete the authentication refactoring and proceed until all related tests pass.

02Goal Mode is suitable for which work

Goal Mode is particularly suitable for the following types of work:

Complete migration
Database, framework, library transition
Fix test failures to completion
Keep going until all tests pass
Prepare for release
Organize changes, documentation, version updates
Large-scale refactoring
Code base cleanup, structure improvement
Update documentation and tests together
Modify all related materials simultaneously when adding features
Improve evaluation scores
Keep improving until reaching the target

The key is "one work session" but rather "a long-term goal with completion conditions."

03Creating good Goals — completion conditions are essential

A good goal must have completion conditions.

Bad goal:

/goal Improve the code.

This goal is too broad—it's hard to know what to improve or when it's done.

Good goal:

/goal Resolve all type errors in the payment module and reach a state where pnpm test:payment and pnpm lint pass.

This goal clearly includes objective, scope, and completion conditions.

04Good Goal writing template

A template for writing goals clearly:

/goal Complete [work goal]. Scope: - [Target files/modules/features] Completion conditions: - [Test command] passes - [Build command] passes - [Documentation update] - [Report diff summary] Constraints: - [What cannot be touched] - [API to maintain] - [Disallowed changes]

Real-world example:

/goal Improve accessibility issues on the user settings page. Scope: - src/pages/settings - src/components/settings Completion conditions: - Keyboard navigation possible - Resolve missing aria-label issues - pnpm test settings passes - Summarize changed files and reasons at the end Constraints: - Don't change design tokens - Keep route paths the same

05Create a goal

Create a goal using the format /goal <objective> from CLI or app composer.

/goal Finish the Vitest migration and keep CI green.

Korean example:

/goal Complete the first-phase Jest to Vitest migration, proceeding until existing tests pass.

To check the current goal, enter /goal without arguments:

/goal

Goal objective allows up to 4,000 characters. For longer instructions, it's recommended to write them in a separate file and reference it in the goal:

/goal Proceed with Vitest migration based on the completion conditions in docs/goals/vitest-migration.md.

06Pause a goal

To temporarily stop Goal Mode while it's running, use /goal pause:

/goal pause

Situations where pause is needed:

Mid-way direction review
When proceeding in unexpected direction
Diff larger than expected
When change scope exceeds intent
Check test failure cause
When user verification is needed
External approval or review needed
When other people need to review first
Adjust scope
When Codex is working too broadly

Usage example:

/goal pause Summarize the files changed so far and remaining work.

07Resume and clear a goal

Resume goal — To restart a stopped goal, use /goal resume:

/goal resume

When resuming, provide any conditions you've adjusted:

/goal resume However, exclude Step 3 and proceed only through stabilizing current changes' tests.

Clear goal — To remove the current goal, use /goal clear:

/goal clear

Clear a goal when: objectives change, want to use the thread for different work, goal is set too broadly, already completed, or want to restart with a new Plan Mode flow.

To change goals, clearing the old one then setting a new one is clearest.

08Using goals in long-term work

Recommended flow for long-term work:

  1. Create a plan first with /plan.
  2. Review and narrow the scope.
  3. Clearly define completion conditions.
  4. Set a persistent goal with /goal.
  5. Check diff and test results throughout.
  6. Pause with /goal pause if needed.
  7. Adjust direction then continue with /goal resume.
  8. Clean up with /goal clear after completion.

Example: Test migration

/plan Create a Jest to Vitest migration plan. But start with packages/auth using a step-by-step plan, not changing everything at once. After reviewing the plan: /goal Migrate Jest tests in packages/auth to Vitest and proceed until pnpm test --filter auth passes. Constraint: Don't change shared test utilities yet, only allow changes within the auth package.

09Long-term work example ① — Release preparation

Release preparation goal:

/goal Complete v2.3.0 release preparation. Completion conditions: - Write initial changelog - Identify version bump candidates - Check for breaking changes - pnpm test passes - Write initial PR description Constraints: - Don't actually create tags or publish

10Long-term work example ② — Repeatedly improve difficult problems

Evaluation score-based goal:

/goal Repeatedly improve prompts and test cases until eval score is 0.85 or above. Completion conditions: - npm run eval passes - score >= 0.85 - Summarize modified prompts and failure cases

For difficult work, it's effective to provide an evaluation system or script and have Codex iteratively improve until the score is good enough.

11Goal Mode in CLI, Desktop App, and IDE

Use in CLI

Control with slash commands:

/goal <objective> /goal /goal pause /goal resume /goal clear

If you don't see /goal, enable the feature flag in config.toml:

[features] goals = true

Or:

codex features enable goals

Use in Desktop App

Enter /goal in the composer. When Goal is active, a progress row appears above the composer, and you can control pause, resume, goal editing, and clear with buttons.

12Goal Mode in IDE extension

Goal Mode is also available in IDE extensions. It's good to give goals based on open files, selections, diagnostics, and test failures.

IDE usage example:

/goal Resolve type errors in the currently open checkout flow and proceed until this module's tests pass.

Narrowing the scope is important in the IDE.

Bad goal:

/goal Fix all type errors in the entire project.

Good goal:

/goal Resolve type errors in src/features/checkout and proceed until pnpm typecheck --filter checkout passes.
Section 21 · Wrap-up

Goal Mode Essential Summary

Goal Mode is a feature that gives Codex a persistent goal to achieve and makes it continue multiple stages of work based on completion conditions.

Plan Mode
Plan what and how before executing
Goal Mode
Push the defined goal through to completion

Best usage pattern:

Establish plan with /plan → User confirms scope and completion conditions → Set persistent goal with /goal → Review midway with /goal pause → Resume with /goal resume → Clean up with /goal clear after completion

Basic sentence beginners can use right away:

/goal Complete [task] and proceed until [verification command] passes. Constraint: Maintain [what cannot change].
Next Section

Section 22. Memory System

22. Memory System

01What is Codex Memory

Codex memory is a local recall system that lets Codex remember useful information from past threads and apply it to future work. For example, if you remember the tech stack you frequently use, your preferred workflow, project conventions, common mistakes, and frequently used commands, you don't need to repeat the same explanations in every new session.

When memory is enabled, Codex remembers these recurring patterns and can reference them in similar future tasks.

For example, you don't need to say this every time:

This project uses pnpm. Run tests with pnpm test, not npm test. Don't edit DB migration files directly; add a new migration instead. API response types must be updated in zod schema first.

02The Nature of Memory: A Recall Layer, Not Rules

However, memory is more like "a helpful recall layer" rather than "a rules file". Rules that must be followed, build commands, forbidden actions, and security guidelines should go in AGENTS.md or repository documentation, not memory.

Official documentation also recommends storing essential team guidelines in AGENTS.md or checked-in documents, and treating memory as a local recall layer only.

Put what must be followed in AGENTS.md, not in memory.

03Difference Between Memory and AGENTS.md

The part that confuses beginners most is the role difference between memory and AGENTS.md.

AGENTS.md is explicit guidance you give to Codex. You manually write work rules, coding styles, test commands, forbidden actions, and review criteria that are in your project.

On the other hand, memory is a system where Codex stores information it repeatedly judged as useful from previous sessions. It's not a document where you directly declare "follow this rule without fail," but rather a way for Codex to reference what it learned from past context in future sessions.

Distinction
AGENTS.md
Memory
Nature
Explicit guidance
Automatic or semi-automatic memory
Written by
Humans
Codex from previous threads
Location
Project or Codex home
Defaults to ~/.codex/memories/
Purpose
Rules that must be followed
Recall of recurring preferences, context, work patterns
Team sharing
Possible, can be committed to repository
Defaults to local state
Security sensitivity
Manageable document
Auto-generated, requires review

04How Beginners Should Distinguish Them

As a beginner, you can remember it this way:

If it must be followed → AGENTS.md If you reference it repeatedly → memory If the whole team needs to know → AGENTS.md If it's your personal habit → memory

05When Memory is Useful ①②

Memory is most useful when it reduces repetitive context you get tired of explaining.

First: Personal Work Habits

I always want a plan first before making changes. Break large changes into small diffs. Answer in Korean but keep code comments in English.

Second: Recurring Patterns by Project

This repository uses pnpm workspace structure. Frontend is in apps/web, backend is in services/api. Tests are run per package, not from root.

06When Memory is Useful ③④

Third: Preventing Recurring Mistakes

Don't edit generated files directly in this project. Always re-run codegen after schema changes. Add timestamp prefix to migration file names.

Fourth: Maintaining Context in Long-Term Work

Memory helps when you're refactoring over multiple days or continuing a specific module's design direction. After memory is enabled, Codex can create useful context from eligible prior threads into local memory files, skip short-lived or active sessions, and memory updates may be processed in the background rather than immediately.

07Advanced Feature: Chronicle

There's also an advanced feature called Chronicle. Chronicle is an opt-in research preview feature that combines Codex's memory functionality with screen context to help it better remember recent work flows.

However, it requires Screen Recording and Accessibility permissions on macOS, can quickly consume rate limits, and increases risks of prompt injection and sensitive information exposure.

Beginners should understand regular memory first before enabling Chronicle.

08Cautions When Using Memory ① Outdated Information

Memory is convenient, but storing everything isn't always good. If wrong memories accumulate, Codex can repeatedly make incorrect assumptions.

Caution 1. Outdated Information

For example, if you used npm before but switched to pnpm now, outdated information in memory could interfere with your work. In this case, you should review or delete the memory.

09Cautions When Using Memory ② Temporary Decisions

Caution 2. Distinguish Temporary Decisions from Long-Term Rules

Skip tests only for this task. Use mocks quickly for today. Ignore type errors on this branch for now.

It's risky to keep this in memory. A "for this time only" decision can act like a long-term rule.

10Cautions When Using Memory ③ External Context

Caution 3. Work Mixed with External Context

Codex memory settings have an option to exclude threads that use external context like MCP tool calls, web search, and tool search from memory generation. The official config key is memories.disable_on_external_context, which helps prevent temporary information from external tools from becoming permanent memory.

11Recommended Configuration for Beginners

We recommend the following settings for beginners:

[features] memories = true [memories] use_memories = true generate_memories = true disable_on_external_context = true min_rate_limit_remaining_percent = 20

This configuration uses memory but excludes threads with mixed external context from memory generation, and reduces memory generation when rate limit is too low.

12Handling Memory in Team Projects

In team projects, don't use memory as a "team rules repository." Content that the whole team must follow should go in these locations:

Memory defaults to local state, so it can differ per team member. Relying only on memory for team rules reduces reproducibility.

13Safe Usage Standards in Teams

Here are the standards for safe memory use in teams:

Team Rules
AGENTS.md
Personal Preferences
memory
Commands That Must Be Reproducible
AGENTS.md
Frequently Repeated Personal Workflows
memory
Security, Deployment, Permission Rules
AGENTS.md or management docs

14Example AGENTS.md

The following content is good to put in AGENTS.md:

# AGENTS.md ## Test commands - Frontend: pnpm --filter web test - API: pnpm --filter api test - Typecheck: pnpm typecheck ## Rules - Do not edit generated files directly. - Do not commit .env files. - Ask before adding new production dependencies.

15Personal Preferences Suitable for Memory

On the other hand, these are personal preferences okay to keep in memory:

I want a change scope summary before refactoring. Explain in Korean but keep code identifiers as-is. After work, summarize focusing on diff so I can review.

In teams, use AGENTS.md as the reference document, not memory, and treat memory only as a personal productivity aid.

16Privacy and Security Considerations

Memory should never contain sensitive information. Although Codex can redact secrets during memory generation, official documentation warns to always review memory files or generated memory artifacts before sharing.

Memory files are stored by default under Codex home, with the default path being ~/.codex/memories/.

17Information That Should Never Be in Memory

Information that should absolutely never be kept in memory includes:

API keys access tokens passwords DB connection strings Customer personal information Sensitive content from internal incident reports Non-public contract information Security vulnerability exploit details

18Handling Memory Files

Memory-related files should be treated as generated state. You can open them to debug issues or before sharing a Codex home directory, but you shouldn't depend on direct editing as your normal control method.

If you want to adjust memory usage in the current thread, you can use /memories in Codex app or TUI. This command controls whether the current thread uses existing memory and whether the current thread can be used for future memory generation. However, thread-level choices don't change global memory settings.

196 Principles for Safe Real-World Use

To use safely in practice, follow these 6 principles:

  1. Never put secrets in prompts or memory.
  2. Keep team rules in AGENTS.md.
  3. Treat memory only as personal local recall aid.
  4. It's safer to disable memory generation for work with mixed external context.
  5. Check the memories folder before sharing Codex home directory.
  6. Clean up outdated or incorrect memory.
Section 22 · Wrap-up

What to Remember from This Unit

Memory is a feature that helps Codex reduce repetition for you. But rules that must be followed should go in AGENTS.md, not memory. Never keep sensitive information in memory.

Memory is personal recall aid; team rules go in AGENTS.md.
Next Section

Section 23. Session Management

23. Session Management

01What is a Session

In Codex, session is not just a chat history but rather a workspace for continuing a specific task.

Beginners can understand session like this:

session = One unit of work being conducted with Codex

For example, these should be separated into different sessions:

Session A: Fix login bug Session B: Refactor payment API Session C: Clean up README docs Session D: Analyze test failure cause

Within one session, files Codex has seen, your instructions, commands Codex executed, code Codex modified, and decisions made accumulate.

02What is a Thread

Thread is the actual conversation flow between Codex and you. A thread is a conversation between you and the Codex agent, containing multiple turns. Each turn is one user request and the agent's corresponding work.

Structurally, it looks like this:

Thread ├─ Turn 1: "Explain this project structure" │ ├─ User message │ ├─ Agent message │ └─ File reads │ ├─ Turn 2: "Fix the login bug" │ ├─ User message │ ├─ Shell command │ ├─ File edit │ └─ Agent summary │ └─ Turn 3: "Run tests too" ├─ User message ├─ Test command └─ Result summary

03Relationship Between Session, Thread, and Turn

As a beginner, you don't need to strictly distinguish between session and thread. But in practice, this way of thinking helps:

session
Saved, resumable bundle of work
thread
Continuing conversation thread within that work
turn
One request and response/work

04Resume

resume is a feature that recalls a previously saved conversation and continues it.

In CLI, use it like this:

/resume

Entering /resume opens a saved session picker, and you can recall the transcript of your chosen conversation and continue while maintaining the original history.

Usage example:

Recall the login bug fix session from yesterday with /resume. Codex maintains what files it saw and what decisions it made previously. Then request "Add tests based on the part you fixed earlier."

05When to Use Resume

When to use resume is clear:

When continuing to solve the same problem
Preserve prior progress
When prior discussion and decisions are important
Context preservation essential
When Codex already understands project structure
No need to re-analyze
When continuing to review uncommitted changes
Continue work in progress

Conversely, if you're starting something completely different, /new is better than resume.

06Fork

fork is a feature that duplicates the current conversation and branches into a new thread. /fork duplicates the current conversation into a thread with a new ID, letting you experiment with different approaches in parallel while keeping the original transcript intact.

In CLI, use it like this:

/fork

07Real-World Use Cases for Fork

Fork is most useful in these situations:

When comparing approach A vs B
Parallel experimentation
When trying a different refactoring direction
Try different approach
When wanting to experiment boldly while keeping original work
Safe experimentation
When separating review thread from implementation thread
Role separation

For example, if fixing a login bug, the original thread can do minimal fixes for just the bug, while the fork thread can try refactoring the entire auth logic.

08Good Habits When Using Fork

Recommended patterns when forking:

Small fixes
Continue in same thread
Direction split
Fork
First message in forked thread
Clarify purpose again

Example of starting a forked thread:

In this fork, don't keep the previous fix direction. Based on the auth middleware, propose a more structural solution. But don't edit files yet—just write a plan.

09Compact

compact is a feature that summarizes earlier parts of a long conversation to make context lighter.

In CLI, use it like this:

/compact

/compact replaces earlier turns with a concise summary after a long conversation, preserving important content while gaining context.

Core concept for beginners to understand:

compact is not deleting conversation; it's compressing long work records into a summary.

10Good Timing for Compact

Good times to use compact:

When conversation gets too long
Gain context
When Codex starts confusing previous content
Organize information
When too much finished exploration has accumulated
Compress unnecessary records
When only conclusions are needed from here on
Recover focus

11Safe Process Before and After Compact

It's safer to request this before compact:

Summarize key decisions, modified files, remaining work, and cautions so far. Then I'll run /compact.

After compact, it's good to re-anchor work criteria with the next message:

Continue based on the summary just compressed. Current goal is to return 401 instead of 500 on login failure. Limit modification scope to auth middleware and related tests.

12Context Window Management

Codex can hold much information within a thread, but it doesn't remember infinitely. As conversations grow longer, important information gets buried, or old exploration can interfere with current work decisions.

Context window management means three things:

Show Codex only necessary information
Improve focus
Summarize old information for organization
Preserve important content
Split threads when work unit changes
Context consistency

13Context Window Management Example

Good and bad examples:

Bad way:

"Look at the whole project and find and fix the problem."

Good way:

"Focus on src/auth and tests/auth to find why login fails with a 500. First list no more than 3 candidate causes, and show me a plan before making changes."

14Effective Routine for Long Tasks

This routine is effective for long work:

  1. Anchor work goal briefly.
  2. Mention only related files.
  3. Have Codex summarize its findings mid-conversation.
  4. Fork when direction changes.
  5. Compact when conversation gets long.
  6. Close with diff and test results.

15How to Organize When Conversation Gets Long

When conversation gets long, it's good to have Codex create a work status report first:

Recommended prompt:

Summarize the work so far in this format: 1. Original goal 2. Files reviewed 3. Cause identified 4. Changes made so far 5. Remaining work 6. Test execution and results 7. Cautions for continuing this work next time

16Next Action by Situation

After writing a work status report, choose based on situation:

Continue same direction
/compact
Try different approach
/fork
Start completely new work
/new
Return to old work
/resume

17Patterns to Avoid in Long Conversations

Patterns to avoid:

18Good Closing Prompt

Useful prompts for wrapping up a thread:

Write a final summary so I can wrap up this thread. Include: - Changed files - Key changes - Tests run - Remaining risks - Draft commit message

19Session Split Strategy by Task

Splitting sessions by work unit is safest. Recommended criteria:

Small bug fix
Maintain one session
Compare different solutions to same bug
Keep original, then /fork
Large refactoring
Start separate session from start
Documentation work
Separate from code change session
Add tests
Can proceed within related implementation session
Review work
Recommended separate thread from implementation
Long-term feature development
Split sessions by feature
Experimental change
Must use /fork or separate worktree

20Real-World Session Split Example

Real-world example of running multiple sessions in parallel:

Session 1: auth-login-bugfix - Fix login failure 500 error - Add related tests - Minimum change principle Session 2: auth-refactor-experiment - Improve auth middleware structure - Separate from original bug fix - Use fork or separate worktree Session 3: auth-docs-update - Update README and API docs - Separate from code changes

Codex app is a desktop environment focused on handling multiple threads in parallel, and for long work it's good to be clear about the boundary between local threads and cloud tasks.

21Summary of Core Slash Commands

Core slash commands for session management:

/resume
Continue old work
/fork
Duplicate current work and try different direction
/compact
Summarize long conversation to gain context
/new
Start new conversation in same CLI
/status
Check current session status
Section 23 · Wrap-up

What to Remember from This Unit

Session management is key to using Codex efficiently. It's important to distinguish between session and thread, and choose the right tool for each work type.

The most important principle is one:

Keep one thread to one coherent work unit.

Use /resume when work continues, /fork when direction branches, /compact when conversation grows long, and /new when work completely changes.

Next Section

Section 24. Non-Interactive Mode: codex exec

24. Non-Interactive Mode: codex exec

01What is codex exec

codex exec is a command to run Codex in non-interactive mode. While normal codex opens an interactive TUI inside the terminal, codex exec passes a prompt once, Codex does the work, and outputs results.

Basic form:

codex exec "Summarize this repository structure and tell me 5 risky areas"

Short form:

codex e "Review recent changes for me"

Beginners can understand it like this:

codex
Interactive mode for conversing and working
codex exec
Non-interactive automation mode for one-off tasks

codex exec is especially useful in these situations:

Test failure in CI
Analyze cause
Auto generation
Release notes, PR review
Automation
Log summary, JSON generation, code inspection

02Difference Between TUI and Exec

The biggest difference between interactive TUI and codex exec is whether a human intervenes mid-way.

Distinction
Interactive TUI codex
Execution method
Enter conversation screen
Purpose
Exploration, collaboration, review changes
Mid-way approval
Human can watch and approve
Distinction
Non-interactive codex exec
Execution method
Run command and exit
Purpose
Automation, CI, scripts
Mid-way approval
Pre-configuration is important
Output
stdout, stderr, JSONL, files
Suitable work
Repeated tasks, inspection, summary, auto review

Core standard:

Human watches mid-way and adjusts direction
codex
Run defined work automatically, results only
codex exec

03Run Work Once

The most basic usage is passing a task instruction as a string:

codex exec "Read the README and summarize this project's purpose in 5 sentences"

Code review:

codex exec "Review current git diff and point out only high-likelihood bugs"

Analyze test failure log:

npm test 2>&1 | codex exec "Summarize the test failure cause and suggest the smallest fix direction"

If stdin is piped and a prompt argument exists at the same time, the prompt is used as an instruction and piped content as additional context.

Good prompt examples:

codex exec "Review current changes. Output format: 1. Potential fatal bugs 2. Missing tests 3. Security risks 4. Fix priority Don't modify code, just review."

To actually modify files, specify sandbox permissions:

codex exec --sandbox workspace-write \ "Reproduce the failing test and fix it with the smallest code change to pass"

04Save Output to File

codex exec result goes to stdout, so it works well with redirection or tee. Progress is streamed to stderr during execution, and only the final agent message is output to stdout.

Save release notes to file:

codex exec "Write release notes based on the last 10 commits" \ > release-notes.md

Save to both screen and file:

codex exec "Review current changes" \ | tee codex-review.md

Write final message to file with -o option:

codex exec "Summarize project metadata" \ -o project-summary.md

Automation pattern:

mkdir -p reports codex exec "Review current git diff and summarize risk level" \ -o reports/codex-review.md

05Using JSON Output

Automation often needs output that machines can process more easily than human-readable text. Use --json for this:

codex exec --json "Summarize repository structure" | jq

With --json, stdout becomes JSON Lines (JSONL) stream, where you get events like thread.started, turn.started, turn.completed, turn.failed, item.*, error.

Normal output
Good for humans to read
--json
Good for scripts to process

Example:

codex exec --json "Review current changes" \ > codex-events.jsonl

JSONL format (one JSON object per line):

{"type":"thread.started","thread_id":"..."} {"type":"turn.started"} {"type":"item.completed","item":{"type":"agent_message","text":"..."}} {"type":"turn.completed","usage":{"input_tokens":1000,"output_tokens":200}}

Extract specific events only in CI:

codex exec --json "Analyze test failure cause" \ | jq -r 'select(.type=="item.completed")'

Important: --json gets the entire execution process as event stream; it's not for enforcing final result structure. To fix final result fields, use --output-schema in the next section.

06--output-schema

--output-schema makes Codex's final response conform to a specified JSON Schema. Use when downstream automation needs stable fields.

For example, if you want review results in this structure:

{ "risk_level": "low | medium | high", "summary": "string", "issues": ["string"], "recommended_action": "string" }

Create a schema file (schemas/review.schema.json):

{ "type": "object", "properties": { "risk_level": { "type": "string", "enum": ["low", "medium", "high"] }, "summary": { "type": "string" }, "issues": { "type": "array", "items": { "type": "string" } }, "recommended_action": { "type": "string" } }, "required": ["risk_level", "summary", "issues", "recommended_action"], "additionalProperties": false }

Then run:

codex exec "Review current git diff and assess risk level" \ --output-schema schemas/review.schema.json \ -o reports/review.json

Good for: PR auto-review, release notes metadata, test failure classification, security risk classification, issue triage results.

Difference between --json and --output-schema:

--json
Get entire execution process as JSONL event stream
--output-schema
Enforce final answer JSON structure
-o
Save final message to file

Use all three options together:

codex exec --json \ "Review current changes and write results conforming to schema" \ --output-schema schemas/review.schema.json \ -o reports/review.json \ > logs/codex-events.jsonl

07Use Exec in CI/CD

Main purposes for using codex exec in CI/CD:

Analyze
Test failure cause, failure log summary
Review
Review changes, detect security risks
Generate
Release notes, issue classification
Validate
Confirm doc changes aren't missed

GitHub Actions example:

name: Codex Review on: pull_request: jobs: codex-review: runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v4 - name: Run tests run: npm test 2>&1 | tee test.log - name: Analyze test result with Codex env: CODEX_API_KEY: ${{ secrets.OPENAI_API_KEY }} run: | cat test.log | codex exec \ "Analyze the test log for failure cause and suggest minimal fix direction" \ -o codex-test-analysis.md - name: Upload Codex report uses: actions/upload-artifact@v4 with: name: codex-test-analysis path: codex-test-analysis.md

Security note: Don't put OPENAI_API_KEY or CODEX_API_KEY in job-wide environment variables. Build scripts, tests, dependency lifecycle hooks, and compromised actions can read the same job environment variables.

Safer structure:

  1. Install dependencies and run tests
  2. Generate log files
  3. Inject API key only when running Codex
  4. Save results as artifacts
  5. Handle PR creation or push permissions in separate job

08Automation Script Examples

Script to run repeatedly locally (scripts/codex-review.sh):

#!/usr/bin/env bash set -euo pipefail mkdir -p reports echo "[1/3] Collecting git diff..." git diff --stat > reports/diff-stat.txt git diff > reports/diff.patch echo "[2/3] Running Codex review..." codex exec \ --sandbox read-only \ "Based on reports/diff.patch, review the changes. Don't modify code, just write the following: 1. Summary of key changes 2. Potential bugs 3. Missing tests 4. Security risks 5. Checklist before merge" \ -o reports/codex-review.md echo "[3/3] Done." echo "Report: reports/codex-review.md"

Grant execute permission and run:

chmod +x scripts/codex-review.sh ./scripts/codex-review.sh

Script for analyzing test failures:

#!/usr/bin/env bash set -euo pipefail mkdir -p reports npm test 2>&1 | tee reports/test.log || true cat reports/test.log | codex exec \ --sandbox read-only \ "Analyze this test log. Output: - Failed tests - Direct cause - Most likely code location - Minimal fix direction - Commands to check further" \ -o reports/test-analysis.md

Auto-fix script allowing file modification (needs more care):

codex exec \ --sandbox workspace-write \ "Run npm test, reproduce the failure, and fix it with minimal changes to pass. Don't do unrelated refactoring. Run npm test again after fixing."

Production requirements: verify working directory is clean, clearly limit modification scope, specify test command, human reviews diff results, CI saves only patches as artifacts.

09Sandbox and Approval Recommended Values

codex exec is used in automation, so permission settings are critical. Default sandbox is read-only, use --sandbox workspace-write to allow file changes, or --sandbox danger-full-access for broader access.

Recommended combinations:

Log summary
read-only + never
Code review
read-only + never
Generate release notes
read-only + never
Analyze test failure
read-only + never
Automate file edits
workspace-write + never
Generate patch in CI
workspace-write + never
High-risk experiment in isolated container
danger-full-access + never

Config example:

sandbox_mode = "read-only" approval_policy = "never"

Separate profile for file modification:

# ~/.codex/ci-fix.config.toml sandbox_mode = "workspace-write" approval_policy = "never" model_reasoning_effort = "medium"

Run:

codex exec --profile ci-fix \ "Reproduce failing test and fix with minimal changes to pass"

Combinations to avoid:

Section 24 · Wrap-up

Section 24 Summary

codex exec = Non-interactive mode for one-off Codex automation

Frequently used commands:

codex exec "Summarize current repository structure" codex e "Review current changes" codex exec "Write release notes" -o release-notes.md codex exec --json "Analyze repository" > codex-events.jsonl codex exec --sandbox workspace-write \ "Fix failing test with minimal changes"

Most important principles:

Next Section

Section 25. Codex Cloud and Background Tasks

25. Codex Cloud and Background Tasks

01What is Codex Cloud

Codex Cloud is a way to have Codex read, modify, and run commands in an isolated cloud environment provided by OpenAI, rather than on your local computer.

Beginners can understand it this way:

Local Codex = Codex working on my computer Codex Cloud = Codex working in a cloud container

When Codex Cloud is useful:

02Differences Between Local and Cloud Work

A Codex thread can run locally or in the cloud.

Execution Location
Local = my computer / Cloud = cloud container
Code Reference
Local = local working tree / Cloud = GitHub repo, branch, commit
Advantages
Local = use my tools and environment / Cloud = background and parallel tasks possible
Risks
Local = directly modifying my files / Cloud = reproduction may fail if environment config is wrong
Suitable Work
Local = hands-on modification / Cloud = delegated work, parallel tasks, PR work
Work where I keep watching and adjusting → Local / Work where I delegate to Codex and get results → Cloud

03Creating Cloud Tasks

A cloud task is a unit of work you delegate to Codex to perform in the cloud.

Most basic flow:

  1. Connect GitHub repository
  2. Set up Codex Cloud environment
  3. Select branch or state to work on
  4. Pass task prompt to Codex
  5. Codex works in cloud container
  6. Review results diff
  7. Create PR or apply locally

04Cloud Task Execution Command

In CLI, use codex cloud command.

Basic usage:

codex cloud exec --env ENV_ID "task description"

Example:

codex cloud exec --env ENV_ID \ "Fix login to return 401 instead of 500 on failure and add related tests"

To get multiple solutions, use --attempts. (Range: 1~4)

codex cloud exec --env ENV_ID --attempts 3 \ "Suggest and implement safer improvements to payment failure retry logic"

05Writing Good Task Prompts

A good task prompt is specific and states conditions clearly.

Goal: Fix the issue where the server returns 500 on login failure. Conditions: - Focus on auth middleware and related tests - No unrelated refactor - Run tests after fixing - Include changed files, test results, and remaining risks in result summary

06Checking Cloud Task List

You can check recent cloud tasks from the terminal.

Basic command:

codex cloud

This opens an interactive picker to browse active and finished tasks.

View recent task list:

codex cloud list

Check specific environment or JSON format:

codex cloud list --limit 10 codex cloud list --env ENV_ID codex cloud list --env ENV_ID --json

07Applying Completed Work Locally

When a cloud task is done, review the diff before merging right away.

Apply the diff locally using the codex apply command.

Basic form:

codex apply TASK_ID codex a TASK_ID # short alias

Recommended flow:

git status git stash push -m "before applying codex cloud task" codex apply TASK_ID git diff npm test

08PR Creation Flow

A major advantage of Codex Cloud is that results can be turned into PRs.

Recommended PR flow:

  1. Create cloud task
  2. Codex modifies code and runs tests
  3. Review result summary and diff
  4. Request follow-up if needed
  5. Final diff check
  6. Create PR
  7. Check CI results
  8. Merge after human review

09Essential Checks Before Creating PR

Before creating a PR, always check:

Change Scope
Does it match the task prompt
Refactoring
No unnecessary refactoring mixed in
Tests
Did tests actually run
CI Reproducibility
Can CI reproduce this change
Sensitive Info
No secrets, tokens, or personal data included

GitHub integration also allows calling via PR comment:

@codex fix the CI failures @codex fix the P1 issue

10Good Use Cases for Long-Running Work

Codex Cloud is better suited for "work where I delegate a clear goal" than "work where I need to keep watching".

Good examples:

11Parallel Work Design

Codex Cloud can work in the background and run multiple tasks in parallel.

Good parallel task example:

Task A
Enhance auth tests
Task B
Update README installation guide
Task C
Analyze CI failure logs
Task D
Fix admin page type errors

Avoid parallel work: Modifying the same file simultaneously can cause diff conflicts or directional conflicts.

12Cloud Usage Precautions

Codex Cloud is powerful, but because it "runs in the cloud," there are different precautions than local Codex.

Environment Setup
If AGENTS.md exists in repo, it's used to find project-specific lint/test commands
Secret Handling
Encrypted but only available during setup script phase (removed before agent phase)
Internet Access
Off by default (setup script can use, agent only if configured)

Key precautions:

13Handling Experimental Features

Some Codex Cloud CLI features may be marked experimental.

Stable Features
Safe to include in team standard workflows, can document and use repeatedly
Experimental Features
Test first for personal productivity, don't put directly in CI critical path

To use cloud tasks reliably, follow these principles:

14Core Commands Summary

Most frequently used Codex Cloud commands:

# Explore cloud tasks codex cloud # Create cloud task codex cloud exec --env ENV_ID "task description" # Request multiple solutions codex cloud exec --env ENV_ID --attempts 3 "task description" # Recent task list codex cloud list # Check task list as JSON codex cloud list --json # Apply completed cloud task diff locally codex apply TASK_ID codex a TASK_ID # short alias
Section 25 · Wrap-up

Core Principle of Section 25

Work you adjust directly → local thread. / Work you delegate and run in parallel → cloud task. / Always review cloud results through diff, tests, CI, and PR review before applying.

Codex Cloud is a powerful tool for speeding up development. But understanding cloud environment characteristics, writing specific task prompts, and maintaining a habit of always reviewing results are important.

Next Section

Section 26. Codex Desktop App

26. Codex Desktop App

01Role of Desktop App

Codex Desktop App is a desktop work hub for managing Codex work in one place. It's a focused desktop experience for handling multiple Codex threads in parallel, providing built-in worktree support, automations, and Git functionality.

Beginners can understand it this way:

CLI
Terminal-centered work
IDE Extension
Pair programming in code editor
Cloud
Background work delegated to cloud
Desktop App
Command center managing multiple Codex tasks on one screen

Desktop App is especially useful when:

02multi-tasking

The core advantage of Desktop App is managing multiple tasks simultaneously. You can run tasks from multiple projects in one Codex app window and switch between codebases by adding each as a project.

For example, you can divide it like this:

Project A: trading-dashboard - Thread 1: Fix chart rendering bug - Thread 2: Analyze test failures - Thread 3: Update README Project B: api-server - Thread 1: Fix auth middleware - Thread 2: Review rate limit logic

Good usage patterns:

03git worktree isolation

Worktree is a feature that lets Codex work independently in a separate checkout without touching your current work. It allows you to run multiple independent tasks in the same project in parallel without interfering with each other.

Beginners can understand it this way:

Local
Actual project folder you have open now
Worktree
Separate working copy of same repo

Example: You're fixing the payment screen locally, and want Codex to strengthen login tests—worktree is great for that.

Recommended criteria:

Quick hands-on edits
Local
Experimental refactoring
Worktree
Parallel work in same repo
Worktree
Long-running independent work
Cloud or Worktree
GUI/browser work needing local environment
Local or Worktree

04inline diff review

Desktop App's review pane is where you visually verify Codex's changes and accept only what you need. It's where you understand what Codex changed, give targeted feedback, and decide what to keep.

Things you can do in review pane:

Especially important is inline comments. Specific feedback on diff lines helps Codex understand your intent more precisely than general instructions.

05inline diff review · practical workflow

Good review prompt example:

Reflect only my inline comments. Don't do unrelated refactoring, and run tests after fixing.

Practical workflow:

1Codex Modifies Code
2Open Review Pane
3Write Inline Comments on Lines You Dislike
4Request Minimal Change Scope
5Stage Only Required Hunks

06integrated terminal

Each thread in Desktop App has a built-in terminal scoped to the current project or worktree. It verifies changes, runs scripts, performs git work, and Codex can read current terminal output and reference failed builds or running dev servers.

Typical commands you run:

git status npm test npm run lint npm run dev git diff

The advantage of this approach is creating a "modify → run → check failure → remodify" loop on the same screen without opening CLI separately.

07conversation forking

You can also use conversation forking in Desktop App. Fork when you need to:

Example: Original thread solves login bug with minimal edits, fork thread refactors auth middleware structure.

First request after fork should be clear:

In this fork, discard the minimal edit approach, and explore simplifying auth middleware structure itself. Write only the plan first, don't modify files.

08floating pop-out windows

Floating pop-out window brings the current thread to a separate small window you can stick near your work. Useful when doing quick iteration near browser, editor, or design preview.

Frontend work layout example:

Left: Code editor Right: Browser preview Top small window: Codex pop-out thread

Recommended prompt style:

I'm looking at this component's mobile layout. I'll give you feedback while checking in the browser, so limit changes to ButtonGroup.tsx and related CSS.

09automations

Desktop App's automations schedule recurring tasks to run in background. You can automate recurring work in background, add findings to inbox, or auto-archive if nothing to report.

Usage examples:

Running automation in worktree is safer because it won't conflict with your unfinished local work.

10automations · good prompt

Good automation prompt example:

Every Monday morning, summarize this project's recent changes. Output: 1. Major changed files 2. Parts with test failure risk 3. Parts needing documentation updates 4. Work needing follow-up Don't modify code, just write the report.

11Appshots · in-app browser · Computer Use

Appshots

Appshots is a feature on macOS that sends the currently foremost app window to Codex thread. Note that Appshots contain screen info, so it's safer not to capture windows showing account info, tokens, customer data, or personal info.

in-app browser

Desktop App has an in-app browser where you can preview web apps and visually comment. Use it to review local dev servers, file-backed previews, or public pages without logging in, while viewing together in thread. Enable browser use lets Codex directly click, input, inspect, and screenshot within the in-app browser.

Computer Use

Computer Use lets Codex see, click, and type in macOS or Windows apps. Useful for desktop app testing, browser or simulator flow verification, and GUI-only bug reproduction.

12When Desktop App is Better Than CLI

CLI is fast and light. But Desktop App excels at managing multiple tasks visually, reviewing diffs, and bundling browser, terminal, Git, and automation on one screen.

Parallel manage multiple threads
CLI is inconvenient, Desktop App is good
Worktree-based parallel work
CLI possible but manual management, Desktop App is good
View diff with line comment
CLI limited, Desktop App is good
stage/revert/commit/push
CLI terminal command focused, Desktop App in-app Git features
frontend visual review
CLI needs separate browser, Desktop App has in-app browser comments
Schedule recurring work
CLI needs separate script, Desktop App has automations
Control GUI apps
CLI limited, Desktop App has Computer Use

Typical Desktop App flow: Add project → Create thread per task → Start risky work with worktree → Write plan → Implement → Test in terminal → Review diff in review pane → Fix with inline comments → Stage only needed changes → Commit/push or create PR

Section 26 · Wrap-up

What to Remember from This Unit

Codex Desktop App = local work hub managing Codex work in parallel

Most important principles:

Quick hands-on edits → Local. Work needing separation from yours → Worktree. Long-running independent work → Cloud. Always review diff in review pane before applying results.
Next Section

Section 27. IDE Extension

27. Development Environment Integration: IDE Extension, Chrome, CI/CD, SDK

01Purpose of This Section

Codex is not just a CLI tool. You can extend the same Codex work to these environments:

IDE Extension → Connected to code you see Chrome → Connected to logged-in websites GitHub Action → Connected to CI/CD SDK → Connected to your custom automation system

So section 27 is understood this way:

How to connect Codex to developers' actual work environments

02IDE Extension Concept

IDE Extension is how you connect Codex inside your code editor.

In CLI, Codex works based on project folder. But in IDE, these naturally become context:

Currently open files Selected code Active editor Project folder Current working branch Diagnostics info in IDE

Supported flow breakdown:

VS Code
Recommended base IDE
Cursor
Use Codex in VS Code-based IDE
Windsurf
Use Codex in VS Code-based IDE

03Using in VS Code, Cursor, Windsurf

Installation flow is similar across all three IDEs.

1. Install Codex Extension in IDE 2. Open Codex sidebar 3. Log in with ChatGPT account or API Key 4. Open project folder 5. Request work based on current file or whole repo

On first use, it's better to make Codex understand project before delegating file modifications.

Explain this project's structure. Don't modify files first, just summarize main folders and execution flow.

04Current File-Focused Requests

When requesting based on current file, write it this way:

Based on the currently open file, review the error handling flow. Show root causes and fix plan before modifying.

Even if Cursor or Windsurf have built-in AI, it's better to use Codex for heavier agent work.

Light single-line edits
IDE's built-in AI
Multi-file edits
Codex
Work including test runs
Codex
Cloud delegation
Codex
PR review and refactoring
Codex

05agent mode

agent mode is when Codex doesn't just answer but directly reads, modifies files, and runs commands.

Good use cases:

Find bug root causes Edit multiple files together Add tests Perform refactoring Analyze build failures

06agent mode request examples

Good request example:

Find the issue where login returns 500 on failure. Limit changes to auth files and tests. Show plan first, fix after approval.

Bad request example:

Review whole project and fix it.

In agent mode, always specify these three things:

Goal
What to solve
Scope
How much to change
Verification
How to verify results

07agent mode example

Clear request example:

Goal: Fix signup failure showing empty error message Scope: src/auth, src/components/signup, tests/auth Verification: npm test -- auth

08inline edits

inline edits is requesting Codex to modify a specific code block or your current selection.

Inline edit is better than agent mode for small changes:

Function name change Simplify conditionals Fix type errors Clean up comments Add small validation

Example:

Keep function behavior, just reduce duplicate conditionals. Don't change function signature.

09inline edits principle

Key principle in inline edit: specify "don't expand work beyond selection".

Edit only within selection. Don't touch other files.

10Sharing CLI and IDE sessions

Better to view Codex CLI, Desktop App, IDE Extension, and Cloud not as completely separate, but as multiple surfaces of same workflow.

Quick questions
CLI
Current file-focused edits
IDE
Parallel manage multiple tasks
Desktop App
Delegate long-running work
Cloud
Automation and CI
codex exec or GitHub Action
Connect custom system
SDK

11IDE Environment Transition Flow

For example, you can move like this:

Find bug in IDE → Request root cause analysis → Delegate to Cloud if work grows → Apply result diff in IDE → Run tests in local terminal → Automate recurring work in CI

12Active File-Focused Workflow

The biggest advantage of IDE Extension is you can delegate work to Codex based on "the file I'm viewing now".

Good pattern:

1. Open file with issue. 2. Select related code. 3. Request explanation from Codex based on current file. 4. Get plan before fixing. 5. Get small diff to fix. 6. Run tests.

13Active File Example

Example for currently open file:

Find why useEffect runs multiple times unnecessarily in this open file. Don't edit yet, just tell me root cause candidates and fix direction.

Fix request:

Fix only the 2nd cause you explained. Don't change component structure, just minimal dependency array and state update flow changes.

14Using in compile-test loop

Best way to use Codex in IDE is the modify → compile → test → pass failure log → remodify loop.

1. Request modification from Codex 2. Run test in IDE terminal 3. Check failure log 4. Pass failure log to Codex 5. Request minimal fix 6. Test again

Prompt example:

Fix based on the TypeScript error in terminal. Don't bypass type with any, match existing type structure.

15Analyzing Test Failures

Test failure analysis example:

Review this test failure log, organize 3 or fewer root causes. Then fix most likely cause with minimal changes.

This way is especially good for beginners because instead of having Codex make big code changes once, you create small validation loops.

16Codex for Chrome

Codex for Chrome lets Codex use websites in Chrome browser.

Beginners can understand it this way:

IDE Extension
Use Codex inside code editor
Chrome Extension
Use Codex from work screen in browser

Good tasks to use:

Check settings in admin console Read data on dashboard Edit content in CMS Perform recurring work in internal tools Check logged-in web app state

17Separating Browser Work and Local Repo Work

Chrome Extension is for website work, IDE Extension is for code work.

Edit React component
IDE Extension
Change settings in logged-in admin page
Chrome Extension
Edit CMS post
Chrome Extension
Edit API code
IDE Extension
Check dashboard then modify code
Chrome + IDE combination
Reproduce bug in browser then add test
Chrome + IDE combination

18Browser Work Flow

Example flow:

1. Reproduce dashboard bug in Chrome 2. Describe screen state to Codex or request action 3. Check root cause candidates 4. Modify related code in IDE 5. Check screen in Chrome again

Be aware that browsers contain sensitive info:

Customer data Admin permissions Payment info Internal metrics Personal info Session cookies

19Chrome Security

So it's better to give Chrome Extension minimal permissions per site and disallow unnecessary sites.

20GitHub Action and CI/CD

GitHub Action is how you connect Codex to CI/CD pipeline. openai/codex-action@v1 runs Codex in GitHub Actions workflow and can apply patches or post reviews.

Typical use cases:

PR auto-review Analyze test failures Issue triage Generate release notes draft Summarize security risks Check doc update gaps

21CI/CD Basic Flow

Simple flow:

1. Create PR 2. Run GitHub Action 3. Use codex exec to analyze diff or test log 4. Save result as comment or artifact 5. Final human check

Most important principle in CI is security:

Don't indiscriminately expose API key to whole job. Don't inject secret before repository-controlled script runs. Give write permission only to needed jobs. Don't auto-merge Codex fix results.

22Connecting codex exec and CI

In CI, non-interactive codex exec fits better than interactive codex.

Example:

codex exec "Review current git diff and summarize only potential bugs"

Test log analysis:

npm test 2>&1 | tee test.log cat test.log | codex exec \ "Analyze this test failure log, summarize root causes and minimal fix direction" \ -o codex-test-analysis.md

23PR Review codex exec

For PR review:

git diff origin/main...HEAD | codex exec \ "Review this PR diff. Output: 1. Fatal bug possibilities 2. Missing tests 3. Security risks 4. Items to check before merge" \ -o codex-review.md

Recommended default combination in CI:

Review/analysis work → read-only Patch generation → workspace-write Auto-merge → not recommended approval_policy → never

24Codex SDK

Codex SDK is how you call Codex inside your own Python or TypeScript program, rather than via CLI or IDE.

Beginners can understand it this way:

CLI
Human uses directly in terminal
IDE
Human uses directly in code editor
GitHub Action
Runs automatically in CI
SDK
My program calls Codex

25SDK Use Cases

When SDK is needed:

Build in-house code review bot Create automatic test failure analysis system Automate issue triage Build refactoring pipeline Interpret security scan results with Codex Connect custom dashboard to Codex

Example structure:

1. Python script reads GitHub issue. 2. Create thread with Codex SDK. 3. Pass issue content and related files as context. 4. Codex returns analysis. 5. Script saves as comment or report.

26SDK vs CLI Difference

User
CLI: human / SDK: program
Execution
CLI: terminal command / SDK: call from code
Suitable Work
CLI: direct analysis and edits / SDK: productized automation
Setup Difficulty
CLI: low / SDK: high
Recurring Run
CLI: via script / SDK: easier to structure
Result Handling
CLI: stdout, files / SDK: objects, JSON, DB storage

27When CLI is Enough

CLI is enough for:

Personal automation Simple review Test log summary Release note generation

SDK is needed for:

Need to traverse multiple repos Need to save results to DB Need to connect to internal systems Need to manage per-user permissions, state, history Need to operate defined workflow like a product

28Recommended Beginner Integration Workflow

Don't use all four at once. Better to expand in this order:

1IDE ExtensionCurrent file explanation, small edits, test failure analysis
2IDE + CLICode review, repo analysis, recurring automation
3IDE + CloudDelegate long work, review result diff
4Chrome ExtensionLogged-in web apps, admin console, dashboard work
5GitHub ActionPR review, test failure analysis, release note automation
6SDKIn-house bots, custom automation, large-scale workflow

29Beginner First Routine

Best first routine for beginners:

1. Open project in VS Code. 2. Open Codex Extension. 3. Request explanation based on current file. 4. Delegate only small edits. 5. Test in IDE terminal. 6. Pass failure log to Codex again. 7. Review diff directly. 8. Expand to Cloud, Chrome, CI when comfortable.
Section 27 · Wrap-up

Core of This Section

IDE Extension
Use Codex inside code editor
Chrome Extension
Use Codex from logged-in browser work
GitHub Action
Auto-run Codex in CI/CD
SDK
Call Codex from your own system

Most important criterion is:

Fix code → IDE Extension / Work in browser → Chrome Extension / Automate PR and CI → GitHub Action / Connect like a product → SDK
Next Section

Section 28. Operational Optimization: Performance, Debugging, Security, Enterprise

28. Operations Optimization: Performance, Debugging, Security, Enterprise

01The Essence of Codex Operations Optimization

Operating Codex well doesn't just mean "making it answer faster." The real goal is to satisfy four things simultaneously.

Speed
Reduce unnecessary exploration and wasted conversation
Stability
Keep session, config, and Git state predictable
Security
Control sandbox, approval, secret, and network
Organizational Operations
Create shared team settings and auditable standards

Codex settings are decided at multiple layers: user config, project config, profile, system config, and managed requirements. The priority order is CLI flag and override (highest), then project config, profile, user config, system config, and built-in default (lowest).

28-A · Performance Optimization

02Why Codex Gets Slow

Codex slowing down isn't always because the model itself is slow. Most of the time it's because input context is too large, the task scope is unclear, tool output is too long, or MCPs, files, and logs are attached excessively.

Common Causes

When noisy output accumulates in long conversations, context pollution and context rot occur, lowering session reliability. It's better to keep core requirements and decisions in the main thread, and separate noisy work like exploration, testing, and log analysis into subagents or separate threads.

03Context Window Management

The context window is the working memory space where Codex refers to when judging current work. More isn't always better—putting in just the right information is what matters.

Bad Approach

Look at this entire repo and find and fix performance issues.

Good Approach

Focus on src/api/orders and tests/orders, and find the cause of slow order creation API. First, organize just 3 or fewer bottleneck candidates without modifying files.

Context Management Principles

04Using /compact

/compact summarizes long conversations to clean up context. It doesn't delete the conversation—it replaces older turns with summaries, keeping only important information.

Good Times to Use

Recommended Procedure

  1. First ask Codex to summarize the current work state.
  2. Verify changed files, decisions, remaining tasks, and test results.
  3. Run /compact.
  4. After compacting, restate the next goal clearly.

05Not Overusing @file

@file is a powerful way to explicitly put specific files into context. But attaching too many files makes Codex take longer to find important information and increases costs.

Guidelines

Bad Example

@src Look at the whole thing and find the issue.

Good Example

@src/auth/middleware.ts @src/auth/session.ts @tests/auth/session.test.ts Focus on these three files and look at the login expiration handling issue. First organize just the root cause candidates without fixing.

06Reducing the Number of MCP Servers

MCP is the standard way to connect Codex with external context outside the repo. Use MCP when the needed context is outside the repo, changes frequently, or repeated integration is required. Don't attach all tools from the start—begin with 1-2 tools that actually remove workflow friction.

Operating Guidelines

Basic Configuration Example

[mcp_servers.github] enabled = true [mcp_servers.figma] enabled = false [mcp_servers.sentry] enabled = false

07MCP Profile Separation Strategy

In practice, it's good to divide profiles by work nature.

Recommended Profile Separation

Create each profile as a separate TOML file and apply with --profile profile-name. This way you activate tools only when needed while maintaining baseline performance.

08Adjusting Tool Output Token Limit

Test logs, build logs, grep, find, npm test, pytest output easily become thousands of lines. If you give all raw output as-is, things slow down and important failure causes get buried.

Reducing Output Volume

# Pass only the last 120 lines instead of the entire log npm test 2>&1 | tail -n 120 # Pass only around the failure line pytest 2>&1 | grep -A 20 -B 10 "FAILED" # Save only TypeScript errors npm run typecheck 2>&1 | grep "error TS" > ts-errors.log

How to Instruct Codex

You can tell Codex: "Don't try to read all the logs. Find the root cause based on the failed test names, first stack trace, and related file paths."

09Using Fast Profile

For quick iteration work, you don't always need the highest reasoning effort. Codex's fast mode increases speed in exchange for higher credit rate usage.

Fast Work Profile Example

model = "gpt-5.4-mini" model_reasoning_effort = "low" approval_policy = "on-request" sandbox_mode = "workspace-write" [features] fast_mode = true service_tier = "fast"

Execution

codex --profile fast

10Fast Profile Recommended Use Cases

Recommended Use Cases

Not Recommended Use Cases

11Subagent Work Separation

Subagents divide large tasks among multiple agents. Each subagent performs its own model and tool work, using more tokens, but for independent read-heavy work like exploration, testing, triage, and summarization, there's a parallelization advantage.

Good Example

Review this branch with parallel subagents. - agent 1: Security risks - agent 2: Missing tests - agent 3: Maintainability issues After all three agents finish, remove duplicates and summarize by priority.

Operating Guidelines

12Exploration Optimization in Large Repos

In large repos, "show me everything" is the slowest request. First narrow the structure, then narrow the files, finally limit the change scope.

Recommended Routine

  1. Summarize repo structure
  2. Find related package candidates
  3. Find the entrypoint
  4. Trace the call flow
  5. Limit fix candidate files
  6. Specify test scope

Prompt Example

Don't read this entire repo. Just find entrypoint candidates related to the payment API. Don't modify files. Organize related directories and key file candidates into 10 or fewer.

13Balancing Cost and Speed

Cost and speed are heavily influenced by three things: model choice, reasoning effort, and context and tool output size.

Recommended Combinations

Fast exploration
Mini series + low
General fixes
Default model + medium
Complex bugs
Default model + high
Security/architecture decisions
Strong model + high/xhigh
Subagent exploration
Faster model + low/medium
Final integration decision
Strong model + medium/high

Beginner Default

model = "gpt-5.5" model_reasoning_effort = "medium" approval_policy = "on-request" sandbox_mode = "workspace-write"
28-B · Problem Debugging

14Basic Codex Troubleshooting Order

When Codex behaves strangely, check operating state before rewriting prompts.

Check Order

  1. Verify Git state
  2. Verify current working directory
  3. Verify Codex session state
  4. Verify config applied values
  5. Verify authentication state
  6. Verify sandbox / approval
  7. Disable MCP / plugin and reproduce
  8. Verify shell environment
  9. Check logs and doctor report

Basic Commands

pwd git status codex doctor --summary codex doctor --json > codex-doctor.json

15codex doctor

codex doctor is a stable command that checks local installation, config, auth, runtime, Git, terminal, app-server, and thread inventory state.

Usage

Summary only: codex doctor --summary JSON for support requests: codex doctor --json > codex-doctor.json

Items to Check

Note that the doctor report shows "current Codex state itself" but doesn't judge whether your prompt is good or bad.

16Checking /status

During a session, use /status to verify the current work state.

What to Check

Especially for sandbox issues, you must first verify the workspace root is correct. For example, if you ran from apps/frontend but the actual modification target is packages/shared, Codex might try to modify files outside its permissions or keep requesting approval.

Resolution Example

codex --cd apps/frontend --add-dir ../shared

17Checking /config

Config issues mostly happen when "the config I think I have" differs from "the config actually applied."

What to Check

Codex reads user-level config from ~/.codex/config.toml and in trusted projects also reads .codex/config.toml. Project config cannot override certain machine-local keys like some provider, auth, and telemetry routing. Profile files go next to config.toml in the form ~/.codex/profile-name.config.toml.

One-Time Override Example

codex --config model='"gpt-5.4"' codex --config sandbox_workspace_write.network_access=true codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

18Authentication Issues

Let's learn the symptoms and how to check authentication problems.

Problem Symptoms

Check Commands

codex login codex logout codex doctor --summary

Troubleshooting Order

  1. Verify CLI and IDE use the same account
  2. Verify whether it's ChatGPT login or API Key login
  3. Verify whether it's company workspace account or personal account
  4. Verify model permissions and plan permissions
  5. If needed, logout and login again

19Sandbox Issues

Let's learn typical sandbox problem symptoms and solutions.

Problem Symptoms

sandbox_mode accepts read-only, workspace-write, and danger-full-access values, determining file system and network access policies during command execution.

Recommended Combination

sandbox_mode = "workspace-write" approval_policy = "on-request" [sandbox_workspace_write] network_access = false

20Approval Issues

Approval issues occur when Codex keeps asking "can I do this?" or conversely, when it runs way too much without asking.

approval_policy Options

It's recommended to use on-request for interactive runs and never for non-interactive runs.

Recommended Guidelines

Beginner local work
on-request
Untrusted repo
untrusted
CI analysis work
never
Automated patch generation
never + restricted sandbox
Risky work review
on-request or auto_review

21Auto-Review Configuration

With auto-review attached, you can send approval-requiring requests to a reviewer agent first.

Configuration Example

approval_policy = "on-request" approvals_reviewer = "auto_review"

approvals_reviewer = "auto_review" sends approval-requiring requests to a reviewer agent first. The reviewer checks sandbox escalation, blocked network requests, permission requests, side-effecting app/MCP tool calls, and evaluates risks like data exfiltration, credential probing, and destructive actions.

Automatic review uses additional model calls, so usage may increase.

22MCP / Plugin Issues

Let's learn MCP problem symptoms and how to check them.

Problem Symptoms

How to Check

codex mcp list codex doctor --summary

If MCP is suspected, first disable all and reproduce. For plugin issues, disable recently installed plugins, verify if they include hooks, check MCPs added by plugins, and run with minimal configuration.

23Shell Environment Issues

Shell environment issues are the most common problem beginners encounter.

Problem Symptoms

Recommended Environment Setup

source .venv/bin/activate export NODE_ENV=test npm install codex

Before running Codex, source language environments like Python virtual environment and prepare necessary daemons and environment variables. This prevents Codex from wasting tokens exploring the environment.

24Shell_environment_policy Configuration

With shell_environment_policy, you can control which environment variables are passed to subprocesses.

Conservative Configuration Example

[shell_environment_policy] inherit = "core" include_only = ["PATH", "HOME", "USER", "SHELL", "NODE_ENV"] exclude = ["*SECRET*", "*TOKEN*", "*KEY*"]

include_only keeps only allowed variable patterns, exclude removes specific patterns, and inherit accepts all, core, or none values.

25Git State Issues

Always check Git state before and after Codex work.

Check Commands

git status git diff git branch --show-current

Problem Symptoms

Safe Routine

git status git stash push -m "before codex work" codex git diff npm test

26Log Review and Common Errors

When reproducing issues, pass them to Codex in the following format.

Good Prompt Structure

Common Error Response Guide

File modification fails
Check sandbox, writable root
Command execution fails
Check approval, shell env
Network fails
Check network_access
MCP fails
Check MCP auth, server running
Slow
Check context, MCP count, reasoning effort
28-C · Security Guide

27Codex Security Principles

Codex security fundamentals are not trusting a smart agent, but limiting what the agent can do.

Core Principles

workspace-write sandbox has network access off by default. To turn on network access, set [sandbox_workspace_write] network_access = true.

28Understanding OS-Level Sandbox

Sandbox limits the file system and network access scope of commands Codex executes.

sandbox_mode Options

Be careful with danger-full-access or --dangerously-bypass-approvals-and-sandbox, and use only in isolated environments like Docker when necessary.

29Protecting Sensitive Files

The following files require special care.

Sensitive File Examples

Team Policy Example

[permissions.filesystem] deny_read = [ "/**/*.env", "~/.ssh", "~/.aws", ]

It's good to reduce secrets in shell environment in personal settings and enforce deny-read with managed requirements in team settings.

30Environment Variables and Secret Management

Environment variables are convenient, but if an agent can run shell commands, secrets can be unintentionally exposed.

Risky Example

export OPENAI_API_KEY=... export PROD_DB_PASSWORD=... codex --sandbox danger-full-access

Safer Way

[shell_environment_policy] inherit = "core" exclude = ["*SECRET*", "*TOKEN*", "*KEY*", "*PASSWORD*"]

Operating Principles

31Advanced shell_environment_policy

shell_environment_policy determines which environment variables to pass to subprocesses when Codex runs them.

Core Keys

inherit
Base environment inheritance scope. all, core, none
include_only
Whitelist of allowed variable patterns
exclude
Patterns to remove
set
Explicit variables to add to all subprocesses
ignore_default_excludes
Ignore default removal of variables with KEY/SECRET/TOKEN

ignore_default_excludes keeps variables with KEY, SECRET, TOKEN before other filters apply, so it requires extreme security care.

32Restricting Network Access

When Codex has network access, it's easy to check external docs, install packages, and call APIs. But from a security perspective, data exfiltration and prompt injection risks increase.

Basic Recommendation

sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = false

Enable Only When Needed

[sandbox_workspace_write] network_access = true

In team environments, it's better to control with domain allowlist in requirements. You can define central network requirements in [experimental_network] and set allowed/denied domains and managed allowlist-only mode.

33danger-full-access Usage Guidelines

danger-full-access is convenient but shouldn't become the default work mode.

Acceptable Uses

Unacceptable Uses

Pre-Execution Checklist

34Guardian Review / Auto-Review

Auto-review has a reviewer agent evaluate risk before a person sees approval requests.

Configuration

approval_policy = "on-request" approvals_reviewer = "auto_review"

The reviewer evaluates already-approval-requiring actions like sandbox escalation, blocked network requests, permission requests, and side-effecting app/MCP tool calls, checking risks like data exfiltration, credential probing, and destructive actions.

Good Team Use Cases

35Hooks and Security

Hooks automatically run scripts matching Codex lifecycle events. They're powerful from a security perspective but can create a new attack surface if misused.

Security Hook Examples

In teams, it's good to control with managed hooks. Admins can define lifecycle hooks in requirements.toml and use allow_managed_hooks_only = true to load only managed hooks, skipping user, project, session, and plugin hooks.

36Team Security Checklist

Team Standard Checklist

Example Team Base Config

model = "gpt-5.5" model_reasoning_effort = "medium" approval_policy = "on-request" sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = false [shell_environment_policy] inherit = "core" exclude = ["*KEY*", "*SECRET*", "*TOKEN*", "*PASSWORD*"]
28-D · Enterprise Deployment

37Organization-Wide Codex Operations

When operating Codex in an organization, the following matters more than individual productivity.

Core Organization Operations

Enterprise admins can control Codex behavior in two ways: requirements that users cannot override, and managed defaults that provide starting values but users can change during sessions.

38System Config

System config provides machine-level default values.

Unix Location

/etc/codex/config.toml can be used as the system config layer.

Configuration Priority

System config ranks lower than user config and higher than built-in defaults.

Example

# /etc/codex/config.toml model = "gpt-5.5" model_reasoning_effort = "medium" approval_policy = "on-request" sandbox_mode = "workspace-write"

Use system config as "recommended defaults" and enforce control with requirements.toml.

39requirements.toml

requirements.toml is where organization admins enforce security-sensitive configuration.

Good Items to Enforce

Example

allowed_approval_policies = ["untrusted", "on-request"] allowed_sandbox_modes = ["read-only", "workspace-write"] allowed_web_search_modes = ["cached"] [permissions.filesystem] deny_read = [ "/**/*.env", "~/.ssh", ]

40Model and Reasoning Effort Restrictions

Organizations should set usage standards for model and reasoning effort to balance cost, security, and quality.

Example Policy

Profile Example

# ~/.codex/review.config.toml model = "gpt-5.5" model_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "read-only"

Profile files overlay on top of base user config in the form ~/.codex/profile-name.config.toml.

41Permission Profile Management

Permission profiles standardize "what permissions for what work" across the team.

Recommended Profiles

security-review Profile Example

model = "gpt-5.5" model_reasoning_effort = "high" sandbox_mode = "read-only" approval_policy = "on-request" [sandbox_workspace_write] network_access = false

42Audit Logs and OpenTelemetry

Large organizations need to track Codex usage, failures, approval flows, and configuration drift.

Items to Observe

OTel Configuration Example

[otel] environment = "prod" exporter = "otlp-http" log_user_prompt = false

43SSO / Account Management

Organizations are better served with workspace accounts and central management rather than individual API key operations.

Operating Guidelines

Documentation Items

44Large Organization Operations Strategy

In large organizations, "how to use" is more important than "allowing Codex."

Adoption Order

  1. Select 1 pilot repo
  2. Write basic AGENTS.md
  3. Define team common profile
  4. Agree on sandbox / approval defaults
  5. Connect only 1-2 minimum MCPs
  6. Experiment with PR review automation
  7. Collect failure cases and good prompts
  8. Add Codex usage to docs/onboarding
  9. Expand CI automation scope
  10. Review enterprise policy and requirements with security, legal, and platform teams

Organization Operations Principles

Section 28 · Wrap-up

What to Remember from This Unit

To make Codex fast, reduce context. To make Codex safe, reduce permissions. To make Codex work in organizations, standardize configuration.

Performance Optimization

Problem Debugging

Security and Enterprise

Next Section

Section 29. Real-World Workflows and Migration

29. Real-World Workflows and Migration

01The Core of This Unit

Good Codex users aren't "people who assign big work at once"—they're people who break tasks into small pieces and build verification loops.

Bad flow:

Look at the entire project and improve it on your own.

Good flow:

1. Narrow the problem scope. 2. Get a plan first. 3. Make small changes only. 4. Verify diff. 5. Run tests. 6. If it fails, provide the log again. 7. Get a final summary and commit message.

OpenAI's Codex best practices also recommend getting a plan first for difficult work, and making repeating instructions reusable through AGENTS.md.

02How to Write Good Prompts

Good prompts include these 5 things.

1. Goal
What needs to be done
2. Fix Scope
Where should we check
3. Forbidden Work
What should not be done
4. Verification Command
How will we verify
5. Desired Output Format
What format to answer in

03Good Prompt Example

Goal: Fix login failure to return 401 instead of 500. Fix scope: Check only in src/auth, tests/auth. Forbidden: Don't refactor the entire auth structure. Don't make unrelated formatting changes. Verification: npm test -- auth Output: - Root cause - Modified files - Test results - Remaining risks

After receiving a prompt, Codex repeatedly does model calls, file reading, file editing, tool calls, and other work to complete the task. The more concrete the initial prompt, the less unnecessary exploration Codex does and the more accurately it acts.

04Bad Prompt Patterns

Bad prompts usually have scope that's too broad.

Improve this project. Find all bugs. Make performance good. Strengthen security. Refactor the entire codebase. Add tests on your own.

These requests are bad because Codex finds it hard to understand what counts as success.

05Bad Prompt Improvement Example

Bad request:

Improve performance.

Good request:

Find the cause of slow orders API response. Check only src/api/orders and src/db/orders related files, and organize 3 or fewer bottleneck candidates before modifying.

06Breaking Down into Small Tasks

Codex work succeeds more when the task is smaller.

Big task:

Refactor the payment system.

Broken down into small tasks:

1. Find the entrypoint of payment creation flow. 2. Explain the failure handling logic only. 3. Find the retry condition duplication. 4. Create a fix plan. 5. Fix one file first. 6. Add related tests. 7. Review the entire diff.

07Task Size Recommendations

5-minute fix
Can request directly
30-minute bug
Analyze cause → plan → fix
Half-day refactoring
/plan or separate thread
Multiple module changes
Task separation or subagents
Long-term work
Cloud / Worktree / PR unit

08Plan First, Execute Later

Complex work requires getting a plan first.

Create only the plan. Don't modify files. Show the target files, change reasons, and test strategy.

Good plan request:

Review whether duplicate payment can occur on payment failure. Don't modify code first. 1. Related files 2. Current flow 3. Risk points 4. Fix plan 5. Needed tests Organize in this order.

09Execute After Plan Approval

Then approve the execution.

OK. Execute plan 2. But don't change public API signature. After fixing, run npm test -- payments.

Official best practices also recommend the flow of requesting a plan first for difficult work, confirming the direction with the user, then implementing.

10The Habit of Verifying Diff

After Codex modifies code, always verify the diff.

git diff

Items to verify:

11Diff Review Request Example

Review the diff you just changed yourself. Check only these items. 1. Unrelated changes 2. Missing tests 3. Edge cases 4. Security risks 5. Parts that could be fixed more minimally

Codex app handles multiple threads in parallel and provides Git features and worktree support. If you need to review diffs visually and stage/revert them, Desktop App is more convenient than CLI.

12Specifying Test Commands

Just telling Codex "also test" isn't enough. Test commands differ by project.

Good example (Node.js):

After fixing, run these commands. npm test -- auth npm run typecheck npm run lint

13Python / Rust Test Commands

Python project:

After fixing, run these commands. pytest tests/auth -q ruff check . mypy .

Rust project:

After fixing, run these commands. cargo test auth cargo clippy

14Responding to Test Failures

When tests fail, don't attach the entire log—pass only the core.

Fix based on this failure log. Don't do complete refactoring. Command: npm test -- auth Failure: ...

15Don't Neglect AGENTS.md

Instructions you repeat shouldn't be put in the prompt each time—put them in AGENTS.md.

Good content for AGENTS.md:

16AGENTS.md Example

# AGENTS.md ## Work Principles - No unrelated refactoring - Write plan before changing public API - Don't report completion without tests ## Tests - unit test: npm test - typecheck: npm run typecheck - lint: npm run lint ## Code Style - Keep existing patterns - Confirm before changing public API ## Security - Don't read .env, secret, token files - Explain edge cases when changing auth/payment/permission logic

Codex reads the AGENTS.md file before work and applies global guidance and project-specific overrides hierarchically. Good AGENTS.md must be short and clear.

17Not Over-Attaching MCPs

MCPs are powerful but connecting all tools always makes Codex slow and context complex.

Good guideline:

OpenAI best practices explain to use MCP when the needed context is outside the repo, changes frequently, or repeated integration is needed. It's better to start with 1-2 tools that actually reduce workflow friction rather than attaching many tools from the start.

18Using Reasoning Effort Correctly

High reasoning effort like xhigh is useful for complex judgment but not every task needs it.

low
Log summarizing, simple doc organizing, small type errors
medium
General feature fixing, test adding, normal difficulty bugs
high
Bugs spanning multiple files, refactoring plans, security review
xhigh
Architecture decisions, complex concurrency issues, payment/auth/permission logic

Continually using xhigh on small tasks increases cost and time. It's good to keep medium as the default and raise it only when failing or high-risk.

19Work Not to Assign to Codex

There's work you shouldn't assign to Codex.

20Requesting Risky Work Correctly

Risky work should be reframed like this.

Bad request:

Find and fix problems in production DB.

Good request:

Analyze root causes based on this anonymized error log. Don't access or modify the actual DB.

21Analyzing an Unknown Codebase

For a new repo, don't modify right away.

Recommended prompt:

Assume you're seeing this codebase for the first time and explain. Don't modify files. Output: 1. Project purpose 2. Main directories 3. Execution entrypoint 4. Test structure 5. Config files 6. Things to be careful about when Codex works

22Codebase Analysis Step-by-Step

After the first explanation, narrow down further.

Explain only the authentication flow in more detail. Organize related file candidates into 10 or fewer, and don't modify yet.

CLI is an environment where you can read repositories, modify files, and execute commands while iterating interactively with the user. For unknown codebases, it's good to start with interactive CLI or IDE to understand structure first.

23Fixing Failed Tests

Fixing test failures is one of Codex's strong tasks. Narrow the failure scope instead of throwing the entire log.

Flow:

  1. Run the failing test command
  2. Pass only the core log
  3. Request root cause candidates first
  4. Request minimal fix
  5. Re-run tests
  6. Review diff

24Test Failure Prompt

Analyze this test failure. First organize 3 or fewer root cause candidates, and fix minimally starting from the most likely cause. Command: npm test -- auth Log: ...

After fixing:

Explain the modified part and let me know why this test should pass. Also check if there are unrelated changes.

25Adding a New API Endpoint

API additions easily get out of scope. First find the structure.

I want to add a new API endpoint. First, investigate the existing API pattern. Goal: Add POST /api/orders/:id/cancel Don't fix yet, organize only: 1. Where existing routes are defined 2. Controller/service structure 3. Validation method 4. Test location 5. Implementation plan

26API Endpoint Implementation and Wrap-up

After plan confirmation:

OK. Implement maintaining existing patterns. Fix scope: - route - controller - service - tests/orders Forbidden: Don't refactor common error handler

Wrap-up:

Organize changed files, test results, and API usage example.

27Planning a Refactoring

Refactoring is risky if executed directly. You must get a plan first.

I want to refactor this module. Don't modify files yet. Goal: Reduce duplicate validation logic and improve testability Output: 1. Current structure problems 2. Refactoring candidates 3. Risk level 4. Step-by-step plan 5. Tests to run at each step

28Executing Refactoring Step by Step

Good refactoring doesn't finish at once.

Step 1: Extract duplicate function without moving code Step 2: Add tests Step 3: Replace call sites Step 4: Remove deprecated code Step 5: Full test

Using worktrees lets you run independent work in parallel in the same repository without interfering with each other. It's safer to conduct experimental refactoring in a worktree or separate branch instead of mixing with existing work.

29Security Review

It's good to start security review read-only.

Review the current branch diff from a security perspective. Don't modify files. Focus items: 1. Authentication bypass potential 2. Missing permission checks 3. Insufficient input validation 4. Secret exposure 5. SSRF / SQL injection / XSS potential 6. Sensitive info left in logs

30Security Review Result Format and Fixing

Result format:

Write each issue in this format. - Risk: high / medium / low - Location: - Problem: - Attack Scenario: - Fix Direction: - Test Suggestion:

Pass fixing as a separate step.

Fix only item 1 with high risk from the review. Add related tests after fixing, and don't touch other items.

31Automating PR Review

PR review should filter easy-to-miss items first rather than replacing human review.

Locally:

git diff origin/main...HEAD | codex exec \ "Review this PR diff. Output: 1. Critical bug potential 2. Missing tests 3. Security risks 4. Unnecessary changes 5. Things to check before merging" \ -o codex-pr-review.md

32CI Automation for PR Review

In CI:

  1. PR created
  2. GitHub Action runs
  3. Pass diff to Codex
  4. Save review result as artifact or comment
  5. Person confirms finally

Codex GitHub Action lets you run repeatable Codex work in GitHub Actions workflows, automating PR review, release prep, migration, and other work.

33Auto-Updating Documentation

Documentation often lags behind code changes. Having Codex find doc gaps is useful.

Based on the current git diff, find places where documentation needs updating. Don't modify docs yet, organize update candidates and reasons.

Fix request:

Update only the API usage example in README. Don't modify code files. Keep existing tone and format.

34Planning Migration Work

Migration carries large failure risk so it must be broken into steps.

Example: Move library v1 to v2

I want to migrate from library v1 to v2. First investigate the impact scope without modifying files. Output: 1. v1 API usage locations 2. Patterns needing changes 3. Risky call sites 4. Step-by-step migration plan 5. Test strategy

35Executing Migration Step by Step

Then execute in small units.

Proceed with step 1 only. Replace deprecated import with new import, but don't change behavior logic. After fixing, run typecheck only.

Good migration principles:

36Generating Release Notes

Release notes work well with codex exec.

git log --oneline v1.2.0..HEAD | codex exec \ "Organize this commit list into user-facing release notes. Focus on user impact over internal implementation details." \ -o release-notes.md

Better input:

git log --oneline v1.2.0..HEAD > commits.txt git diff --stat v1.2.0..HEAD > diff-stat.txt

37Detailed Release Notes Execution

codex exec \ "Create release notes based on commits.txt and diff-stat.txt. Sections: - Added - Changed - Fixed - Migration Notes - Known Issues" \ -o release-notes.md

codex exec runs Codex in non-interactive mode without opening an interactive TUI, suitable for scripts and CI. It fits well with repeatable output generation work like release notes.

38Issue Triage

Issue triage focuses on "classification" over "fixing."

Triage this GitHub issue. Don't modify code. Output: 1. Type: bug / feature / question / docs 2. Priority: P0 / P1 / P2 / P3 3. Reproducibility 4. Needed additional info 5. Related code candidates 6. Summary for next owner

39Issue Triage Automation Schema

When automating multiple issues, setting a schema helps.

{ "type": "bug", "priority": "P2", "needs_reproduction": true, "missing_info": ["version", "logs"], "suggested_owner": "frontend" }

40Creating Team Onboarding Materials

Codex is useful for reading existing repos and drafting onboarding docs.

Create an onboarding doc draft for new developers. Don't create the file yet, propose a table of contents first. Include: 1. Project purpose 2. How to run locally 3. How to test 4. Main directories 5. Deployment flow 6. Common errors 7. Recommended first issues

41Generating and Principles of Onboarding Documents

Then create the document:

OK. Write to docs/onboarding.md. But mark uncertain content as "needs confirmation."

Important principles:

42Browser-Based Work Automation

Browser work should be thought of separately from code work.

Fitting work:

Check user permission settings in this admin page. Don't make changes, just summarize current settings and risky-looking items.

43Browser Automation Precautions

When modifications are needed:

Change only these items. Don't touch other settings. Changes: - Role: Viewer - Export permission: Off

Browser automation requires care with permissions and data exposure. It's safer to narrow work scope and grant permissions only to needed sites when dealing with screens showing customer data, admin rights, payment info, or internal metrics.

44Moving from Other Tools to Codex

When moving from another AI coding tool to Codex, "changing commands as-is" is less important than changing work habits to Codex style.

Core Shifts:

45Claude Code Users → Codex

If you're familiar with terminal-based agents like Claude Code, Codex CLI is the most natural starting point.

Transition Points:

Recommended first config:

model = "gpt-5.5" model_reasoning_effort = "medium" sandbox_mode = "workspace-write" approval_policy = "on-request"

46Cursor Users → Codex

If you're a Cursor user, it's natural to start with Codex Extension in IDE first.

Transition Points:

For Cursor, good to separate roles between existing IDE AI features and Codex.

47Cursor Role Separation Details

IDE base AI:

Codex:

48Copilot Users → Codex

Users familiar with Copilot need to separate "auto-completion" and "agent work."

Transition Points:

Rather than completely abandoning Copilot, attaching Codex to larger work units works well.

49Copilot Work Step-by-Step Roles

50Aider Users → Codex

If you're familiar with Git-based code editing flow like Aider, Git discipline matters in Codex too.

Transition Points:

51Aider Flow and Commit Messages

Recommended flow:

git status codex git diff npm test git add . git commit -m "fix: handle expired auth sessions"

You can have Codex create commit messages.

Propose a commit message in Conventional Commit format based on current diff. Include why changes were made and test results in the body.

52Adding AGENTS.md to Existing Projects

The first practical task for migration is adding AGENTS.md.

Initial prompt:

Create an appropriate AGENTS.md draft for this repo. Don't create the file yet, explain what should be included and why.

Then create:

OK. Create AGENTS.md at the root. Keep content short and practical-guideline focused.

53AGENTS.md Initial Template

# AGENTS.md ## Project Overview - Briefly explain this project's purpose. ## Work Principles - No unrelated refactoring - Write plan before public API changes - Don't report completion without tests ## Commands - install: - test: - typecheck: - lint: ## Code Style - Maintain existing patterns - Confirm before public API changes ## Security - Don't read .env, secret, token files - Explain edge cases when changing auth/payment/permission logic

54Attaching codex exec to Existing Automation

When attaching Codex to existing shell scripts or CI, codex exec is simplest.

Existing test script:

npm test

Add Codex analysis:

npm test 2>&1 | tee test.log || true cat test.log | codex exec \ "Analyze this test failure log. Output: 1. Failed tests 2. Direct cause 3. Related file candidates 4. Minimal fix direction" \ -o reports/test-analysis.md

55Attaching Codex to Existing PR Workflow

Existing PR workflow:

git diff origin/main...HEAD

Add Codex review:

git diff origin/main...HEAD | codex exec \ "Review this PR diff. Point out only critical bugs, missing tests, security risks." \ -o reports/codex-review.md

These combinations are safely used in CI by default:

56Team Migration Checklist

When adopting Codex organization-wide, this order is good.

  1. Select 1 pilot repo
  2. Write basic AGENTS.md
  3. Define team common profile
  4. Agree on sandbox / approval defaults
  5. Connect only 1-2 minimum MCPs
  6. Experiment with PR review automation
  7. Collect failure cases and good prompts
  8. Add Codex usage to docs/onboarding
  9. Expand CI automation scope
  10. Review Enterprise policy and requirements

57Team Standard Documentation Items

Items to include in team standard docs:

58Migration Success Criteria

Migration success criteria:

59Unit 29 Core Summary ① · Good Usage

Good usage:

60Unit 29 Core Summary ② · Bad Usage

Bad usage:

61Final Principle

Codex isn't a "developer replacing worker" but an agent that breaks work small and runs verification loops fast.

Breaking work small, verifying plans, checking diffs, and closing with tests is the most stable flow.

Section 29 · Wrap-up

What to Remember from This Unit

Good work habits are the most important Codex performance improvement.

Codex learns how you work. When the habit develops of breaking work small, getting plans first, verifying diffs, and specifying tests, Codex becomes a more accurate and trustworthy tool.

Small → Plan → Execute → Verify → Automate

Repeating this flow lifts both team development speed and stability.

Next Section

Section 30. Quick Reference, Updates, Reference Materials