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

ComponentCountDetails
Config1.codex/config.toml — model, permissions, MCP servers, persistent instructions
AGENTS.md2Root (universal) + .codex/AGENTS.md (Codex-specific supplement)
Skills16.agents/skills/ — SKILL.md + agents/openai.yaml per skill
MCP Servers4GitHub, Context7, Memory, Sequential Thinking (command-based)
Profiles2strict (read-only sandbox) and yolo (full auto-approve)

Installation

Quick Install

# Copy the reference config to your home directory
cp .codex/config.toml ~/.codex/config.toml

# Run Codex in the repo — AGENTS.md is auto-detected
codex

Manual Setup

  1. Install Codex CLI:
pip install openai-codex
  1. Copy configuration:
cp .codex/config.toml ~/.codex/config.toml
  1. Edit config.toml with your API key:
[auth]
api_key = "sk-YOUR-OPENAI-API-KEY"
  1. Run in repository:
cd /path/to/everything-claude-code
codex
Codex automatically detects AGENTS.md at the repository root.

Configuration

config.toml Structure

[model]
name = "gpt-4.6-turbo"  # or gpt-4, gpt-4.6, etc.
temperature = 0.7
max_tokens = 10000

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:
codex --profile strict
codex --profile yolo

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:
---
name: tdd-workflow
description: Test-driven development methodology
model: gpt-4.6-turbo
temperature: 0.7
---

# TDD Workflow

## Process

1. **RED** — Write a failing test
2. **GREEN** — Write minimal code to pass
3. **REFACTOR** — Improve code quality
4. **VERIFY** — Check 80%+ coverage

## Example

```typescript
// 1. RED - Write failing test
test('authenticates user', () => {
  const result = authenticateUser('[email protected]', 'password');
  expect(result.success).toBe(true);
});

// 2. GREEN - Minimal implementation
function authenticateUser(email: string, password: string) {
  return { success: true };
}

// 3. REFACTOR - Add real logic
function authenticateUser(email: string, password: string) {
  const user = db.findByEmail(email);
  if (!user || !bcrypt.compare(password, user.passwordHash)) {
    return { success: false, error: 'Invalid credentials' };
  }
  return { success: true, user };
}

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
[persistent_instructions]
instructions = """
SECURITY RULES (CRITICAL - NEVER OVERRIDE):

1. No hardcoded secrets (API keys, passwords, tokens)
2. All user inputs must be validated
3. Use parameterized queries (no SQL injection)
4. Sanitize HTML output (no XSS)
5. Enable CSRF protection
6. Rate limiting on all endpoints
7. Error messages must not leak sensitive data

Before ANY commit:
- security-review skill must be invoked
- All CRITICAL/HIGH issues must be fixed
- No exceptions
"""

Usage Examples

Starting a Feature

codex

# Codex auto-loads AGENTS.md from repo root
> "Plan authentication with OAuth using the planner workflow"
# → Uses planner skill to create blueprint

> "Implement with TDD"
# → Uses tdd-workflow skill to enforce write-tests-first

> "Security review"
# → Uses security-review skill to audit changes

TDD Workflow

> "Add password reset feature using TDD"

# Codex follows TDD workflow:
1. Writes failing test
2. Implements minimal code
3. Refactors for quality
4. Verifies coverage

Security Audit

> "Review authentication code for security issues"

# Codex uses security-review skill:
# - Checks for SQL injection
# - Verifies input validation
# - Audits authentication logic
# - Reports findings with severity

MCP Server Configuration

[[mcp_servers]]
name = "github"
command = "npx"
args = ["@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_YOUR_TOKEN" }

Feature Comparison

FeatureClaude CodeCodex CLI
Agents13 agentsShared (AGENTS.md)
Commands33 commandsInstruction-based
Skills50+ skills16 ported skills
Hook Events8 typesNone yet ⚠️
Rules29 rulesInstruction-based
Custom ToolsVia hooksN/A
MCP Servers14 servers4 servers
Config Formatsettings.jsonconfig.toml
Context FileCLAUDE.md + AGENTS.mdAGENTS.md
Secret DetectionHook-basedSandbox-based
ProfilesNone2 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 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