OpenAI Codex CLI Complete Guide: Setup, Features, and Pro Tips (2026)

OpenAI Codex CLI has transformed how developers write, review, and ship code. Unlike ChatGPT's web interface, Codex CLI brings a powerful AI coding agent directly into your terminal, letting it read, edit, and run code on your machine. This comprehensive guide covers everything you need to get started with Codex CLI in 2026, from installation to advanced features like multi-agent workflows and the skills catalog.

What is OpenAI Codex CLI?

Codex CLI is OpenAI's local coding agent that runs directly from your terminal. Built in Rust for speed and efficiency, it's an open-source tool that can inspect your repository, edit files, run commands, and help you ship code faster.

Think of it as having an AI pair programmer that sits right in your terminal, understands your entire codebase, and can take action on your behalf. Unlike ChatGPT's web interface where you copy and paste code back and forth, Codex CLI works directly with your files.

How Codex CLI Differs from ChatGPT

Feature	Codex CLI	ChatGPT Web
Environment	Runs locally in your terminal	Browser-based interface
File Access	Direct read/write to your codebase	Copy/paste only
Command Execution	Can run terminal commands	Cannot execute code locally
Context	Full repository awareness	Limited to conversation
Workflow	Agentic, takes actions	Advisory, suggests code

Installation and Setup Guide

Getting Codex CLI running takes just a few minutes. Here's everything you need:

Prerequisites

• Node.js (includes npm) - version 18 or later recommended
• Git - for version control integration
• ChatGPT subscription - Plus, Pro, Team, Business, Edu, or Enterprise plan
• Operating System - macOS or Linux (Windows via WSL)

Step 1: Install Codex CLI

Choose your preferred package manager:

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

# Using Homebrew on macOS
brew install --cask codex

Step 2: Verify Installation

codex --version

Step 3: Authenticate

Run Codex for the first time and authenticate with your ChatGPT account:

codex

Select "Sign in with ChatGPT" when prompted. This opens your browser to complete authentication. Your credentials are stored locally for future sessions.

Step 4: Navigate to Your Project

For best results, run Codex inside a Git repository:

cd /path/to/your/project
codex

Pro Tip: Working in a Git repository allows you to easily revert any changes Codex makes using standard Git commands.

Key Features of Codex CLI

Codex CLI packs powerful features that make it more than a simple code generator. Here's what sets it apart:

1. Interactive Terminal UI

Launch with codex to open a full-screen terminal interface. You can:

• Send prompts and watch Codex explain its plan
• Approve or reject individual steps
• Attach screenshots for visual context
• Resume previous sessions with codex resume

2. Multi-Agent Workflows

One of the most powerful features in 2026 is multi-agent support. Codex CLI integrates with the OpenAI Agents SDK and Model Context Protocol (MCP) to enable:

• Parallel Work: Multiple agents can work on the same repository simultaneously using isolated worktrees
• Orchestration: Run Codex as an MCP server, allowing other agents to use it as part of larger pipelines
• Auditable Handoffs: Full traces of agent actions for review and accountability
• Scalability: From single-agent tasks to coordinated team efforts

3. Skills Catalog

Skills are folders of instructions, scripts, and resources that teach Codex specific capabilities. Built on the open Agent Skills standard, they're shareable across tools like Claude Code and GitHub Copilot.

Key skills features:

• Progressive Disclosure: Codex only loads skill details when needed, keeping context efficient
• Custom Skills: Create your own for team-specific workflows
• Multiple Scopes: Repository, user, admin, and system-level skills

Access skills by typing /skills or $ in the CLI. Use the built-in skill creator:

$skill-creator

4. Local Code Review

Get your code reviewed before committing with /review:

• Review against a base branch
• Review uncommitted changes
• Review specific commits
• Custom review instructions

5. Web Search Integration

Codex can search the web for up-to-date information while helping you code. Use --search for live results or let it use the cached web index.

6. Image Inputs

Attach screenshots or design specs directly:

codex -i screenshot.png "Explain this error"
codex --image design.png,mockup.jpg "Implement this UI"

7. Approval Modes

Control how much autonomy Codex has:

Mode	Description	Use Case
Auto	Read, edit, and run commands in working directory	Default for trusted projects
Read-only	Browse files only, no changes	Code exploration, learning
Full Access	Network and cross-machine access	Advanced automation (use carefully)

Pricing Breakdown

Codex CLI is included with ChatGPT subscriptions. Here's what each tier offers:

Plan	Cost	Local Messages/5h	Cloud Tasks/5h	Code Reviews/week
ChatGPT Plus	$20/month	45-225	10-60	10-25
ChatGPT Pro	$200/month	300-1500	50-400	100-250
ChatGPT Business	~$25/user/month	45-225	10-60	10-25
Enterprise/Edu	Custom	Scales with credits	Scales with credits	Scales with credits
API Key	Usage-based	Pay per token	Not available	Not available

Note: Usage varies based on task complexity. GPT-5.1-Codex-Mini offers up to 4x more usage for simpler tasks.

Credit System

When you hit limits, credits let you continue:

• Local tasks: ~5 credits per message (GPT-5.3-Codex), ~1 credit (GPT-5.1-Codex-Mini)
• Cloud tasks: ~25 credits per message
• Code review: ~25 credits per PR

Best Practices and Pro Tips

Get the most out of Codex CLI with these expert strategies:

1. Work in Git Repositories

Always run Codex in a Git-tracked directory. This lets you easily revert changes if something goes wrong:

git diff    # Review changes
git checkout .    # Revert all changes

2. Be Precise with Prompts

Clear, specific prompts yield better results:

# Less effective
codex "fix the bug"

# More effective
codex "Fix the null pointer exception in user-service.ts line 42 when processing empty arrays"

3. Use @ for File References

Reference specific files to focus Codex's attention:

@src/components/Button.tsx refactor this to use TypeScript generics

4. Optimize for Usage Limits

• Keep AGENTS.md files focused and concise
• Limit active MCP servers to what you need
• Switch to GPT-5.1-Codex-Mini for simple tasks
• Use /status to check remaining limits

5. Resume Sessions

Don't lose context between sessions:

codex resume --last    # Continue most recent session
codex resume    # Pick from recent sessions

6. Set Up Your Environment First

Before launching Codex, activate your environment:

source venv/bin/activate    # Python
nvm use 18    # Node.js
export API_KEY=xxx    # Environment variables
codex

7. Use Slash Commands

• /review - Code review workflow
• /skills - Browse available skills
• /model - Switch models mid-session
• /permissions - Change approval mode
• /exit - Close session

Common Issues and Solutions

Issue: "Command not found: codex"

Solution: Ensure npm global packages are in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(npm prefix -g)/bin"

Issue: Authentication Fails

Solutions:

• Clear cached credentials: rm -rf ~/.codex/auth
• Try codex login explicitly
• Ensure you have an active ChatGPT subscription

Issue: Codex Not Seeing Files

Solutions:

• Run from the correct directory: codex --cd /path/to/project
• Check .gitignore isn't excluding important files
• Use --add-dir to expose additional directories

Issue: Hitting Usage Limits Too Fast

Solutions:

• Switch to GPT-5.1-Codex-Mini for routine tasks
• Reduce context in AGENTS.md
• Disable unused MCP servers
• Purchase additional credits if needed

Issue: Slow Performance

Solutions:

• Work in smaller project directories
• Reduce the number of open files/tabs
• Check network connectivity
• Update to the latest version: npm i -g @openai/codex@latest

Issue: Windows Compatibility

Solution: Use WSL (Windows Subsystem for Linux) for the best experience. Follow the official Windows setup guide.

Codex CLI vs Alternatives

How does Codex CLI compare to other AI coding tools?

Tool	Type	Strengths	Best For
Codex CLI	Terminal Agent	Multi-agent, skills, local execution	Power users, automation
Claude Code	Terminal Agent	200K context, artifact support	Complex reasoning tasks
Cursor	IDE	VS Code fork, inline edits	IDE-centric workflow
GitHub Copilot	Extension	Tight GitHub integration	Autocomplete, suggestions

Getting Started Checklist

Ready to start using Codex CLI? Here's your quick checklist:

1. Install Node.js 18+ and Git
2. Run npm install -g @openai/codex
3. Verify with codex --version
4. Authenticate with codex
5. Navigate to a Git repository
6. Start coding with AI assistance!

Conclusion

OpenAI Codex CLI represents a significant leap forward in AI-assisted development. With multi-agent workflows, the extensible skills catalog, and deep terminal integration, it's built for developers who want an AI that can actually take action, not just suggest code.

Whether you're fixing bugs, implementing features, or reviewing code, Codex CLI streamlines your workflow while keeping you in control. Start with the ChatGPT Plus plan to explore the basics, then consider upgrading to Pro for heavy daily usage.

The key to success is treating Codex as a pair programmer: give it clear context, review its suggestions, and use Git to maintain control over your codebase. With practice, you'll find yourself shipping code faster than ever before.

Want to build AI-powered applications with your own API keys? Check out Serenities AI for a platform that lets you connect your existing AI subscriptions and build without vendor lock-in.