| name | codex-rescue |
| description | When Claude is unavailable, hits a hard block, or repeatedly fails the same task, hand it to OpenAI Codex CLI with full vault context. Vault is plain markdown — model-portable. Use after 2+ failed attempts, on persistent API errors, or when the operator says "ask Codex". |
/codex-rescue
The vault is model-portable. If Claude can't finish, Codex can.
When to run
- Claude has attempted the same task ≥2 times and produced incorrect or incomplete output
- An Anthropic API error persists across retries
- Operator says "consult Codex", "second opinion", "ask Codex"
- A long investigation has stalled
Prerequisites
- Codex CLI installed:
npm install -g @openai/codex
OPENAI_API_KEY available (in .env or env)- Codex authenticated:
codex login
If anything missing, prompt the operator. Don't fail silently.
Phases
1. Capture state
Write system/intake/codex-rescue-{YYYY-MM-DD-HH-MM}.md:
---
type: source
source-kind: intake
date: 2026-04-26
processed: false
---
# Codex Rescue Brief
## What we're trying to do
{operator's most recent ask + the original task}
## What's been attempted
- {attempt 1: approach + outcome}
- {attempt 2: approach + outcome}
## Files touched
- {path 1} — {purpose}
## Where we got stuck
{specific failure mode, error message, or unanswered question}
## Success criteria
{operator's bar for "done"}
## Vault context
- Project: `{project-path}` (if applicable)
- Spec: `{spec-path}` (if applicable)
- Relevant rules: {list}
2. Hand off
Run Codex with the brief as context:
codex --cd $CLAUDE_PROJECT_DIR exec "$(cat system/intake/codex-rescue-...md)"
Or interactive:
codex --cd $CLAUDE_PROJECT_DIR
Stay in the loop — summarize Codex's output back into the conversation.
3. Verify
When Codex returns:
- Read the output. Does it meet success criteria?
- Run any tests, lint, or verification the spec requires.
- If good, apply it. If not, decide: another Codex iteration, escalate to operator, or back to Claude.
4. Log
The hook fires source-processed when the brief flips processed: true. Manual log entry not required.
Output
- Brief path
- Codex result, summarized
- Whether result was applied, and to which files
- Next action if Codex didn't resolve
What NOT to do
- Don't run Codex without writing the brief. Codex with no context is just another stuck model.
- Don't apply Codex output without reading it.
- Don't loop forever. After 2 Codex passes that don't resolve, escalate to operator.
- Don't strip vault context from the brief. Codex needs to see the rules and project state.
