The Complete OpenAI Codex CLI Guide: Setup, Sandbox, AGENTS.md, and MCP

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

# Upgrade to latest
npm install -g @openai/codex@latest

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

codex login                     # Interactive OAuth (recommended)
codex login --device-auth       # OAuth device code flow (headless)
codex login --with-api-key      # API key from stdin
codex login status               # Check auth state (exit 0 = logged in)
codex logout                     # Clear stored credentials

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

codex --version
# codex-cli 0.133.0

npm i -g @openai/codex
codex login

cd ~/my-project   # Any git repo works

codex

> What does this project do? Summarize the architecture.

> Add input validation to the login endpoint

> /plan Refactor the database layer to use connection pooling

> /diff

codex                                    # Launch TUI
codex "fix the failing tests"            # Launch with initial prompt
codex -m gpt-5.5                         # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

codex app   # Launch desktop app (auto-installs if missing)

[profile.fast]
sandbox = "workspace-read"
ask_for_approval = "never"
model = "gpt-5.5"

[profile.careful]
sandbox = "workspace-write"
ask_for_approval = "always"
model = "gpt-5.4"

[profile.auto]
sandbox = "workspace-write"
ask_for_approval = "on-request"
model = "gpt-5.5"

codex --profile fast
codex --profile careful

codex --sandbox workspace-write
codex --sandbox workspace-read

codex --ask-for-approval always
codex --ask-for-approval never
codex --ask-for-approval on-request

How Does AGENTS.md Work?

AGENTS.md is a project-level file that defines operating contracts for AI coding agents. It works across Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed, and 60,000+ open source projects. Write once, use everywhere.

Creating AGENTS.md

Use /init in the TUI to generate an AGENTS.md scaffold:

> /init

This creates a template file in your project root. Edit it to include:

• Project overview and architecture
• Coding standards and conventions
• Testing requirements
• Deployment instructions
• Any other context the agent should know

Example AGENTS.md

# Project: MyApp

## Overview
MyApp is a REST API for managing user accounts.

## Architecture
- Express.js backend with PostgreSQL database
- React frontend with TypeScript
- Redis for caching

## Coding Standards
- Use async/await for all asynchronous operations
- Follow ESLint configuration in .eslintrc.js
- Write unit tests for all new functions

## Testing
- Run `npm test` before committing
- Maintain 80% code coverage

## Deployment
- Deploy to AWS ECS via GitHub Actions
- Run database migrations with `npm run migrate`

Best Practices

• Keep AGENTS.md concise and focused on what the agent needs to know.
• Update it as the project evolves.
• Use it to enforce team conventions without manual code reviews.

Hooks

Hooks allow you to run custom scripts at various points in the Codex lifecycle. They are defined in config.toml or per-project.

Available Hook Points

Hook	Trigger
pre_turn	Before each turn (prompt + response cycle)
post_turn	After each turn completes
pre_tool	Before a tool is executed
post_tool	After a tool completes
pre_approval	Before an approval prompt is shown
post_approval	After approval is granted or denied

Example Hook Configuration

[hooks.pre_turn]
command = "echo 'Starting turn'"

[hooks.post_turn]
command = "echo 'Turn completed'"

Use /hooks in the TUI (v0.129.0+) to browse and toggle lifecycle hooks without leaving the session.

What Is MCP (Model Context Protocol)?

MCP (Model Context Protocol) extends Codex capabilities to external services. It allows Codex to interact with APIs, databases, and other tools through a standardized protocol.

Configuring MCP Servers

MCP servers are configured in config.toml:

[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "your_token" }

[mcp.servers.figma]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-figma"]
env = { FIGMA_ACCESS_TOKEN = "your_token" }

[mcp.servers.sentry]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sentry"]
env = { SENTRY_AUTH_TOKEN = "your_token" }

Using MCP Tools

Once configured, MCP tools are available in the TUI. Use /mcp to list configured MCP tools. Codex can then invoke these tools during conversations.

MCP Improvements (v0.134.0+)

As of v0.134.0, MCP setup improved with per-server environment targeting and OAuth options for streamable HTTP servers. Connector tool schemas are more reliable by preserving local $ref/$defs and compacting oversized schemas. Read-only MCP tools can run concurrently when they advertise readOnlyHint.

Code Mode

Code mode is a specialized mode for focused coding tasks. It can call standalone web search directly (including from nested JavaScript tool calls) and receive plaintext results (v0.139.0+). Code mode remains experimental or under development as of v0.133.0.

JavaScript REPL Runtime

The JavaScript REPL runtime (js_repl) was removed as of v0.132.0. Use the shell or other tools for interactive JavaScript execution.

What Are Skills?

Skills package reusable domain expertise that Codex loads on demand. They allow you to encapsulate common workflows, patterns, and knowledge into shareable units.

Creating a Skill

Skills are defined in a directory structure:

~/.codex/skills/my-skill/
  skill.toml
  instructions.md
  examples/

Example skill.toml:

[skill]
name = "my-skill"
description = "Domain expertise for my project"
version = "1.0.0"

[instructions]
file = "instructions.md"

Using Skills

Use /skills in the TUI to access and invoke skills. Codex loads the skill instructions and applies them to the current context.

Skills System Improvements (v0.137.0+)

v0.137.0 shipped a v1 skills extension with per-turn catalog resolution, making skills more responsive and easier to manage.

Plugins

Plugins extend Codex functionality. They are managed through the plugin marketplace.

Plugin Marketplace Commands (v0.117.0+)

codex plugin marketplace list
codex plugin marketplace list --json   # v0.139.0+: exposes sources with faster cached-catalog listing
codex plugin install <name>
codex plugin uninstall <name>

Managing Plugins

Use /plugins in the TUI to browse and manage installed plugins. v0.129.0 adds workspace sharing and marketplace operations.

Plugin discovery (v0.133.0+) shows installed versions, marketplace roots, and remote collections.

Plan Mode and Collaboration

Plan mode allows Codex to create a plan without executing. This is useful for reviewing proposed changes before they are applied.

Entering Plan Mode

> /plan Refactor the database layer to use connection pooling

Codex creates a plan as a structured document. Review the plan, then approve to begin execution.

Collaboration Features

• Conversation forking: Branch conversations to explore alternatives without losing context.
• Goal mode (v0.128.0+): Create, pause, resume, or clear persisted work goals. As of v0.133.0, goals are enabled by default, backed by dedicated storage, and track progress across active turns.
• Memory system: Codex can remember preferences and context across sessions.

Memory System

Codex includes a memory system that allows it to remember preferences and context across sessions. This is managed through the /import command (v0.140.0+) which can selectively import setup, project configuration, and recent chats from Claude Code. v0.145.0 expands this to migrate from Cursor as well, including settings, MCP servers, plugins, sessions, commands, and project-scoped memories.

Session Management

Saving and Resuming Sessions

> /resume          # Resume a saved conversation
> /fork             # Fork current conversation into new thread
> /new              # Start new conversation in same session

Deleting Sessions

codex delete <session-id>   # Permanently delete a session (v0.140.0+)

Or use /delete in the TUI. Both have confirmation safeguards.

Session History Search (v0.134.0+)

Search across local conversation history with case-insensitive content matches and result previews.

Non-Interactive Mode (codex exec)

codex exec allows you to run Codex in non-interactive mode, suitable for automation and CI/CD pipelines.

Basic Usage

codex exec "fix the failing tests"
codex exec --output-schema json   # v0.132.0+: richer TurnResult

Resume with Output Schema (v0.132.0+)

codex exec resume --output-schema json

This allows you to resume a previous execution with structured output.

Codex Cloud and Background Tasks

Codex Cloud allows you to delegate long-running tasks to the cloud. This is useful for heavy refactoring, batch processing, or any operation that would tie up your local terminal.

Submitting a Cloud Task

codex cloud submit "Refactor the entire database layer"

Checking Task Status

codex cloud status <task-id>

Cloud tasks remain experimental or under development as of v0.133.0.

The Codex Desktop App

Launching

codex app   # Launch desktop app (auto-installs if missing)

Key Features

• Multi-tasking: Run multiple parallel agents across different projects simultaneously.
• Git worktree isolation: Each thread works on an isolated copy of your repo.
• Inline diff review: Stage, revert, and commit changes without leaving the app.
• Integrated terminal: Per-thread terminal for running commands.
• Conversation forking: Branch conversations to explore alternatives.
• Floating pop-out windows: Detach conversations into portable windows.
• Automations: Schedule recurring tasks (issue triage, CI monitoring, alert response).
• Appshots (v0.133.0+): Capture frontmost Mac windows for context.

GitHub Action and CI/CD

Codex can be integrated into GitHub Actions for automated code review, testing, and deployment.

Example GitHub Action

name: Codex Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Codex Review
        run: |
          npm install -g @openai/codex
          codex login --with-api-key <<< "${{ secrets.CODEX_API_KEY }}"
          codex exec "Review the changes in this PR"

Codex SDK

The Codex SDK (Python) provides programmatic access to Codex functionality.

Python SDK Features (v0.132.0+)

• First-class auth
• Simpler text-only turn APIs
• Richer TurnResult
• Friendly Sandbox presets for thread and turn APIs (v0.135.0+)

Example Python SDK Usage

from codex import Codex

client = Codex()
result = client.turn("What does this project do?")
print(result.text)

Performance Optimization

Context Management

• Use /compact to summarize conversation and free tokens.
• Use focused prompts to stay within context limits.
• Use @file references to attach specific files instead of entire directories.

Model Selection

• Use gpt-5.5 for most tasks (400K context, SOTA performance).
• Use gpt-5.6 Terra/Luna for lower-latency subagent work (272K context).
• Use gpt-5.3-codex for tasks that fit within 272K context.

Profile Selection

• Use fast profile for quick, read-only operations.
• Use careful profile for production codebases.
• Use auto profile for general development.

How Do I Debug Issues?

Codex Doctor (v0.131.0+)

codex doctor

This command reports richer environment, Git, terminal, app-server, and thread inventory (v0.135.0+). v0.139.0 adds editor and pager environment details (redacting sensitive values in JSON).

Common Issues and Solutions

Issue	Solution
Authentication failure	Run codex login again or check CODEX_API_KEY environment variable
Sandbox restrictions	Use --sandbox off (with caution) or adjust sandbox mode
Context window full	Use /compact or start a new session
Model not available	Check your subscription tier; some models require Plus/Pro
Slow performance	Use a faster model like gpt-5.6 Terra/Luna or reduce context size

Logs and Feedback

Use /feedback in the TUI to send logs to Codex maintainers for debugging.

Enterprise Deployment

Configuration Management

• Use config.toml for global settings.
• Use per-project AGENTS.md for project-specific instructions.
• Use profiles for team-wide configurations.

Security Considerations

• Enforce sandbox mode at the organizational level.
• Use API keys with restricted permissions for CI/CD.
• Audit token usage with /usage.

Amazon Bedrock Integration (v0.145.0, Experimental)

Teams whose model access runs through Amazon Bedrock get an experimental login path with custom endpoint and authentication support. GPT-5.6 Sol is the default Bedrock model.

Best Practices and Anti-Patterns

Do

• Write clear, specific prompts.
• Use AGENTS.md to define project conventions.
• Use profiles to match your workflow.
• Use /compact to manage context windows.
• Review diffs before approving changes.
• Use plan mode for complex changes.

Do Not

• Use --full-auto (deprecated).
• Run with --sandbox off in production.
• Ignore context window limits.
• Skip approval prompts on critical codebases.
• Use Codex for tasks better suited to other tools (e.g., simple text editing).

Workflow Recipes

Recipe 1: Daily Development

1. Start Codex in the project directory.
2. Use /plan to outline the day's tasks.
3. Execute tasks with approval prompts.
4. Use /diff to review changes.
5. Commit and push.

Recipe 2: Code Review

1. Start Codex in the PR branch.
2. Use /review to get a code review of the working tree.
3. Address issues.
4. Use /diff to verify changes.

Recipe 3: Debugging

1. Start Codex in the project directory.
2. Describe the bug.
3. Use @file to attach relevant files.
4. Let Codex analyze and propose fixes.
5. Review and apply fixes.

Migration Guide

Migrating from Claude Code

Use /import (v0.140.0+) to selectively import setup, project configuration, and recent chats from Claude Code. v0.145.0 expands this to migrate from Cursor as well, including settings, MCP servers, plugins, sessions, commands, and project-scoped memories.

Migrating from Cursor

Use /import (v0.145.0+) to migrate settings, MCP servers, plugins, sessions, commands, and project-scoped memories from Cursor.

Migrating from Other Tools

• GitHub Copilot: Set up AGENTS.md for project instructions.
• Aider: Configure MCP servers for external services.
• Windsurf: Use profiles to match your workflow.

Quick Reference Card

Installation

npm install -g @openai/codex
codex login

Basic Commands

codex                    # Launch TUI
codex exec "prompt"     # Non-interactive mode
codex app                # Launch desktop app
codex doctor             # Debug issues
codex --version          # Check version

TUI Shortcuts

Shortcut	Action
@	Attach file
!command	Run shell command
Ctrl+G	Open external editor
Ctrl+R	Reverse history search

Key Slash Commands

Command	Description
/plan	Enter plan mode
/diff	Show changes
/compact	Free tokens
/model	Switch model
/usage	Token usage
/import	Import from other tools

Changelog Highlights

• v0.145.0 (July 21, 2026): /import migrates from Cursor; voice returns as streaming realtime V3; multi-agent v2 stabilized; experimental Amazon Bedrock login; GPT-5.6 Terra/Luna variants.
• v0.144.6 (July 18, 2026): Corrected GPT-5.6 Sol/Terra/Luna context windows to 272,000 tokens.
• v0.140.0 (June 15, 2026): /usage shows token activity; /delete for session deletion; /import from Claude Code; unified @ mentions menu; Amazon Bedrock API-key authentication.
• v0.139.0 (June 9, 2026): Code mode web search; tool schema improvements; codex doctor enhancements; plugin marketplace JSON output.
• v0.138.0 (June 8, 2026): /app for desktop handoff; local image paths; reasoning-effort flexibility; encrypted sub-agent task text.
• v0.137.0 (June 4, 2026): Multi-agent v2; F13-F24 keybindings; v1 skills extension.
• v0.135.0 (May 28, 2026): codex doctor improvements; vim mode enhancements; Python SDK Sandbox presets.
• v0.134.0 (May 26, 2026): Session history search; --profile as primary selector; MCP improvements; read-only MCP tool concurrency.
• v0.133.0 (May 21, 2026): Goals enabled by default; permission profiles; plugin discovery; extension improvements.
• v0.132.0 (May 20, 2026): Python SDK auth; text-only turn APIs; codex exec resume --output-schema; js_repl removed.
• v0.131.0: codex doctor; unified @ mention search; marketplace CLI commands; daemon-managed remote-control.
• v0.129.0: Vim mode; hooks TUI; workflow picker redesign; raw scrollback mode.
• v0.128.0: Goal mode.
• v0.121.0: Reverse history search; context-percent indicator.
• v0.117.0: Plugin management; /title command.
• v0.106.0: Direct install script.
• v0.100.0: Windows sandbox promoted from experimental.

Going Further

To deepen your Codex expertise, explore these areas from the source material:

• Multi-Agent v2: v0.137.0 shipped multi-agent v2 with runtime kept per thread, cleaner follow-up and metadata defaults, and hide_spawn_agent_metadata default true. v0.145.0 stabilized the opt-in multi-agent v2 experience with configurable sub-agent models, reasoning levels, and concurrency. This allows you to delegate sub-tasks to specialized agents.
• Extension System: Extensions can observe subagent start/stop, tool execution, turn metadata, and async approval/turn processing (v0.133.0+). Build custom extensions to integrate Codex into your workflow.
• Remote Control: codex remote-control (v0.133.0+) got foreground readiness/status plus daemon-style start/stop. Useful for running Codex on a remote server.
• Appshots (v0.133.0+): Capture frontmost Mac windows for context. Useful for debugging UI issues.
• Computer Use (v0.133.0+): Opt-in locked Computer Use for eligible Mac users. Allows Codex to interact with your desktop.
• Browser Annotation: In-app browser annotation improvements (v0.133.0+). Useful for web scraping and testing.
• Amazon Bedrock: For teams using AWS, explore the experimental Amazon Bedrock login path with custom endpoint and authentication support (v0.145.0).
• Open Source Community: AGENTS.md works across 60,000+ open source projects. Contribute your own AGENTS.md to projects you use.