OpenAI Codex CLI
OpenAI Codex CLI (launched February 2026) is an open-source, terminal-based AI coding agent built in Rust. It competes directly with Claude Code and Kimi Code, offering unique features for developers who prioritize control, customization, and open-source auditability.
Codex CLI is released under the Apache 2.0 license. Source code available at github.com/openai/codex.
Key Differentiators
| Feature | Codex CLI | Claude Code | Kimi Code |
|---|---|---|---|
| License | Apache 2.0 (open-source) | Proprietary | Apache 2.0 |
| Runtime | Rust (fast, low memory) | Node.js | Node.js |
| Philosophy | Fine-grained control | Deep reasoning | Cost efficiency |
| Custom Commands | Yes (Markdown-defined) | No | Limited |
| Memory File | AGENTS.md | CLAUDE.md | N/A |
| Context Window | 128K tokens | 200K tokens | 256K tokens |
| Base Model | GPT-5-Codex | Claude 4.5 | Kimi K2.5 |
| Pricing | ChatGPT sub/API | $20-200/mo | $0.60/$2.50 per 1M |
Why Codex CLI Matters
With over 1 million developers using it within the first month of launch, Codex CLI represents a significant shift in the AI coding landscape. It combines OpenAI's latest code-optimized models with a privacy-first, locally-executed architecture.
Key advantages:
- Performance: Rust-based implementation delivers faster response times and lower memory usage
- Control: Three-level approval system (suggest, edit, full-auto) plus custom slash commands
- Transparency: Open-source codebase enables security audits and custom modifications
- Integration: Native support for Model Context Protocol (MCP) and tool orchestration
Installation
Prerequisites
- macOS 12+ or Linux (Windows support experimental)
- Node.js 18+ (for CLI wrapper)
- OpenAI API key or ChatGPT subscription
Quick Install
# Via npm
npm install -g @openai/codex
# Or download binary
curl -fsSL https://raw.githubusercontent.com/openai/codex/main/install.sh | bash
Authentication
# Set API key
codex auth login
# Or use environment variable
export OPENAI_API_KEY="sk-..."
Core Concepts
AGENTS.md
Similar to Claude Code's CLAUDE.md, Codex CLI uses AGENTS.md for project context:
# Project Agent Configuration
## Role
Senior full-stack developer specializing in TypeScript and React.
## Tech Stack
- Frontend: React 18, TypeScript, Tailwind CSS
- Backend: Node.js, Express, PostgreSQL
- Testing: Jest, React Testing Library
## Patterns
- Use functional components with hooks
- Prefer async/await over raw promises
- Follow RESTful API conventions
## Constraints
- Never expose database credentials
- Always validate user input
- Include error handling for all API calls
Place AGENTS.md in your project root. Codex CLI automatically loads it on startup.
Custom Slash Commands
Define custom commands in ~/.codex/commands/:
<!-- ~/.codex/commands/fix-tests.md -->
# Fix Tests
Run the test suite, identify failures, and fix them.
## Steps
1. Run `npm test` to identify failures
2. Analyze error messages and stack traces
3. Fix the underlying issues
4. Re-run tests to verify fixes
5. Report summary of changes
Usage:
codex /fix-tests
Approval Levels
Codex CLI operates in three permission modes:
| Level | Description | Use Case |
|---|---|---|
| Suggest | Shows proposed changes, requires manual application | Security-critical code |
| Edit | Automatically edits files, shows diff | Standard development |
| Full-Auto | Executes commands and edits without confirmation | Trusted workflows |
Configure in ~/.codex/config.json:
{
"approvalMode": "edit",
"allowedCommands": ["npm test", "npm run build"],
"blockedCommands": ["npm publish", "git push"]
}
Security & Governance
Sandboxing
Codex CLI implements defense-in-depth sandboxing:
- macOS: Apple Seatbelt (sandbox-exec) restricts filesystem and network access
- Linux: Landlock + seccomp-bpf for syscall filtering
- Network isolation: Blocks outbound connections by default (configurable)
Enterprise Controls
For AEEF compliance:
- Audit Logging: All actions logged to
~/.codex/audit.log - Policy Enforcement: Centralized config via
AGENTS.mdin version control - Secret Protection: Automatic detection of API keys, tokens in context
- Approval Gates: Required for production deployments
AEEF Alignment
PRD-STD-001: Prompt Engineering
Codex CLI supports structured prompting through:
AGENTS.mdfor persistent context- Custom slash commands for repeatable patterns
- Constraint specification in configuration
PRD-STD-002: Code Review
Integration options:
--diff-onlyflag for review-before-apply workflow- Git hooks for pre-commit validation
- CI/CD integration via
codex reviewcommand
PRD-STD-009: Autonomous Agent Governance
Codex CLI's approval system maps to AEEF's elicitation pattern:
- Auto-execute: Full-Auto mode with allowlisted commands
- Elicit: Edit mode with automatic application
- Approve: Suggest mode for human review
Best Practices
1. Start with AGENTS.md
Always create an AGENTS.md file before starting a project. This establishes context and constraints upfront.
2. Use Approval Levels Appropriately
# High-risk: manual review
codex --approval suggest "Refactor authentication module"
# Standard: auto-edit with diff
codex --approval edit "Add input validation"
# Trusted: full automation
codex --approval full-auto "Run tests and fix failures"
3. Define Custom Commands
Create reusable commands for common workflows:
# /refactor-legacy
Analyze legacy code and suggest modernization:
1. Identify deprecated patterns
2. Propose TypeScript conversions
3. Add missing type definitions
4. Update tests accordingly
4. Version Control Integration
# Stage changes before AI session
git add -A
# Run codex with auto-commit on success
codex --approval edit "Implement feature X" && git commit -m "feat: X (AI-assisted)"
5. Cost Management
Monitor token usage:
codex --dry-run "Complex refactoring" # Estimate cost
Comparison with Alternatives
Codex CLI vs Claude Code
| Aspect | Codex CLI | Claude Code |
|---|---|---|
| Setup | npm install, API key | npm install, auth |
| Philosophy | Control and customization | Deep reasoning and autonomy |
| Best For | Custom workflows, compliance | Complex logic, large refactors |
| Extensibility | High (custom commands) | Medium (CLAUDE.md only) |
| Open Source | Yes | No |
Codex CLI vs Kimi Code
| Aspect | Codex CLI | Kimi Code |
|---|---|---|
| Model | GPT-5-Codex | Kimi K2.5 |
| Context | 128K | 256K |
| Cost | Subscription/API | Per-token |
| Unique Feature | Custom commands | Agent Swarm |
| Best For | Control and auditability | Parallel execution, cost |
Troubleshooting
Common Issues
Issue: Commands fail with "permission denied"
Solution: Check sandbox permissions in ~/.codex/config.json
Issue: Context not loading from AGENTS.md Solution: Verify file is in project root, restart Codex CLI
Issue: Custom commands not recognized
Solution: Check ~/.codex/commands/ directory permissions
Performance Optimization
# For large codebases, use .codexignore
node_modules/
dist/
*.log
Resources
Related AEEF Resources
- Kimi Code Guide - Open-source terminal agent
- Kimi Code Guide - Open-source alternative
- PRD-STD-009: Agent Governance
- Free-Tier Comparison