| name | codex-consulting |
| description | Consult OpenAI Codex for fresh analytical perspective. Use when:
- Stuck after 3 failed attempts with identical errors (auto-escalation)
- Want a second opinion on a problem or approach
- Need web research on unfamiliar errors or technologies
<example>
Context: Claude has tried 3 different approaches to fix a TypeError but the same error persists
user: "I've been trying to fix this null pointer error for a while now"
assistant: "I've attempted three different fixes but the same error persists. Let me consult Codex for a fresh perspective."
<commentary>
Three failed attempts with identical error output indicates running in circles. Fresh analytical perspective from a different model may reveal blind spots.
</commentary>
</example>
<example>
Context: User wants a second opinion from a different model
user: "Ask Codex what it thinks about this approach"
assistant: "I'll consult Codex for an independent analysis of this approach."
<commentary>
User explicitly requests Codex consultation. No failure threshold needed for on-demand use.
</commentary>
</example>
<example>
Context: Unfamiliar error with an external dependency
user: "I keep getting this cryptic error from the SDK"
assistant: "Let me consult Codex — it can also search the web for recent information about this error."
<commentary>
Unfamiliar or cryptic errors benefit from web search capability and a second opinion.
</commentary>
</example>
Do NOT use for:
- Making progress (each attempt reveals new errors or reduces failures)
- First or second attempts at fixing an issue
- Questions that can be answered directly without a second opinion
|
| context | fork |
| agent | codex-integration:codex-escalation |
| allowed-tools | ["mcp__codex-cli__codex","mcp__codex-cli__websearch","mcp__codex-cli__ping","Read","Edit","Bash","Grep","Glob"] |
Codex Consultation Protocol
You are consulting OpenAI Codex for fresh analytical perspective. You were invoked either because the main Claude instance is stuck after three failed attempts, or because the user explicitly requested a second opinion.
Step 1: Pre-Flight Check
Verify the Codex MCP server is available:
mcp__codex-cli__ping({})
If ping succeeds: Proceed to Step 2.
If ping fails: Report and stop immediately:
Codex MCP server is not available.
This typically means:
1. Codex CLI is not installed (run: npm i -g @openai/codex)
2. Claude Code needs restart (required after plugin installation)
3. Authentication not configured (run: codex login)
4. OpenAI account lacks Codex access (requires ChatGPT Plus/Pro/Team)
Run /codex-check for detailed diagnostics.
Do NOT continue without a successful ping.
Step 2: Assess the Request
Determine the consultation mode:
Auto-escalation (stuck after 3+ failed attempts):
- Thorough context gathering required
- Use
reasoningEffort: "high" for deep analysis
- Follow the full protocol (Steps 3-7)
On-demand consultation (user asked for second opinion):
- Lighter context gathering
- Default reasoning effort
- Skip escalation tracking (Steps 6-7 optional)
Step 3: Gather Context
Codex has NO filesystem access. You must provide all relevant code and context.
Required Information
-
Problem description and goal
- What are you trying to accomplish?
- What is the expected outcome?
-
Attempt history (escalation mode)
- Summarize 3+ failed attempts with specific outcomes
- Include error messages, test failures, or unexpected behavior
-
Code context
- Use Read tool to gather relevant code snippets
- Include problematic code and related files
- Note file paths for all code
- Keep snippets focused but complete
-
Environment details (if relevant)
- Recent changes, dependencies, configuration
Step 4: Consult Codex
Format Your Prompt
Structure your prompt with clear sections. Keep it concise — Codex performs deep analysis automatically.
Stuck on: [ONE-LINE PROBLEM DESCRIPTION]
**Goal:** [Clear objective]
**Failed attempts (3x):**
1. [Approach] -> [Specific outcome/error]
2. [Approach] -> [Specific outcome/error]
3. [Approach] -> [Specific outcome/error]
**Error:**
[Full error message/stack trace]
**Code:**
File: [file-path]
[language]
[Minimal but complete relevant code]
**Environment:** [Only if relevant]
What's the root cause and how should I fix it?
For on-demand consultation, adapt the template — omit failed attempts if not applicable, focus on the question.
Call Codex
mcp__codex-cli__codex({
"prompt": "[Your structured prompt]",
"reasoningEffort": "high",
"sessionId": "escalation-[brief-topic]"
})
- Use
reasoningEffort: "high" for escalation, omit for on-demand
- Use
sessionId to enable multi-turn conversation
- Default model is
gpt-5.2-codex (optimized for coding, no need to override)
Multi-Turn Conversations
If Codex asks for clarification or more information:
- Gather the requested information using your tools (Read, Grep, Bash)
- Call
mcp__codex-cli__codex again with the same sessionId:
mcp__codex-cli__codex({
"prompt": "[Response with additional context]",
"sessionId": "escalation-[same-topic]"
})
Continue until Codex provides actionable recommendations.
Step 5: Research if Needed
Use web search for unfamiliar errors, dependencies, or APIs:
mcp__codex-cli__websearch({
"query": "[error message or technology question]",
"numResults": 10
})
Use when:
- Error messages reference unfamiliar libraries or APIs
- Codex suggests a solution involving tools you're not familiar with
- The problem might be a known issue with a recent update
Step 6: Implement and Verify
Validate the Recommendation
- Verify the diagnosis — Does Codex's root cause match all observed symptoms?
- Assess feasibility — Can this be implemented in the project context?
- Check blind spots — What project-specific constraints might Codex miss?
Implement
- You are the decision-maker; Codex provides recommendations
- Use your tools (Read, Edit, Bash) to implement, test, and verify
- Adapt the solution as needed based on project context
Verify
- Run relevant tests
- Verify the original error is resolved
- Check for new issues introduced
- Confirm the goal is achieved
Step 7: Second-Level Escalation
If still running in circles after 3 more implementation attempts, notify the user:
I consulted Codex and implemented their recommendations, but I'm still not making progress.
**Codex's diagnosis:**
[Root cause and solution Codex provided]
**Implementation attempts:**
1. [Approach based on Codex recommendation] — [outcome]
2. [Adjusted approach] — [outcome]
3. [Alternative approach] — [outcome]
Would you like me to:
- Try a completely different direction?
- Research alternative solutions?
- Pause and reassess the requirements?
Do NOT re-consult Codex infinitely. Wait for user guidance.
Output Format
When consultation is complete, provide a structured summary:
## Consultation Result
**Status:** [Resolved | Partially Resolved | Requires User Input]
**Root Cause Identified:**
[Summary of what Codex determined was the underlying issue]
**Solution Implemented:**
[Description of the fix, with file paths and key changes]
**Verification:**
- Tests: [Pass/Fail with details]
- Original error: [Resolved/Persists]
- New issues: [None/List any introduced]
**Remaining Concerns:**
[Any caveats, edge cases, or follow-up recommendations]
Recognition Patterns
DO escalate (running in circles):
Attempt 1: Add null check -> Error: "Cannot read property 'name' of null"
Attempt 2: Initialize object -> Error: "Cannot read property 'name' of null"
Attempt 3: Different null check -> Error: "Cannot read property 'name' of null"
DO NOT escalate (making progress):
Attempt 1: Fix syntax error -> New error: undefined variable
Attempt 2: Define variable -> New error: type mismatch
Attempt 3: Fix types -> Test passes
Common escalation scenarios:
- Same error after three different fix attempts
- Tests fail identically after three iterations
- Build/logic errors unresolved after three approaches
- Repeated timeouts/performance issues without improvement
