Codex

Codex Review & Second Opinion Skill

Use OpenAI's Codex CLI to get code reviews, plan evaluations, and second opinions. This provides an independent AI perspective using GPT-5.5 or o3 models.

When to Use This Skill

Trigger when user:

• Uses /codex command explicitly
• Asks for a "code review"
• Wants to "evaluate a plan" or "check my implementation plan"
• Wants a "second opinion" on code or approach
• Says "review this", "check this code", "validate this"
• Asks "what do you think about this implementation"
• Wants to "double check" code changes
• Requests "another perspective" on code

Prerequisites

Codex CLI must be installed and authenticated:

# Check installation
which codex

# Login if needed
codex login

Prompt Rules

Follow these when constructing Codex prompts. Better prompts beat higher reasoning effort.

1. Use XML-tagged prompt blocks — give Codex a ``, an output contract, and grounding rules instead of bare string instructions.
2. Don't be vague — "take a look at this" produces vague output. State what you want evaluated and what shape the answer should take.
3. Don't mix unrelated jobs — review in one run, fix in another, docs in a third. One clear task per Codex invocation.
4. Don't ask for "more reasoning" — tighten the output contract or add a `` instead of saying "think harder."
5. Separate facts from inferences — always include `` so Codex labels speculation explicitly.
6. Specify output shape — tell Codex exactly what sections to return. Structured output is easier to act on.

Guardrail

After presenting Codex findings, STOP. Do not make any code changes. Do not fix any issues. Ask the user which issues, if any, they want fixed before touching a single file. Auto-applying fixes from a review is strictly forbidden, even if the fix is obvious.

Workflow

Step 1: Determine What to Review

ALWAYS ask the user what they want reviewed:

Use AskUserQuestion to clarify:

1. Scope: What should be reviewed?

• Uncommitted changes (staged/unstaged)
• Specific file(s)
• Changes against a branch
• A specific commit
• An implementation plan
• General approach/implementation question

1. Model: Which model to use?

• gpt-5.5 - Fast, good quality (default)
• o3 - Deep analysis, complex reasoning (slower)

Step 2: Build the Prompt

Use the prompt templates below to construct a structured prompt. Pick the closest template, fill in the specifics, and trim anything unnecessary.

Step 3: Execute

IMPORTANT: Always use --sandbox workspace-write (NOT --full-auto, which is deprecated and triggers a warning).

CRITICAL: Pass the prompt as a direct string argument, NOT via heredoc or command substitution. Using $(cat filename.md)

Execution Modes

Mode 1: Review Uncommitted Changes

codex review --uncommitted -c model="MODEL"  **`codex review` flags differ from `codex exec`.** It sets the model via `-c model="…"` (no `-m`), is read-only (no `--sandbox`), and has no `-o` (redirect stdout to save). The scope flags (`--uncommitted` / `--base` / `--commit`) are **mutually exclusive with a custom prompt** — to add review focus, drop the scope flag and pass instructions as a prompt: `codex review -c model="MODEL" "Review the uncommitted changes, focusing on X" 
Evaluate this implementation plan against the codebase for feasibility, completeness, and risks.

Plan:
PLAN_CONTENT_HERE

Return:
1. feasibility issues (ordered by severity)
2. missing steps or edge cases
3. risks and tradeoffs
4. suggested improvements
5. open questions

Ground every claim in the repository context or tool outputs.
If a point is an inference, label it clearly.
Do not invent problems that are not supported by the codebase.

Before finalizing, verify that each concern is material and actionable, not speculative.

Code Review

Use for reviewing diffs, uncommitted changes, or specific files.

Review this change for material correctness and regression risks.
Focus areas: FOCUS_AREAS_HERE

Return:
1. findings ordered by severity
2. supporting evidence for each finding
3. brief next steps

Ground every claim in the repository context or tool outputs.
If a point is an inference, label it clearly.

Check for second-order failures, empty-state handling, retries, stale state, and rollback paths before finalizing.

Before finalizing, verify that each finding is material and actionable.

Architecture / Research Opinion

Use for "should we use X or Y" or "evaluate this approach" questions.

Research the available options and recommend the best path.
Context: CONTEXT_HERE

Return:
1. observed facts
2. reasoned recommendation
3. tradeoffs
4. open questions

Separate observed facts, reasoned inferences, and open questions.
Prefer breadth first, then go deeper only where the evidence changes the recommendation.

Back important claims with explicit references to the sources you inspected.
Prefer primary sources.

Diagnosis

Use when something is broken and you want Codex to find the root cause.

Diagnose why the failing test or command is breaking in this repository.
Failure: FAILURE_DESCRIPTION_HERE

Return:
1. most likely root cause
2. evidence
3. smallest safe next step

Keep going until you have enough evidence to identify the root cause confidently.
Only stop to ask questions when a missing detail changes correctness materially.

Before finalizing, verify that the proposed root cause matches the observed evidence.

Do not guess missing repository facts.
If required context is absent, state exactly what remains unknown.

Command Reference

Every command below appends `" " " " " review.md 2>&1

## Usage Examples

### Example 1: Evaluate Implementation Plan

User: Evaluate my plan for adding auth

Claude asks: Which model? What specific concerns? User: gpt-5.5, focus on security

Claude builds XML prompt with plan content, executes: codex exec --sandbox workspace-write -m gpt-5.5 -o codexreview20260111140000.md "" codexreview20260111140000.md

Reports findings. STOPS. Asks user what to fix.

### Example 3: Compare with Main

User: Review my feature branch against main

Claude executes: codex review --base main -c model="gpt-5.5" codexreviewfeature.md

Reports findings. STOPS. Asks user what to act on.

## Available Models

| Model | Best For | Speed |
|-------|----------|-------|
| `gpt-5.5` | General reviews, quick feedback | Fast |
| `o3` | Deep analysis, complex reasoning | Slower |

## AskUserQuestion Template

When triggered, ask:

Question 1: "What would you like Codex to evaluate?" Options:

• Uncommitted changes (git working tree)
• Changes against a branch
• Specific file(s)
• An implementation plan
• General question/second opinion

Question 2: "Which model should I use?" Options:

• gpt-5.5 (faster, default)
• o3 (more thorough)

## Error Handling

| Error | Solution |
|-------|----------|
| Not logged in | Run `codex login` |
| Not in git repo | Use `-C /path` or `--skip-git-repo-check` |
| Model not available | Fall back to `gpt-5.5` |
| Timeout | Try with smaller scope or faster model |
| Hangs / "Reading additional input from stdin" | Prompt was passed via heredoc or `$(cat ...)`. Pass it as a direct inline string argument instead. |
| Hangs silently with 0% CPU, 0-byte output, no error | Stdin not closed. Append ` " < /dev/null

Tips

1. Use XML prompt templates: Always use the structured templates above instead of bare string instructions
2. Be specific: Fill in the template placeholders with concrete context
3. One task per run: Don't mix review + fix + docs in a single invocation
4. Review incrementally: Review smaller changes more frequently
5. Always use --sandbox workspace-write: Prevents interactive confirmation prompts (--full-auto is deprecated)
6. Working directory: Codex needs to be run from the project directory
7. Never use heredocs for prompts: Pass prompts as direct string arguments. Heredocs ($(cat <<'EOF' ... EOF)) and command substitution cause Codex to hang waiting for stdin
8. Always close stdin with < /dev/null: Without it, codex hangs indefinitely (0% CPU, 0-byte output) when launched by an agent harness, especially in background mode. This is the single most common cause of "codex is stuck"

Limitations

• Requires internet connection and OpenAI API access
• Rate limits may apply
• Large codebases may need scoped reviews
• Cannot review files outside git repository by default

Source & license

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

• Author: letitbk
• Source: letitbk/claude-academic-setup
• License: MIT

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