Codex Consult

Arguments

Usage Instructions

Basic Consultation (Plan Mode)

To consult Codex for implementation planning:

1. Execute the wrapper script with task description:

   bash ${CLAUDE_PLUGIN_ROOT}/scripts/codex-exec.sh "Implement user authentication with JWT"
   

2. Read the output from /tmp/codex-consult.last.md

3. If output is empty or error occurs, check /tmp/codex-consult.run.log

Patch Mode Consultation

To get concrete code change suggestions:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/codex-exec.sh --mode=patch "Refactor the database connection to use connection pooling"

Custom Model

To use a different model:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/codex-exec.sh --model=o4-mini "Design the caching layer"

Scoped Analysis

To analyze a specific directory:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/codex-exec.sh --scope=/path/to/src "Review error handling patterns"

Disable Web Search

To run without web search:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/codex-exec.sh --no-web "Analyze this legacy code"

Output Interpretation

Summary Section

• What changes are proposed
• Assumptions and preconditions
• Impact analysis

Changes Section (Patch Mode)

• Unified diff format
• File-by-file breakdown
• Explanation of each change

Verification Section

• Test commands to run
• Manual verification steps
• Edge cases to check

Best Practices

1. Be specific: Provide clear task descriptions with context
2. Always specify --scope explicitly: Use --scope=$(pwd) or --scope=/absolute/path/to/project to ensure Codex analyzes the correct project context. This is especially important in multi-repository environments.
3. Start with plan mode: Use plan mode first, then patch mode if needed
4. Verify suggestions: Always review Codex output before applying changes
5. Consider execution time: Complex analyses may take longer. Avoid running as background tasks with strict timeouts.

Caveats

Scope Resolution in Multi-Repository Environments

When working in directories that contain multiple git repositories (e.g., nested subprojects or monorepos), Codex may analyze the wrong project context if --scope is not explicitly specified.

Problem scenario:

/home/user/projects/
├── main-project/
│   └── submodules/
│       └── other-repo/      ← Codex may analyze this instead
└── .git/

Solution: Always use explicit --scope parameter:

# From any directory, specify the target project explicitly
bash ${CLAUDE_PLUGIN_ROOT}/scripts/codex-exec.sh --scope=/home/user/projects/main-project "Analyze the codebase"

# Or use $(pwd) to ensure current directory is used
bash ${CLAUDE_PLUGIN_ROOT}/scripts/codex-exec.sh --scope=$(pwd) "Analyze the codebase"

Timeout Considerations

Codex CLI may encounter timeout failures (exit code 144) in the following scenarios:

1. Background task execution: Running as a background process with strict timeout limits
2. Complex analysis requests: Large codebases or architecturally complex queries requiring extended reasoning
3. Network latency: Slow connections can cause API timeouts

Recommendations:

• Set timeout to at least 10 minutes (600 seconds): Complex analyses require extended processing time. Shorter timeouts will likely cause failures.
• Run Codex consultations in the foreground when possible
• Break down complex queries into smaller, focused questions
• For large codebases, use --scope to limit the analysis scope
• Check /tmp/codex-consult.run.log for timeout-related errors

Error Handling

If Codex execution fails:

1. Check /tmp/codex-consult.run.log for error details
2. Verify Codex CLI is authenticated (codex login)
3. Check network connectivity
4. Try with a different model if quota exceeded

Additional Resources

Reference Files

• references/codex-cli-reference.md - Codex CLI commands and options
• references/output-format.md - Output format specification

Examples

• examples/sample-consultation.md - Sample consultation outputs