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.