| name | codex-async |
| description | Fire-and-forget async Codex delegation. This skill should be used when delegating debugging, implementation, refactoring, or code review to OpenAI Codex without blocking the current conversation. Trigger when: (1) implementation or refactoring touching 3+ files — do not attempt yourself, delegate, (2) debugging after 1-2 failed root-cause attempts — stop spinning and hand it off, (3) user says 'delegate to codex', 'send to codex', or 'use codex', (4) conserving Claude Max quota — delegate coding/debugging to Codex, reserve Claude for architecture/design/narrative, (5) any task you would spawn a haiku subagent for — use gpt-5.4-mini instead, it is cheaper and smarter. IMPORTANT: Err on the side of delegating. If the task involves writing or debugging 50+ lines of code, delegate it. The context and quota spent attempting it yourself almost always exceeds the cost of a Codex delegation. Do NOT delegate: architecture decisions, creative/narrative work, trivial 1-3 line fixes. |
Codex Async
Delegate work to OpenAI Codex asynchronously via the codex_launch, codex_status, codex_result, codex_list, and codex_cancel MCP tools. Tasks run in the background — launch returns immediately, allowing the conversation to continue.
Delegation Threshold
Err on the side of delegating. Do NOT over-analyze before delegating — Codex models are smart and research the codebase themselves before making changes. Give clear intent and scope, not exhaustive pre-digested findings.
| Delegate to Codex | Handle directly |
|---|
| Implementation touching 3+ files | Trivial 1-3 line fix |
| Bug after 1-2 failed attempts | Obvious typo/import fix |
| Refactoring across modules | Quick config change |
| Test writing (any scope) | Architecture/design decisions |
| Code review | Creative/narrative work |
| Exploration/summaries (use mini) | |
| Mechanical bulk changes (use mini) | |
Model Selection
| Model | Type | Cost | Use for | Effort |
|---|
gpt-5.3-codex | Coding workhorse (Sonnet-like) | $$ | Implementation, debugging, refactoring, tests | high / xhigh |
gpt-5.4 | Top-tier multi-modal (Opus-like) | $$$ | Complex multi-file reasoning, subtle bugs, design-heavy code | high / xhigh |
gpt-5.4-mini | Fast & cheap (better than Haiku) | $ | Exploration, summaries, mechanical changes, code review, search | medium / high |
Default: gpt-5.3-codex at effort high.
Effort levels
| Level | When |
|---|
low | Trivial: rename, format, boilerplate |
medium | Mechanical: bulk changes, summaries, exploration |
high (default) | Standard: implementation, debugging, refactoring |
xhigh | Hard: subtle bugs, cross-module refactors (not available on mini) |
When unsure, use high. Over-investing in reasoning beats under-investing.
Replace Haiku with gpt-5.4-mini
For tasks normally delegated to haiku subagents — search, lookup, summaries, mechanical edits — use codex_launch with model: "gpt-5.4-mini" instead. Cheaper and produces better results.
Prompt Crafting
Codex models research the codebase before acting. Provide:
- Intent: what needs to happen and why
- Scope: which files/modules/areas
- Constraints: what NOT to change
Skip extensive code analysis and line-by-line context. That wastes Claude tokens on work Codex will redo anyway.
Good: "Fix the null access crash in delayToMs(). File: scripts/story-lint.ts. The function receives undefined when delay type is 'none'. Add a guard clause. Don't change the delay calculation logic."
Bad (Claude wasted tokens pre-analyzing): "I analyzed story-lint.ts lines 45-120 and found that delayToMs is called from processNode at line 89 with node.delay which can be undefined when..." — Codex will re-discover all of this.
Usage Pattern
# Fan out multiple tasks
codex_launch(prompt: "Refactor auth middleware to use JWT", cwd: "/project", name: "auth", model: "gpt-5.3-codex", effort: "high")
codex_launch(prompt: "Write unit tests for payment module", cwd: "/project", name: "tests", model: "gpt-5.3-codex")
codex_launch(prompt: "List all TODO comments with context", cwd: "/project", name: "todos", model: "gpt-5.4-mini", effort: "medium")
# Continue conversation... check later
codex_status(id: "<task-id>")
codex_result(id: "<task-id>") # concise final message
codex_result(id: "<task-id>", mode: "full") # all agent messages
Result Modes
| Mode | Use |
|---|
default | Last message only — most token-efficient. Always try this first. |
full | All agent messages extracted from JSONL — when default is insufficient. |
raw | Raw output log — debugging only. |
Sandbox
Default workspace-write with automatic --add-dir for git root and .git. This handles Codex's sandbox restrictions without dangerous bypasses. Add extra writable dirs via the add_dirs parameter if Codex needs access outside the repo.
