Skip to main content
Everything Claude Code provides first-class Codex CLI support with a reference configuration, Codex-specific AGENTS.md supplement, and 16 ported skills.

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

Installation

Quick Install

Manual Setup

  1. Install Codex CLI:
  1. Copy configuration:
  1. Edit config.toml with your API key:
  1. Run in repository:
Codex automatically detects AGENTS.md at the repository root.

Configuration

config.toml Structure

Profiles

Codex supports multiple profiles for different workflows:
Read-only sandbox — Maximum safety
  • Shell execution blocked
  • File writes blocked
  • Network access blocked
  • User must approve each action
Best for: Code review, exploration, learning
Switch profiles:

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

Codex CLI does not yet support hooks (GitHub Issue #2109, 430+ upvotes).
Security enforcement is instruction-based via:
  1. persistent_instructions in config.toml
  2. Sandbox permission system (block shell/file/network)
  3. Skill-embedded security rules

Workaround: Instruction-Based Security

config.toml

Usage Examples

Starting a Feature

TDD Workflow

Security Audit

MCP Server Configuration

Feature Comparison

Codex Advantages: Profiles for different workflows, instruction-based security, OpenAI model access

Best Practices

Use Profiles

Switch between strict and yolo based on task

Embed 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

  1. Check .agents/skills/ exists in repo
  2. Verify each skill has SKILL.md and agents/openai.yaml
  3. Ensure YAML frontmatter is valid
  4. Run codex --debug to see skill loading logs
  1. Place AGENTS.md at repository root (not in subdirectory)
  2. Ensure file is named exactly AGENTS.md (case-sensitive)
  3. Run Codex from repository root directory
  4. Check Codex logs for context loading
  1. Verify MCP server packages are installed globally
  2. Check environment variables (API keys, tokens)
  3. Test MCP server independently: npx @modelcontextprotocol/server-github
  4. Review Codex logs for connection errors
  1. Check current profile: codex --profile
  2. Switch to yolo if you need auto-approve
  3. Verify sandbox settings in config.toml
  4. Use --allow-shell, --allow-write flags 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