# Codex Async

> 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.

- Skill: `edimuj/codex-async` (Agent Skill)
- Install (CLI): `npx skillmds@latest add edimuj/codex-async`
- Raw SKILL.md: https://api.skillmd.com/api/skills/edimuj/codex-async/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: edimuj (https://skillmd.com/u/edimuj)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/edimuj/codex-async

---


# 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.