Overview
Codex CLI is OpenAI’s command-line AI coding assistant. ECC adapts its battle-tested workflows to work seamlessly with Codex’s architecture.What’s Included
| Component | Count | Details |
|---|---|---|
| Config | 1 | .codex/config.toml — model, permissions, MCP servers, persistent instructions |
| AGENTS.md | 2 | Root (universal) + .codex/AGENTS.md (Codex-specific supplement) |
| Skills | 16 | .agents/skills/ — SKILL.md + agents/openai.yaml per skill |
| MCP Servers | 4 | GitHub, Context7, Memory, Sequential Thinking (command-based) |
| Profiles | 2 | strict (read-only sandbox) and yolo (full auto-approve) |
Installation
Quick Install
Manual Setup
- Install Codex CLI:
- Copy configuration:
- Edit config.toml with your API key:
- Run in repository:
AGENTS.md at the repository root.
Configuration
config.toml Structure
Profiles
Codex supports multiple profiles for different workflows:- strict (Default)
- yolo
Read-only sandbox — Maximum safety
- Shell execution blocked
- File writes blocked
- Network access blocked
- User must approve each action
16 Ported Skills
Skills at.agents/skills/ are auto-loaded by Codex:
tdd-workflow
Test-driven development with 80%+ coverage requirement
security-review
Comprehensive security checklist (OWASP Top 10)
coding-standards
Universal coding standards (immutability, file organization)
frontend-patterns
React, Next.js, and modern frontend patterns
frontend-slides
HTML presentations, PPTX conversion, visual style exploration
article-writing
Long-form writing from notes and voice references
content-engine
Platform-native social content and repurposing
market-research
Source-attributed market and competitor research
investor-materials
Decks, memos, models, and one-pagers
investor-outreach
Personalized outreach, follow-ups, and intro blurbs
backend-patterns
API design, database, caching patterns
e2e-testing
Playwright E2E tests and Page Object Model
eval-harness
Evaluation-driven development
strategic-compact
Context management and compaction strategy
api-design
REST API design patterns, pagination, error responses
verification-loop
Build, test, lint, typecheck, security verification
Skill Format
Each skill has two files:Key Limitation: No Hooks Yet
Security enforcement is instruction-based via:- persistent_instructions in config.toml
- Sandbox permission system (block shell/file/network)
- Skill-embedded security rules
Workaround: Instruction-Based Security
config.toml
Usage Examples
Starting a Feature
TDD Workflow
Security Audit
MCP Server Configuration
Feature Comparison
| Feature | Claude Code | Codex CLI |
|---|---|---|
| Agents | 13 agents | Shared (AGENTS.md) |
| Commands | 33 commands | Instruction-based |
| Skills | 50+ skills | 16 ported skills |
| Hook Events | 8 types | None yet ⚠️ |
| Rules | 29 rules | Instruction-based |
| Custom Tools | Via hooks | N/A |
| MCP Servers | 14 servers | 4 servers |
| Config Format | settings.json | config.toml |
| Context File | CLAUDE.md + AGENTS.md | AGENTS.md |
| Secret Detection | Hook-based | Sandbox-based |
| Profiles | None | 2 profiles (strict/yolo) |
Codex Advantages: Profiles for different workflows, instruction-based security, OpenAI model access
Best Practices
Use Profiles
Switch between
strict and yolo based on taskEmbed Security
Add security rules to persistent_instructions
Leverage AGENTS.md
Keep project context in AGENTS.md at repo root
Test Skills
Invoke skills explicitly to verify behavior
Troubleshooting
Skills not loading
Skills not loading
- Check
.agents/skills/exists in repo - Verify each skill has SKILL.md and agents/openai.yaml
- Ensure YAML frontmatter is valid
- Run
codex --debugto see skill loading logs
AGENTS.md not detected
AGENTS.md not detected
- Place AGENTS.md at repository root (not in subdirectory)
- Ensure file is named exactly
AGENTS.md(case-sensitive) - Run Codex from repository root directory
- Check Codex logs for context loading
MCP servers failing
MCP servers failing
- Verify MCP server packages are installed globally
- Check environment variables (API keys, tokens)
- Test MCP server independently:
npx @modelcontextprotocol/server-github - Review Codex logs for connection errors
Permissions blocked
Permissions blocked
- Check current profile:
codex --profile - Switch to
yoloif you need auto-approve - Verify sandbox settings in config.toml
- Use
--allow-shell,--allow-writeflags for one-off overrides
Roadmap
Features coming to Codex CLI support:- Hooks support — Waiting on GitHub Issue #2109
- More skills — Additional 20+ skills from ECC library
- Custom tools — Once hooks are available
- Enhanced MCP configs — More servers (Supabase, Vercel, Railway)
Next Steps
Skills Library
Browse all 16 Codex-compatible skills
AGENTS.md Guide
Learn how to customize AGENTS.md
Security Guide
Instruction-based security patterns