Apr 21, 2026 · 5 min read

Last updated on Apr 19, 2026

Codex CLI Complete Guide: OpenAI's Terminal Coding Agent (2026)

Codex CLI is OpenAI’s terminal-based coding agent. Built in Rust, it reads your codebase, edits files, runs commands, and manages git workflows — all from the command line with OS-level sandboxing. It’s the OpenAI answer to Claude Code and Gemini CLI.

Since launching in April 2025, Codex has evolved into a multi-surface platform: terminal CLI, IDE extension, cloud environment, and mobile. This guide covers the CLI — the core developer experience.

Install

# Via npm (requires Node.js 18+)
npm install -g @openai/codex

# Authenticate with ChatGPT account
codex auth login

# Or use API key directly
export OPENAI_API_KEY=sk-...

# Set default model
codex config set model=gpt-5.4

Codex is built in Rust but distributed via npm. It runs on macOS, Linux, and Windows (via WSL2 or native PowerShell with experimental AppContainer sandbox).

Approval modes

The key concept in Codex: how much autonomy you give the agent.

Mode	What Codex can do	Best for
`--suggest`	Suggests changes, you approve each one	Learning, reviewing
`--auto-edit`	Edits files automatically, asks before commands	Daily coding
`--full-auto`	Edits files and runs commands without asking	CI/CD, automation

# Conservative: review everything
codex --suggest "Add input validation to the user registration endpoint"

# Balanced: auto-edit files, ask before shell commands
codex --auto-edit "Refactor the auth module to use JWT"

# Full autonomy: let it run
codex --full-auto "Fix all failing tests and commit"

Start with --suggest until you trust the agent with your codebase. Graduate to --auto-edit for daily work. Use --full-auto only for well-defined tasks in sandboxed environments.

Sandbox

Codex runs commands in an OS-level sandbox:

macOS: Seatbelt (App Sandbox)
Linux: Bubblewrap + Landlock/seccomp
Windows: AppContainer (experimental)

The sandbox prevents Codex from accessing files outside your project directory, making network calls you didn’t authorize, or modifying system files. This is a significant security advantage over Claude Code, which runs with full filesystem access.

For even stronger isolation, use the OpenAI Agents SDK with Docker or Cloudflare Sandboxes.

AGENTS.md

AGENTS.md is a project-level instruction file that tells Codex (and other AI tools) how to work with your codebase:

<!-- AGENTS.md in your project root -->
# Project: MyApp

## Tech Stack
- Next.js 15 with App Router
- TypeScript strict mode
- Prisma + PostgreSQL
- Tailwind CSS

## Conventions
- Use server components by default
- API routes in app/api/
- All database queries through Prisma
- Tests with Vitest, minimum 80% coverage

## Do NOT
- Modify the auth middleware without review
- Add new npm dependencies without justification
- Use any/unknown types in TypeScript

AGENTS.md works across tools — Codex, Cursor, Amp, and others read it. Write it once, every AI tool follows your project conventions.

MCP integration

Codex supports MCP for connecting to external tools and data sources:

# Add an MCP server
codex mcp add context7 -- npx -y @context7/mcp

# Add Playwright for browser testing
codex mcp add playwright -- npx -y @playwright/mcp

# List connected MCP servers
codex mcp list

This lets Codex access documentation, run browser tests, query databases, and interact with any tool that has an MCP server.

Models

Codex works with multiple OpenAI models:

Model	Context	Speed	Cost	Best for
gpt-5.4	1M	Medium	$2.50/$15 per 1M	Complex tasks, architecture
gpt-5.4-mini	400K	Fast	$0.75/$4.50 per 1M	Routine coding, subagents
o3	200K	Slow	$10/$40 per 1M	Deep reasoning
o4-mini	200K	Medium	$1.10/$4.40 per 1M	Reasoning on budget

# Switch models per task
codex --model gpt-5.4 "Redesign the database schema"
codex --model gpt-5.4-mini "Add JSDoc comments to all exported functions"

GPT-5.4 is recommended as the default. Use Mini for subagent work and routine tasks to save ~70% on costs. See our GPT-5 guide for detailed pricing.

Skills system

Skills are reusable capabilities you can install:

# Install a skill
codex skills install @openai/web-search
codex skills install @openai/code-review

# List installed skills
codex skills list

Skills extend what Codex can do without writing custom tools. They’re similar to Claude Code’s built-in capabilities but modular and installable.

Context management

Like Claude Code, Codex needs context management for long sessions:

# Compact the conversation (summarize and continue)
/compact

# Clear and start fresh
/clear

# Check context usage
/usage

GPT-5.4’s 1M context window is generous, but long sessions still accumulate tokens. Compact proactively — see our long-running agents guide for strategies.

Codex CLI vs Claude Code vs Gemini CLI

Feature	Codex CLI	Claude Code	Gemini CLI
Language	Rust	TypeScript	TypeScript
Sandbox	✅ OS-level	❌ Full access	❌ Full access
AGENTS.md	✅	✅	✅
MCP	✅	✅	✅
Approval modes	3 levels	Permission system	Permission system
Cloud automation	Via Agents SDK	✅ Routines	❌
Custom subagents	Via Agents SDK	Natural language	✅ Markdown files
Default model	GPT-5.4	Claude Sonnet	Gemini 2.5 Pro
Price	API usage	$20/mo or API	Free

Codex’s advantage is the sandbox — it’s the most secure option for autonomous code execution. Claude Code’s advantage is Routines for cloud automation. Gemini CLI’s advantage is being free.

See our detailed agent comparison for more.

Getting started

# Install
npm install -g @openai/codex

# Authenticate
codex auth login

# Try it on your project
cd your-project
codex --auto-edit "Explain this codebase and suggest improvements"

Start with --auto-edit on a git branch so you can easily revert. Once you’re comfortable, use it for real work.

FAQ

Is Codex CLI free?

Codex CLI itself is free and open source, but it requires an OpenAI API key and you pay for token usage. Costs depend on which model you use — GPT-5.4 runs $2.50/$15 per million tokens, while GPT-5.4 Mini is significantly cheaper at $0.75/$4.50 per million tokens.

How does Codex compare to Claude Code?

Codex CLI’s main advantage is its OS-level sandbox, which prevents the agent from accessing files outside your project or making unauthorized network calls — Claude Code runs with full filesystem access. Claude Code currently scores higher on coding benchmarks (SWE-bench) and offers Routines for cloud automation, while Codex integrates with the OpenAI Agents SDK for similar workflows.

Does Codex work offline?

No, Codex CLI requires an internet connection to communicate with OpenAI’s API for model inference. All code generation and reasoning happens server-side on OpenAI’s infrastructure. The sandbox and file operations run locally, but the AI brain is in the cloud.

Can I use Codex with local models?

Codex CLI is designed to work exclusively with OpenAI models and does not natively support local models or alternative API providers. If you need a terminal coding agent that works with local models, consider using Claude Code with a local Ollama backend or Aider, which supports any OpenAI-compatible endpoint.