Skip to content

notque/vexjoy-agent / skills/process/pr-workflow

pr-workflow

Flagged

Pull request lifecycle: commit, codex review, sync, review, fix, status, cleanup, and PR mining. Use when user wants to commit changes, get a second-opinion code review from Codex, push changes, create a PR, check PR status, fix review comments, clean up branches after merge, or mine tribal knowledge from PR reviews. Use for "commit my changes", "codex review", "push my changes", "create a PR", "pr status", "fix PR comments", "clean up branches", "mine PRs", or "address feedback".

references/codex-review-cli-patterns.md

View on GitHub
# Codex CLI Patterns

> **Scope**: `codex exec` command variants, flags, and error recovery for code review invocations.
> **Cross-provider note**: Under Claude Code this is an explicit cross-provider second-opinion tool, never the automatic default.
> **Version range**: @openai/codex with the GPT-5.6 Sol review lane available
> **Generated**: 2026-04-16

---

## Overview

The Codex CLI runs GPT models in a sandboxed environment with direct filesystem access.
For code review, the key pattern is `codex exec review` (built-in review subcommand) or
`codex exec` with a custom prompt. The CLI manages its own git context — embedding diffs
wastes tokens and hits prompt-length limits.

---

## Command Pattern Table

| Use Case | Command Variant | Key Flags |
|----------|----------------|-----------|
| Branch review vs main | `codex exec review --base main` | `--base <branch>` |
| Single commit review | `codex exec review --commit <SHA>` | `--commit <SHA>` |
| Unstaged changes only | `codex exec review --uncommitted` | `--uncommitted` |
| Custom focus areas | `codex exec "YOUR PROMPT"` | no `--base/--commit` |
| High-risk review | add to any | `-m gpt-5.6-sol -c 'model_reasoning_effort="xhigh"'` |
| Exceptional maximum-power escalation | explicit override only | `-m gpt-5.6-sol -c 'model_reasoning_effort="max"'` |
| Capture output | add to any | `-o "$TMPFILE"` |
| One-shot (no persist) | add to any | `--ephemeral` |
| Container/VM bypass | add to any | `--dangerously-bypass-approvals-and-sandbox` |

---

## Correct Patterns

### Branch review with output capture

```bash
TMPFILE=$(mktemp /tmp/codex-review.XXXXXXXX)

codex exec review \
  --base main \
  -m gpt-5.6-sol \
  -c 'model_reasoning_effort="xhigh"' \
  --ephemeral \
  --dangerously-bypass-approvals-and-sandbox \
  -o "$TMPFILE"
```

**Why**: `mktemp` template must end in Xs — appending an extension (`.md`) after the Xs
breaks macOS `mktemp`. `--base` and a custom prompt are mutually exclusive — `review`
handles diff internally.

### Custom prompt with heredoc

```bash
TMPFILE=$(mktemp /tmp/codex-review.XXXXXXXX)

codex exec \
  -m gpt-5.6-sol \
  -c 'model_reasoning_effort="xhigh"' \
  --ephemeral \
  --dangerously-bypass-approvals-and-sandbox \
  -o "$TMPFILE" \
  "$(cat <<'PROMPT'
Review the changes in git diff HEAD~1 focusing on error handling and security.
Run: git diff HEAD~1
PROMPT
)"
```

**Why**: Let Codex run `git diff` itself rather than embedding the diff — Codex has repo
access and embedding large diffs wastes tokens and loses formatting.

### Check exit code before reading output

```bash
if ! codex exec review --base main -m gpt-5.6-sol -c 'model_reasoning_effort="xhigh"' -o "$TMPFILE"; then
  echo "Codex failed — check stderr for API/auth errors"
  rm -f "$TMPFILE"
  exit 1
fi

if [ ! -s "$TMPFILE" ]; then
  echo "Codex produced empty output"
  rm -f "$TMPFILE"
  exit 1
fi
```

---

## Pattern Catalog
<!-- no-pair-required: section header with no content -->

### Embedding the diff in the prompt

**Detection**:
```bash
# In constructed prompt strings — look for variable expansion with git diff output
grep -n 'DIFF=\$(git diff' . -r
```

**What it looks like**:
```bash
DIFF=$(git diff main...HEAD)
codex exec "Review this code: $DIFF"
```

**Why wrong**: Large diffs (>50 files) hit prompt-length limits. Formatting collapses.
Codex already has filesystem access — it can run `git diff` directly.

**Do instead:** Give Codex a shell command to run rather than pasting the output. Use `codex exec "Run \`git diff main...HEAD\` and review..."` so Codex executes the diff itself with full context and correct formatting.

**Fix**: Tell Codex which command to run, not what the output is:
```bash
codex exec "Run \`git diff main...HEAD\` and review the changes for security issues."
```

---

### Using `--base` and a custom prompt together with `codex exec review`

**What it looks like**:
```bash
codex exec review --base main "Focus on error handling"
```

**Why wrong**: `--base`, `--commit`, and `--uncommitted` are mutually exclusive with a
custom `[PROMPT]` argument in the `review` subcommand. The CLI errors.

**Do instead:** When you need a custom focus prompt, drop the `review` subcommand and use bare `codex exec "your prompt"`. Let the prompt instruct Codex to run `git diff main...HEAD` itself.

**Fix**: Use `codex exec` (not `codex exec review`) with a custom prompt:
```bash
codex exec -m gpt-5.6-sol -c 'model_reasoning_effort="xhigh"' -o "$TMPFILE" \
  "Run \`git diff main...HEAD\` and focus on error handling patterns."
```

---

### Appending extension to mktemp template

**What it looks like**:
```bash
TMPFILE=$(mktemp /tmp/codex-review.XXXXXXXX.md)
```

**Why wrong**: macOS `mktemp` requires the template to end in Xs. Appending `.md` causes
`mktemp: /tmp/codex-review.XXXXXXXX.md: invalid suffix`.

**Do instead:** Keep the template as `mktemp /tmp/codex-review.XXXXXXXX` with no extension. The output file is a temp artifact read by the script, not a human-facing document — it does not need an extension.

**Fix**: No extension, Xs at the end:
```bash
TMPFILE=$(mktemp /tmp/codex-review.XXXXXXXX)
```

---

### Using `-s read-only` with `--dangerously-bypass-approvals-and-sandbox`

**What it looks like**:
```bash
codex exec review --dangerously-bypass-approvals-and-sandbox -s read-only ...
```

**Why wrong**: These flags are mutually exclusive. `-s read-only` configures the bwrap
sandbox; the bypass flag disables it entirely. Combining them errors.

**Do instead:** Choose one flag based on the environment. In containers or VMs where bwrap cannot create network namespaces, use `--dangerously-bypass-approvals-and-sandbox`. In bare-metal environments where sandbox isolation is desired, use `-s read-only` without the bypass flag.

**Fix**: Use one or the other. In containerized environments, use the bypass flag.

---

## Error-Fix Mappings

| Error Message | Root Cause | Fix |
|---------------|------------|-----|
| `codex: command not found` | CLI not installed or not in PATH | `npm install -g @openai/codex`; verify with `codex --version` |
| `loopback: Failed RTM_NEWADDR: Operation not permitted` | bwrap sandbox fails in VM/container | Add `--dangerously-bypass-approvals-and-sandbox` |
| `invalid suffix` from mktemp | Extension appended after Xs in template | Remove extension: `mktemp /tmp/codex-review.XXXXXXXX` |
| `Error: cannot use --base with PROMPT` | `codex exec review` with both `--base` and positional prompt | Remove `--base` or switch to `codex exec` without review subcommand |
| Empty output file | Timeout, model error, or prompt too long | Check stderr; do not retry automatically |
| `401 Unauthorized` | OPENAI_API_KEY not set or expired | `export OPENAI_API_KEY=...` or check key validity |
| `429 Too Many Requests` | Rate limit hit | Wait and report to user — do not retry in a loop |
| `model not found: gpt-5.6-sol` | Review lane unavailable in account tier | Fall back to the policy's Claude review lane and note it in the report |

---

## Detection Commands Reference
<!-- no-pair-required: reference block of detection commands, not an failure mode description -->

```bash
# Verify codex is installed
codex --version

# Check temp file has content before processing
[ -s "$TMPFILE" ] && echo "has content" || echo "empty or missing"

# Find embedded diffs in shell scripts (signals the embedding pattern)
grep -rn 'DIFF=\$(git' . --include="*.sh" --include="*.bash"
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall