---
name: codex
description: >
  Delegate code generation to Codex CLI so Claude writes zero code itself.
  ALWAYS use this skill when the user asks to create, modify, fix, refactor,
  or test code — even if they don't mention Codex. Trigger on: implementing
  features, adding endpoints, writing services or classes, creating tests,
  fixing bugs, refactoring, migrating code, adding models or entities,
  writing fakers/fixtures, adding DI registrations, creating middleware.
  Trigger if the task would require Claude to write more than 5 lines of code.
  Do NOT trigger for: read-only exploration, explaining code, architecture
  discussions, git/commit/push/PR operations, running tests, checking config,
  listing files, Jira/ticket management, CI/CD debugging, or trivial one-liner edits.
---

# Codex Delegate — Claude Orchestrates, Codex Implements

Claude's output tokens are expensive. Every line of code Claude generates
costs ~5x more than it costs to read. The entire point of this skill is to
shift code generation to Codex (which runs on its own token budget) so Claude
spends its tokens only on thinking: planning, spotting gotchas, reviewing.

**Golden rule: Claude never writes code. Claude writes prompts for Codex.**

## When to Delegate vs. Handle Directly

**Delegate to Codex** when the task involves generating or editing code —
new files, classes, methods, tests, refactors, bug fixes, boilerplate.

**Handle directly** when no code generation is needed — reading files,
planning, discussing architecture, git operations, running commands,
trivial one-liner edits (a typo, a flag toggle, adding an import).

The threshold is low: if you'd write more than ~5 lines of code, delegate it.

## The Orchestration Loop

### 1. Minimal Context Gathering

Read just enough to write a good Codex prompt. Codex has full filesystem
access via `-C` and its own skills, so it can discover patterns on its own.

Only read files to:
- Identify the correct file paths to reference in the prompt
- Spot gotchas (e.g., a method name that differs from what the user assumed)

Don't read the codebase "just in case." If there's a CLAUDE.md, skim it.
If the user references a pattern file, glance at it to confirm the file
path exists and the key method names are what the user thinks.

### 2. Craft a Short Prompt

**Never include code in the prompt.** Point Codex to files and let it read
them. Codex has the project open — it will explore.

Good prompt (~50 tokens):
> Create src/Services/OrderService with a cancelOrder method.
> Follow src/Services/UserService patterns. Read the Order model for
> entity methods. Write tests first in tests/OrderServiceTests following
> tests/UserServiceTests structure.

Bad prompt (~300 tokens):
> Create OrderService. It must be a class with constructor taking
> a DatabaseClient and a Logger. Store them as private fields.
> The namespace is com.example.services. Add import for Entity
> from models. Add import for DatabaseClient from db...
> [50 more lines duplicating what's already in the reference file]

The short prompt works because Codex reads the existing service itself
and copies the patterns. Claude saves ~250 output tokens per prompt.

### 3. Execute via Codex CLI

**Always run codex exec in the foreground** — never in the background.
Set a generous timeout so the Bash call blocks until Codex finishes.

**Command template:**

```bash
codex exec \
  -m gpt-5.3-codex \
  --config model_reasoning_effort="high" \
  --full-auto \
  --skip-git-repo-check \
  -C "<project-directory>" \
  "<prompt>" \
  2>/dev/null
```

Use a Bash timeout of 120000ms (2 minutes) for simple tasks, 300000ms
(5 minutes) for complex multi-file tasks.

**Sandbox modes:**

| Task type | Flags |
|---|---|
| Write or edit files (default) | `--full-auto` |
| Analyze / review only | `-s read-only` |
| Need network or system access | `-s danger-full-access` (ask user first) |

**Rules:**
- Always `--config model_reasoning_effort="high"`.
- Always `--skip-git-repo-check` (WSL paths may confuse git detection).
- Always `2>/dev/null` to suppress thinking tokens from stderr.
- Always `-C` to point at the project root.
- Never `danger-full-access` without asking the user first.
- Use `--full-auto` for implementation tasks (the normal case).

### 4. Quick Review

After Codex finishes, verify the files were created/modified. Don't reread
and analyze the code Codex wrote — just check:

- The expected files exist (quick `ls` or `glob`)
- If tests were written, run them (the project's test command)

Keep the review to 1-2 sentences of output. If tests pass, the code is fine.
If they don't, send a follow-up to Codex.

### 5. Resume or Continue

To continue in the same Codex session:

```bash
echo "follow-up instructions" | codex exec --skip-git-repo-check resume --last 2>/dev/null
```

When resuming, don't repeat model/sandbox flags — the session inherits them.

### 6. Brief Report

Tell the user what was done in one sentence. Example:
"Codex created OrderService with cancelOrder + 5 tests, all passing."

Don't list what files were created, don't summarize the code, don't explain
the implementation. The user can read the diff.

## Iterative Development Pattern

For multi-step features, each Codex call is one focused task:

1. **Claude** skims context, plans approach (minimal output)
2. **Codex** writes tests first (TDD)
3. **Claude** runs tests (should fail — red)
4. **Codex** implements the code
5. **Claude** runs tests (should pass — green)
6. **Claude** reports one-liner to user

## Handling Codex Errors

If `codex exec` exits non-zero:
1. Remove `2>/dev/null` temporarily to see the error
2. Transient issue (network, timeout) → retry once
3. Config issue (wrong model, missing credentials) → tell the user
4. Bad code → send a corrective prompt to Codex

## What Codex Already Knows

Codex has its own skills and instructions configured. Don't repeat
language conventions or project patterns in the prompt — Codex will
apply them automatically. Just reference the relevant files by path.