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