Ask Codex

Claude Code × Codex Collaboration Framework

Claude Code is the architect and coordinator; Codex is the autonomous implementer.

Core principle: Claude Code handles user interaction, scope control, product/architecture decisions, and final verification. Codex handles heavyweight codebase exploration, data inspection, implementation, and command execution. Default to Codex for repo-bound heavy lifting; keep Claude Code focused on judgment and synthesis. For anything that benefits from ongoing observation or mid-course correction, use the brokered session flow instead of one-shot execution.

Iron Laws

1. Route first — On receiving an implementation task, determine routing (self vs delegate vs split) before acting.
2. Review loop — Every Codex output must be verified by Claude Code (at minimum: read changed files). Never blindly trust results.
3. Self-contained context — Prompts sent to Codex must be fully self-contained. Never rely on "it should know."
4. Prefer session reuse — When corrections are needed, prefer --session to continue in the original session rather than starting fresh and losing context.
5. Never hide failures — When Codex fails, report honestly to the user with failure analysis. No silent retries.
6. Auto-offload heavy lifting — If a subtask is mostly repo/data exploration or verification work, prefer Codex by default instead of Claude Code or an internal lightweight/Haiku-style handoff.

Critical Rules

• Use ~/.claude/skills/ask-codex/scripts/ask_codex.sh for single-turn execution.
• Use ~/.claude/skills/ask-codex/scripts/codex_broker.sh for live collaboration, long tasks, review loops, or any task where Claude Code may want to inspect progress and send follow-up instructions before the whole effort is over.
• Do not call the codex CLI directly from the skill workflow (except codex exec review — see references/invocation.md).
• For one-shot ask_codex.sh runs: if it succeeds (exit code 0), read the output file. Don't re-run just because output seems short — Codex often works quietly.
• Quote file paths containing [, ], spaces, or special characters.
• Keep prompts focused on goals and constraints, not implementation steps. Aim for ~500 words max.
• Never paste file contents into the prompt. Use --file to point Codex to files.
• Never mention this skill or its configuration in the prompt.
• Require evidence, not assertions. End every prompt with a Verification: line that names a concrete command Codex must run and show output for (tests, reproduction, grep, etc.). Do not accept "tests pass" — demand the run. This is the single biggest driver of Codex success rate.

Prompt-design principles, templates, and anti-patterns live in references/prompt-engineering.md.

---

Phase 1: Smart Task Routing

After receiving a task, first determine the execution route. This is the entry logic for this framework.

Routing Decision Tree

Task received
  │
  ├─ User explicitly requested Codex?
  │    → Respect user intent, delegate directly (skip to Phase 2)
  │
  ├─ Heavy internal subtask? (repo sweep, data scan, log triage, broad search, impact analysis,
  │  evidence gathering, long verification run)
  │    → Delegate to Codex automatically (usually Mode 0 / read-only)
  │
  ├─ Analysis / planning / decision task?
  │    ├─ Mostly user-facing judgment? (architecture choice, trade-off discussion, requirements)
  │    │    → Claude Code handles it. Do not delegate.
  │    └─ Mostly evidence gathering from repo/data?
  │         → Delegate to Codex, then Claude Code synthesizes
  │
  ├─ Git / PR / deployment operation? (commit, push, PR, release)
  │    → Claude Code handles it. Codex lacks these tools.
  │
  ├─ Clear implementation task?
  │    ├─ Requirements clear + self-contained description + pure code/shell?
  │    │    ├─ User-visible execution choice matters?
  │    │    │    → Suggest delegating to Codex
  │    │    └─ Internal execution detail only?
  │    │         → Delegate to Codex automatically
  │    ├─ Requirements vague or need multi-turn user clarification?
  │    │    → Claude Code clarifies first, consider delegation after
  │    └─ Depends on current conversation context / transient state?
  │         → Claude Code handles it (context can't transfer to Codex)
  │
  └─ Review / verification task?
       → Choose cross-review mode based on source

Routing Criteria Quick Reference

| Criterion | → Claude Code | → Codex | |-----------|:---:|:---:| | Requires user interaction / confirmation | ✓ | | | Uncertain approach, multiple possibilities | ✓ | | | Involves git / PR / deployment | ✓ | | | Depends on current conversation context | ✓ | | | Heavy repo exploration across many files | | ✓ | | Data/log inspection and summarization | | ✓ | | Broad symbol/callsite/impact tracing | | ✓ | | Multi-command verification / reproduction | | ✓ | | Looks like an internal lightweight/Haiku subtask | | ✓ | | Clear requirements, well-defined goal | | ✓ | | Pure code read/write + shell operations | | ✓ | | Can be self-contained in \ --file

**Output on success:**

sessionid= outputpath=

Read `output_path` for Codex's response. Save `session_id` for follow-ups via `--session `.

**Common role flags:**

- `--read-only` → scout, reviewer, feasibility check
- `--reasoning high` → debugger, hard refactors
- `--session ` → continue a previous session (same role only; see `references/session-management.md`)
- `--timeout ` / `--idle-timeout ` → override defaults (600s / 180s)

### Brokered call

```bash
bash ~/.claude/skills/ask-codex/scripts/codex_broker.sh start "Goal description" \
  --file 
# then: status / send / wait / stop against the returned broker_id

Exit code handling (summary)

| Exit | Action | |------|--------| | 0 | Read output_path, continue normal flow | | 4 | Codex is asking a question — answer via --session (max 5 relay rounds) | | 3 | Fatal error (connection/auth/service) — report to user, offer takeover; do NOT auto-retry | | 2 | Timeout after one automatic grace window — report partial output + offer split/retry/takeover | | 1 / 137 | Codex error / OOM — simplify prompt or split task |

Full recovery decision tree, fast-fatal-error detection, review-loop failure handling, and takeover principles are in references/failure-recovery.md.

---

Red Flags — STOP

If you catch yourself thinking any of these, stop immediately:

• "Codex should understand what I mean" — No, the prompt must be self-contained and explicit.
• "The result looks roughly right" — No, you must read the changed files to verify.
• "Let's skip review this time, we're in a hurry" — No, the review loop is an Iron Law.
• "Let me just retry, it should work" — No, analyze the failure reason before choosing a strategy.
• "This is only exploration, I can just do it myself first" — No, heavy repo/data exploration should default to Codex.
• "This looks like a Haiku/background task" — Good. Route it to Codex unless it requires user-facing judgment.
• "Just delegate, no need to ask the user" — Only for internal heavy lifting or explicit user Codex requests.
• "Codex timed out earlier, so I should avoid delegating new work" — No, independent new tasks can start a fresh session.
• "Let me include all the details in the prompt" — No, 500 words max: goal + constraints + entry files.
• "One more review round should fix it" — 3-round cap. Beyond that, stop and analyze.
• "Codex can't do it, I'll take over" — Fine, but read Codex's partial output first.

---

References

Load these on demand when the task needs the detail:

• references/collaboration-modes.md — full diagrams, examples, constraints for Modes 0/A/B/C/D/E/F
• references/prompt-engineering.md — principles, templates by task type, anti-patterns, context transfer, verification gates
• references/session-management.md — role definitions, session lifecycle, timeout & new-task policy, resume limitations
• references/failure-recovery.md — exit codes, multi-turn relay protocol, recovery decision tree, takeover principles
• references/invocation.md — full options, codex exec review, integration with other skills

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bookSiYi1412
• Source: bookSiYi1412/ask-codex
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.