Codex

Unified Codex Skill

One command to rule them all. Auto-detects project context, routes by intent, iterates until green.

Usage

/codex <natural language task>

Examples

/codex implement a rate limiter for the API
/codex fix the auth bug and add tests
/codex review the payment module for security issues
/codex refactor UserService to use repository pattern

Flags

Workflow

1. Load User Settings

Load settings from ~/.claude/codex-settings.toml (if exists):

python scripts/settings_loader.py --json

This returns user's preferred defaults, gate configuration, and profile definitions. If no settings file exists, sensible defaults are used.

2. Detect Project DNA

Run project detection (cached for session):

python scripts/project_dna.py --json

This returns framework, patterns, test commands, lint commands.

3. Analyze Intent

Run intent analysis on the user's prompt:

python scripts/task-analyzer.py "<user prompt>"

This returns JSON with:

• intent.type: generate, debug, review, refactor, test, or chain
• intent.steps: ordered list of operations (for chain type)
• complexity: 1-5 scale
• codex_params.profile: quick, standard, or deep
• codex_params.model: gpt-5.1-codex-mini, gpt-5.2-codex, or gpt-5.1-codex-max
• codex_params.model_reasoning_effort: low, medium, high, or xhigh

4. Route to Appropriate Agent

Based on intent type, route to the appropriate subagent:

For write operations (generate/debug/refactor/test): Use the Task tool to spawn a codex-coder agent:

Task tool with subagent_type: "codex-coder"

For read operations (review/analyze/audit): Use the Task tool to spawn a codex-reviewer agent:

Task tool with subagent_type: "codex-reviewer"

For direct execution (simple tasks or when agents unavailable): Continue with steps 5-7 below.

5. Build Enhanced Prompt

Combine DNA context with user's task:

PROJECT CONTEXT (auto-detected):
[DNA output here]

USER SETTINGS:
Model: [from settings or flag]
Reasoning: [from settings or flag]

TASK: [user's original prompt]

INSTRUCTIONS:
- Follow existing project patterns
- [Intent-specific instructions]

6. Execute with Model Escalation

Start with the model based on complexity and user settings:

User settings override these defaults. Flag overrides take highest priority.

Call Codex:

Use mcp__codex__codex with:
- prompt: [enhanced prompt]
- cwd: "."
- model: [from settings/analysis]
- sandbox: [from intent - workspace-write or read-only]
- approval-policy: "never"  (REQUIRED for MCP stdio)

If the response indicates struggle or failure, escalate to next model and retry.

7. Run Quality Gates (if write operation)

For generate/debug/refactor/test intents, run quality gates based on user settings:

# Check which gates are enabled
python scripts/settings_loader.py --gates --json

# Run enabled gates
python scripts/quality_gates.py --gate test --command "<test command>" --json
python scripts/quality_gates.py --gate lint --command "<lint command>" --fix "<fix command>" --json

If a gate fails:

1. Send error output back to Codex with fix request via mcp__codex__codex-reply
2. Codex attempts fix
3. Re-run gate
4. Max retries from user settings (default: 3 per gate, 10 total Codex calls)

8. Report Results

On success:

Complete: [summary of changes]
  - Files modified: [list]
  - Tests: passing
  - Lint: passing

On partial success:

Partially complete: [what was done]
  - Remaining issue: [what's failing]
  - Suggested fix: [recommendation]

Intent-Specific Instructions

generate

• Create new files following existing patterns
• Include appropriate tests
• Follow naming conventions from DNA

debug

• Analyze error context first
• Explain root cause before fixing
• Verify fix doesn't break other tests

review

• Read-only analysis
• Categorize findings by severity
• Suggest specific fixes

refactor

• Preserve all existing behavior
• Run tests frequently during refactor
• Make atomic, reviewable changes

test

• Follow existing test patterns
• Cover happy path, edge cases, errors
• Use appropriate mocking

Chain Execution

For prompts like "fix X and add tests":

1. Execute steps in order
2. Each step must pass before next
3. Share context between steps
4. Report progress after each step

Error Handling

Related Commands

Backward Compatibility

Old skills still work:

• /codex-delegate X -> redirects to /codex implement X
• /codex-review X -> redirects to /codex review X

Converted and distributed by TomeVault — claim your Tome and manage your conversions.