OpenAI Codex Tutorial: Complete Guide to the AI Coding Agent

OpenAI Codex is no longer just a terminal assistant. It is a full coding-agent system that can work in your terminal, inside your IDE, in the Codex desktop app, in cloud environments, in GitHub pull requests, and inside automated CI or internal tooling.

This guide is written against the official OpenAI Codex documentation available on June 21, 2026. Product names, models, pricing, and install commands can change, so use the official links at the end when you need the newest detail.

---

What Is OpenAI Codex?

OpenAI Codex is OpenAI's coding agent for software development. It can read a codebase, explain unfamiliar systems, edit files, run commands, debug failures, review changes, automate routine engineering work, and coordinate multi-step implementation tasks.

The important shift is that Codex is agentic: you give it a goal, it gathers context, proposes or follows a plan, edits files, runs checks, inspects output, and iterates until the task is complete or blocked.

What Codex Can Help With

• Write code: implement features, scripts, tests, migrations, UI changes, and documentation.
• Understand codebases: map architecture, explain modules, summarize flows, and identify risky areas.
• Debug failures: inspect logs, reproduce errors, isolate causes, and patch the smallest likely fix.
• Review code: find serious bugs, missed edge cases, risky diffs, security regressions, and missing tests.
• Automate development tasks: run repeatable checks, update docs, triage issues, prepare release notes, and fix CI failures.
• Connect to tools: use MCP servers, plugins, browser tools, computer use, GitHub, Linear, Slack, Figma, Sentry, and internal docs when configured.

---

Codex Surfaces: Which One Should You Use?

Codex has several surfaces. They share the same underlying agent idea, but each surface fits a different workflow.

Practical Recommendation

Start with the Codex app if you want the richest local experience. Use the CLI if you live in the terminal. Use the IDE extension when editor context matters. Use cloud when you want a background task or isolated branch-based run. Use codex exec, the GitHub Action, or the SDK when the workflow needs to run without an interactive UI.

---

Part 1: Installation and First Setup

Account and Access

Every ChatGPT plan includes Codex, and you can also use Codex with API credits by signing in with an OpenAI API key.

The sign-in method matters:

• ChatGPT sign-in uses your ChatGPT plan, workspace permissions, enterprise controls, and Codex cloud access.
• API key sign-in uses OpenAI Platform billing and is useful for local CLI, IDE, and automation workflows.
• Codex cloud requires ChatGPT sign-in.

Install the Codex App

The Codex app is available for macOS and Windows. Download it from the official Codex quickstart, open it, sign in with ChatGPT or an API key, choose a project folder, and start your first Local thread.

Use the app when you want:

• multiple threads across projects
• Git worktrees
• an integrated terminal
• Git diff, stage, commit, push, and PR flows
• automations
• in-app browser previews
• computer use for desktop applications
• artifact previews for PDFs, spreadsheets, documents, and presentations

Install the Codex IDE Extension

Install the Codex extension for Visual Studio Code, Cursor, Windsurf, or another VS Code-compatible editor. After installation, open the Codex panel from the sidebar and sign in.

The extension starts in Agent mode by default, which lets Codex read files, run commands, and write changes in your project directory. Switch to a more constrained chat/planning mode when you only want advice.

Install the Codex CLI

On macOS or Linux, the official standalone installer is:

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

On Windows PowerShell:

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

For unattended installs:

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

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

You can also install the CLI with npm or Homebrew:

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

Verify the install:

codex --version
codex --help

Sign In

Run:

codex login

Then choose ChatGPT sign-in or API key sign-in. The CLI and IDE extension share cached login details. If you sign out from one, you may need to sign in again in the other.

For headless machines, use device-code authentication:

codex login --device-auth

For trusted automation that needs API-key usage, prefer setting credentials only for the command that needs them instead of exposing keys to an entire job environment.

---

Part 2: Your First Codex Session

Open a repository:

cd path/to/your-project
codex

Try a read-only first prompt:

Explain this codebase. Focus on the main entry points, data flow, test commands, and the riskiest modules.

Then try a scoped implementation prompt:

Fix the failing login validation test. Keep the change minimal, run the relevant test, and show me the diff before summarizing.

A Strong Prompt Template

Use this shape for reliable results:

Goal:
Implement [specific behavior].

Context:
Relevant files are [files/folders]. The current error is [error/log].

Constraints:
Keep the change minimal. Follow existing patterns. Do not add dependencies.

Done when:
The relevant tests pass and the diff only touches the intended files.

When to Ask Codex to Plan First

Use plan-first prompting when the task is ambiguous, cross-cutting, risky, or expensive to test:

Before editing, inspect the code and write a short implementation plan. Include the files you expect to change and the checks you will run.

In the CLI, /plan switches into plan mode. In the app, use planning language directly or the available mode controls.

---

Part 3: CLI Essentials

Common Commands

Useful Global Flags

Recommended Local Default

For normal coding work:

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

For advisory work:

codex --sandbox read-only --ask-for-approval on-request

Avoid --dangerously-bypass-approvals-and-sandbox unless Codex is already inside an external sandbox, such as a disposable VM or isolated CI runner.

---

Part 4: Slash Commands

Slash commands let you steer an active CLI session without restarting it.

Use /status often. It is the quickest way to confirm the actual model, sandbox, approvals, writable roots, token usage, and session state.

---

Part 5: Models and Reasoning

The official Codex model guidance available on June 21, 2026 recommends starting most work with gpt-5.5. It is the strongest general Codex model for complex coding, computer use, knowledge work, and research workflows.

For lighter or faster tasks, use gpt-5.4-mini where available. ChatGPT Pro subscribers may also see gpt-5.3-codex-spark as a research-preview option for fast iteration.

Set a Default Model

Add this to ~/.codex/config.toml:

model = "gpt-5.5"

Temporarily override the model:

codex --model gpt-5.5
codex exec --model gpt-5.5 "review the diff for concurrency bugs"

Reasoning Effort

Use low or medium reasoning for narrow, well-scoped edits. Use high reasoning for debugging, architecture changes, security reviews, migration plans, and multi-file refactors.

In config.toml:

model_reasoning_effort = "high"

In the IDE extension, use the model switcher under the chat input.

---

Part 6: Configuration

Codex reads configuration from multiple layers.

Configuration Precedence

Highest precedence first:

1. CLI flags and --config overrides
2. trusted project .codex/config.toml files from repo root down to the current directory
3. selected profile files such as ~/.codex/profile-name.config.toml
4. user config at ~/.codex/config.toml
5. system config such as /etc/codex/config.toml
6. built-in defaults

Project .codex/ config loads only when the project is trusted.

Practical config.toml

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
model_reasoning_effort = "medium"
personality = "pragmatic"

[sandbox_workspace_write]
network_access = false

[shell_environment_policy]
include_only = ["PATH", "HOME", "LANG"]

[features]
hooks = true
multi_agent = true
shell_snapshot = true

Profiles

Profiles let you reuse settings:

codex --profile review
codex exec --profile ci "summarize risk in this pull request"

Use profiles for different operating modes:

• review: read-only, high reasoning, no edits
• frontend: workspace-write, browser tooling enabled
• ci: noninteractive, fixed model, JSON output
• research: live search enabled

---

Part 7: Sandboxing, Approvals, and Security

Security is one of Codex's most important concepts. There are two separate controls:

• Sandbox mode: what Codex can technically access.
• Approval policy: when Codex must ask before acting.

Sandbox Modes

By default, local Codex workflows keep network access off unless you enable it:

[sandbox_workspace_write]
network_access = true

Enable network access only when the task needs it, and prefer scoped network policies when possible.

Approval Policies

For interactive local development, workspace-write plus on-request is the safest productive default.

Protected Paths

In the default workspace-write sandbox, protected paths such as .git, .codex, and .agents are read-only when they appear in writable roots. That helps prevent accidental corruption of agent state or Git internals.

Auto Review for Approvals

If automatic approval review is available, Codex can route eligible approval requests through a reviewer policy before running them. This can catch risky actions such as credential probing, destructive operations, or security weakening.

---

Part 8: Web Search and Network Access

Codex has two separate ideas that are easy to confuse:

• Web search tool: a model tool for looking up web results.
• Command network access: whether shell commands spawned by Codex can reach the network.

Codex local tasks use cached web search by default. You can switch modes:

web_search = "cached"
# web_search = "live"
# web_search = "disabled"

Or for a single CLI run:

codex --search "check the latest release notes and update this migration guide"

Treat web content as untrusted. Prompt injection can appear in docs, issue comments, HTML, package README files, and logs.

---

Part 9: Persistent Instructions with AGENTS.md

AGENTS.md is the durable instruction file Codex reads before work begins. Use it for repo conventions, commands, review expectations, and directory-specific guidance.

Where Codex Looks

Codex can read:

• global guidance in ~/.codex/AGENTS.md
• global override guidance in ~/.codex/AGENTS.override.md
• repo-level AGENTS.md
• nested AGENTS.md or AGENTS.override.md files along the path to the current directory
• fallback filenames if configured

Files closer to the current working directory appear later in the combined prompt and can override broader guidance.

Example AGENTS.md

# AGENTS.md

## Repository expectations

- Use `npm run lint` before opening a pull request.
- Use `npm test -- --runInBand` for targeted test verification.
- Keep changes small and aligned with existing component patterns.
- Do not add production dependencies without asking first.

## Review guidelines

- Flag auth, billing, and data-loss regressions as high priority.
- Treat missing tests as a blocker for shared utilities.
- Mention exact file paths and line numbers in review findings.

Good Uses

• build and test commands
• package-manager preference
• service boundaries
• migration rules
• review style
• deployment checks
• generated-file rules
• directories to avoid
• common local setup notes

Do not turn AGENTS.md into a large architecture book. Keep it focused and move deeper detail into referenced docs or skills.

---

Part 10: Skills, Plugins, MCP, Hooks, and Automations

Codex becomes much more powerful when you customize it around your team's real workflows.

Skills

Skills are reusable workflow packages. A skill is a directory with a SKILL.md file and optional references, scripts, examples, and assets.

Use skills for:

• release workflows
• PR preparation
• translation batches
• design implementation
• data-analysis reports
• security reviews
• migration playbooks
• customer-specific support routines

Minimal skill:

---
name: release-check
description: Prepare and verify a release branch. Use when the user asks to ship, release, or publish changes.
---

1. Inspect the diff and identify the release scope.
2. Run the project's documented checks.
3. Confirm generated assets are current.
4. Draft release notes with changed files and verification results.

Codex can invoke skills explicitly with $skill-name or implicitly when the request matches the skill description.

Plugins

Plugins are installable bundles. They can include skills, MCP configuration, lifecycle hooks, assets, and app integrations. Use plugins when you want to distribute a repeatable workflow to other developers or across an organization.

MCP Servers

MCP connects Codex to external tools and context.

MCP servers can expose:

• tools
• resources
• prompts
• server instructions

Add a local stdio MCP server:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Configure MCP in config.toml:

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

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Use /mcp in the CLI to inspect active MCP servers.

Hooks

Hooks run scripts around Codex lifecycle events. They are useful for validation, policy, logging, prompt scanning, memory creation, and custom guardrails.

Common hook events include:

Example inline 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"

Review hooks before trusting them. Non-managed command hooks require trust because they can run local scripts.

Automations

Automations run recurring Codex tasks in the background. Use them for:

• checking PR status
• polling long-running deployments
• weekly dependency reports
• recurring test-failure triage
• daily changelog summaries
• recurring security checks

Use thread automations when the scheduled work should preserve the current conversation context. Use standalone/project automations when each run should be independent.

---

Part 11: Codex App Workflows

The Codex app is the most complete local surface.

Local, Worktree, and Cloud Modes

When starting a thread, choose:

Use worktrees when you want Codex to experiment without touching your main checkout, or when you want multiple tasks running in the same repository.

Built-In Git Tools

The app can show diffs, stage chunks, revert files, commit, push, and open pull requests. For advanced Git commands, use the integrated terminal.

Integrated Terminal

Each thread has a terminal scoped to the project or worktree. Codex can read terminal output, so it can inspect a failed dev server, a running test command, or a build error without you copying everything manually.

In-App Browser

Use the in-app browser for local development servers, file-backed previews, and public pages that do not require sign-in. You can leave browser comments on specific UI areas, then ask Codex to address them.

Computer Use

Computer use lets Codex operate desktop apps by seeing, clicking, and typing. Use it for GUI-only testing, simulator flows, desktop settings, and apps that do not expose APIs or plugins. Keep tasks narrow because computer use can affect state outside the repo.

Artifacts

The app can preview PDFs, spreadsheets, documents, and presentations. When asking Codex to generate an artifact, specify the expected structure, data source, and verification criteria.

---

Part 12: IDE Extension Workflows

Use the Codex IDE extension when the active editor context matters.

File Mentions

Reference files directly:

Use @CheckoutForm.tsx and @pricing.ts as context. Add a coupon validation state and update the tests.

Selected Code

Select code and ask Codex to explain, refactor, test, or review it. This works well for narrow changes because Codex does not need to rediscover the file context.

Agent, Chat, and Full Access

• Agent: read, edit, and run commands inside the project.
• Chat: answer and plan without acting.
• Agent Full Access: broad access with network; use carefully.

Cloud Delegation from the IDE

For larger jobs, choose a cloud environment and run the task in Codex cloud. You can continue locally after reviewing the cloud output.

---

Part 13: Codex Cloud

Codex cloud runs tasks in OpenAI-managed containers.

When you submit a cloud task:

1. Codex creates a container and checks out the selected repository branch or commit.
2. Setup scripts run and can access the internet to install dependencies.
3. The agent phase begins. Agent internet access is off by default unless configured.
4. Codex edits files, runs commands, and validates its work.
5. You review the summary and diff, ask follow-ups, or open a pull request.

Cloud Environment Setup

Configure:

• repository access
• setup script
• maintenance script
• runtime versions
• environment variables
• secrets
• internet access policy

Secrets are available to setup scripts but removed before the agent phase for security.

When Cloud Is Better Than Local

Use cloud when:

• you want isolated work away from your local checkout
• the task should run while you do other work
• you want branch-based review and PR handoff
• your local machine lacks the dependencies
• a teammate needs to review the result in GitHub

Use local when the task depends on private local state, signed-in browser sessions, local simulators, desktop apps, or hardware.

---

Part 14: Code Review with Codex

Codex supports several review workflows.

Local Review

Inside the CLI:

/review

Review options can include:

• review uncommitted changes
• review against a base branch
• review a specific commit
• run custom review instructions

GitHub PR Review

After setting up Codex cloud and code review for a repository, you can request a review in a pull request:

@codex review

You can narrow focus:

@codex review for security regressions and missing edge-case tests

Codex can also fix a finding:

@codex fix the P1 issue

Review Guidance in AGENTS.md

Add a review section:

## Review guidelines

- Prioritize bugs, data loss, auth mistakes, and security regressions.
- Treat missing tests on shared logic as P1.
- Do not comment on style unless it changes behavior or maintainability.

Codex applies the closest relevant AGENTS.md to changed files.

---

Part 15: Noninteractive Mode and CI

Use codex exec when Codex needs to run from a script or pipeline.

Basic Usage

codex exec "summarize the repository structure and list the top 5 risky areas"

Allow edits:

codex exec --sandbox workspace-write "fix the failing unit test"

Read-only review:

codex exec --sandbox read-only "review this repository for migration risk"

JSONL Output

codex exec --json "summarize the repo structure" | jq

JSONL output can include thread events, command executions, file changes, MCP tool calls, web searches, plan updates, and final messages.

Structured Output

Use a JSON Schema when another system needs stable output:

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

Prompt Plus Stdin

Pass command output as context:

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix"

Use this for logs, CI output, HTTP traces, changelogs, and bug reports.

GitHub Action

Use openai/codex-action@v1 in GitHub Actions when you want Codex in CI/CD without hand-installing and authenticating the CLI.

Good use cases:

• PR review
• release-note generation
• CI failure triage
• migration checks
• patch generation

Security rules:

• limit who can trigger the workflow
• keep repository permissions narrow
• do not expose OPENAI_API_KEY to untrusted build steps
• run Codex late in the job
• save patches as artifacts before opening PRs from a separate permissioned job

---

Part 16: SDK Workflows

Use the Codex SDK when you want Codex inside your own server-side tooling.

TypeScript SDK

npm install @openai/codex-sdk

Example:

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

console.log(result);

Python SDK

pip install openai-codex

Example:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.4",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

Use SDKs for internal dashboards, release tooling, review bots, migration assistants, and systems that need to continue the same Codex thread across multiple runs.

---

Part 17: Image Inputs and Image Generation

Codex can use images as context.

Attach an image in the CLI:

codex --image screenshot.png "Explain the UI bug and suggest a fix"

Attach multiple images:

codex --image before.png,after.png "Compare these states and identify regressions"

Use image inputs for:

• UI screenshots
• failing browser states
• design mockups
• architecture diagrams
• error dialogs
• mobile simulator screenshots

Codex can also generate or edit images through built-in image generation in supported surfaces. This is useful for UI assets, banners, placeholders, sprite sheets, and reference illustrations.

---

Part 18: Importing from Claude Code

Codex includes an import path for supported Claude Code configuration, project files, and recent chats.

In the CLI:

/import

Use import when you already have:

• Claude Code instruction files
• MCP server configuration
• skills or subagents
• recent chats you want available in Codex

After import, review the generated files before relying on them. Different agents use different assumptions, so migration is a good time to simplify stale guidance.

---

Part 19: Practical Workflows

Workflow 1: Understand a New Repo

Read the repository and explain the architecture. Include the main entry points, important commands, data flow, risky areas, and the first three tasks a new developer should do.

Then ask:

Create an AGENTS.md draft from what you learned. Keep it short and include only commands and conventions Codex should follow every time.

Workflow 2: Fix a Bug Safely

Reproduce this bug from the failing test output below. Find the smallest fix, explain the root cause, update or add one focused test, and run only the relevant checks.

Workflow 3: Review Before a PR

Review my uncommitted changes against origin/main. Prioritize P0/P1 defects, missed edge cases, data-loss risk, and missing tests. Do not comment on style unless it affects behavior.

Workflow 4: Build a Feature

Implement [feature]. First inspect existing patterns and write a short plan. Then make the change, update tests, run the relevant checks, and summarize the diff.

Workflow 5: Frontend QA

Start the dev server, use the in-app browser to inspect the changed page, verify desktop and mobile states, fix visible layout issues, and include screenshots or a clear visual summary.

Workflow 6: Automate a Weekly Report

Create a weekly automation that checks this repo for merged PRs, failing checks, open release blockers, and dependency updates. Report only actionable findings.

Workflow 7: CI Failure Triage

gh run view 123456 --log \
  | codex exec "summarize the CI failure, identify the most likely root cause, and propose the smallest fix"

---

Part 20: Best Practices

Give Codex the Right Context

Name the relevant files, commands, errors, and constraints. If the task has a hidden business rule, state it.

Make "Done" Explicit

Tell Codex what must be true before it stops:

• tests pass
• lint passes
• build passes
• screenshot looks correct
• PR is ready
• docs are updated
• no unrelated files changed

Use Git Checkpoints

Codex can edit many files. Keep your working tree understandable:

git status
git diff
git add path/to/file
git commit -m "Implement focused change"

Keep Tasks Small

Codex can handle large work, but review quality improves when tasks are scoped. Split unrelated changes into separate threads, worktrees, or PRs.

Trust, But Verify

Always review:

• diffs
• generated commands
• test results
• dependency changes
• migrations
• security-sensitive code
• output files and screenshots

Turn Repetition into Configuration

If you repeat an instruction twice, consider adding it to:

• AGENTS.md for durable repo guidance
• a skill for a reusable workflow
• a hook for enforcement
• an MCP server for external context
• an automation for recurring work

---

Quick Reference

Daily Commands

codex
codex --sandbox read-only
codex --sandbox workspace-write --ask-for-approval on-request
codex resume --last
codex doctor
codex exec "summarize this repo"
codex review
codex mcp --help
codex completion zsh

Daily Slash Commands

/status
/permissions
/model
/plan
/review
/diff
/mcp
/skills
/hooks
/compact
/exit

Important Files

---

Frequently Asked Questions

Is OpenAI Codex free?

Every ChatGPT plan includes Codex according to the official quickstart. You can also use Codex with API credits by signing in with an OpenAI API key. Feature availability can differ between ChatGPT sign-in, API key sign-in, and Codex cloud.

How do I install Codex CLI?

On macOS or Linux, use the official standalone installer:

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

You can also install with:

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

Is Codex CLI the same as the Codex app?

They share the same Codex agent concepts and configuration, but the surfaces are different. The CLI is terminal-first; the app adds projects, threads, worktrees, automations, Git UI, browser tooling, computer use, and richer artifact previews.

Can Codex review GitHub pull requests?

Yes. After Codex cloud and code review are configured for a repository, you can request a review with @codex review in a pull request comment or enable automatic reviews.

Does Codex support MCP?

Yes. Codex supports MCP servers in the CLI and IDE extension, and the app shares the same MCP configuration. MCP is the standard way to connect Codex to tools such as documentation servers, Figma, GitHub, browser automation, Sentry, and internal systems.

Can Codex run in CI?

Yes. Use codex exec for noninteractive local runs or openai/codex-action@v1 in GitHub Actions. Keep credentials scoped to the Codex step and avoid exposing API keys to untrusted build steps.

How do I use Codex safely?

Start with read-only for planning and review, use workspace-write with on-request for normal development, and reserve full access for isolated environments. Review diffs, commands, dependency changes, migrations, and test results before shipping.

---

Official References

• Codex overview
• Codex quickstart
• Codex CLI
• Codex CLI command options
• Codex app features
• Codex IDE extension
• Codex cloud environments
• Agent approvals and security
• Config basics
• AGENTS.md guide
• Agent skills
• Model Context Protocol
• Hooks
• Automations
• Noninteractive mode
• Codex GitHub Action
• Codex SDK

---

Conclusion

Codex is best understood as a configurable software teammate. The CLI gives you terminal speed, the IDE extension gives you editor context, the app gives you coordination and local worktrees, cloud gives you isolated background execution, and automation surfaces let you wire Codex into repeatable engineering workflows.

Start simple: install Codex, sign in, run it in read-only mode, ask it to explain a repo, then move to workspace-write for a small bug fix. Once that loop works, add AGENTS.md, configure sandbox and approval defaults, connect MCP tools, package repeatable workflows as skills, and automate the stable parts of your development process.