consulting-codex

When to consult Codex (and how)

Every Codex turn costs tokens. Per the May 2026 rate card, a single gpt-5.4 call on autopilot averages 25–40k input + 5–10k output = $0.10–$0.30. Multiply by 30 iterations and a runaway loop is real money. This skill is the cost/value matrix for deciding "do I ask Codex, or do I just answer the user".

Don't consult Codex when

• The question is trivial — a typo fix, a one-line change, a rename. Just edit. The autopilot loop is for goals, not chores.
• The user asked a factual question about the repo — read the file yourself, don't burn a Codex turn paraphrasing.
• The answer is already in state.json — current_task, plan, last_review, last_verdict are local. Use /codex-status or /codex-next first.
• You'd be second-guessing a verdict — if the last review was approve and you want to "double-check", don't. The verdict is the contract.

Consult Codex (manager / architect role) when

Kind of question	Entry point
"Decompose this engineering goal into tasks."	codex-manager subagent → mcp__autopilot-bridge__plan
"Does this diff meet the current task's acceptance contract?"	codex-reviewer subagent → mcp__autopilot-bridge__review
"Is the goal achieved? If not, what next?"	Stop hook (automatic) → mcp__autopilot-bridge__verdict
"Should I use library X or Y for this?" (one-shot architectural)	codex-planner subagent (haiku, no state mutation)
"Re-plan from scratch — original plan exhausted but goal not met."	/codex-plan <revised goal>

How to ask well

Codex's prompts (in lib/prompts.mjs) embed:

• The user's goal
• CLAUDE.md, AGENTS.md, README head, repo listing
• Schema constraints (plan / review / verdict)

That's already enough for most calls. Don't add to the prompt unless you're sure — extra context is extra tokens, and Codex's role-specific prompts are tuned to deny shell / MCP / file I/O. Adding hints can break that framing.

Cost-aware patterns

• Use gpt-5.4 (default) for plan / review / verdict. gpt-5.5 is twice the price for marginal quality on these structured tasks.
• Use gpt-5.4-mini or haiku for codex-planner one-shot questions — they're $0.50/$2 per 1M tokens; an architectural opinion costs pennies.
• Set --budget USD on /autopilot to cap a session. The budget-guard.mjs check hook flips status to stopped_budget once spend ≥ cap. See safety-rails skill.

What Codex must NOT do

The bridge prompts explicitly forbid Codex from:

• Executing shell commands.
• Calling MCP tools.
• Reading or writing files via tools.

Codex's only output is the structured JSON for plan / review / verdict. If a Codex response includes shell commands or "I'll just run X" — that's prompt drift; the bridge's validateXxxShape will reject the output and the autopilot will surface a clean error to the user.

Conversation continuity

The bridge does not use codex-reply or --resume. Each call spawns a fresh codex exec process. Continuity is achieved by embedding state.json in the prompt — Codex sees the running plan, last_review, last_verdict, recent commits in every prompt. This trades token cost for reproducibility: every turn is replayable from the prompt log.