/astra-review

description: Send Claude-written code to GPT-6-Astra (ChatGPT, via Codex CLI) for an independent cross-provider review, then fix what it finds.
argument-hint: "[--base <branch> | --commit <sha> | --files <paths> | --files-from-commit <sha>] [extra reviewer instructions]"
model: opus

Astra Review

Cross-provider second opinion. Claude writes the code; GPT-6-Astra (OpenAI, running through the locally installed Codex CLI with your ChatGPT login) reviews it with no shared context. Claude then fixes what Astra finds and re-runs until Astra passes or the round limit is hit.

This command runs on **Opus** (`model: opus`). Opus orchestrates, verifies findings, checks every diff, and runs the tests. Fixes are delegated to a **Fable** subagent; when Fable has hit its usage limit, Astra applies the fixes instead (see Step 4).

Purpose

• Catch problems that a same-model reviewer shares blind spots on.
• Keep Claude as the writer: Astra reviews in a read-only sandbox and returns a structured verdict, never a patch. The single exception is the Fable-limit fallback in Step 4, where Astra edits the working tree and Opus verifies the result.
• Produce a machine-readable verdict (PASS/FAIL, severity-tagged findings) that can gate a commit or push.

Prerequisites

• Codex CLI installed and logged in with ChatGPT: `codex login`
• `gpt-6-astra` available on the account (check with `codex` model picker; override with `ECC_ASTRA_MODEL`)
• Invoking this command is your consent to send the diff to OpenAI. Do not run it on code you are not allowed to share.

Usage

/astra-review                          # uncommitted changes (default)
/astra-review --base main              # everything on this branch vs main
/astra-review --commit HEAD~1          # one commit
/astra-review --files src/a.ts src/b.ts
/astra-review --files-from-commit HEAD~1  # repair round after a --commit review
/astra-review Focus on the SQL layer   # free text becomes extra reviewer instructions

Workflow

Step 1: Resolve scope

Parse `$ARGUMENTS`. Flags (`--base`, `--commit`, `--files`, `--files-from-commit`) select the scope; any remaining text is passed as `--instructions`. With no flags, review uncommitted changes.

Preview what will leave the machine before sending it:

ASTRA=""
for candidate in "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/scripts/astra-review.js" \
                 "./.claude/scripts/astra-review.js" \
                 "$HOME/.claude/scripts/astra-review.js" \
                 "./scripts/astra-review.js"; do   # plugin, project-local, global, the ECC repo itself
  [ -f "$candidate" ] && ASTRA="$candidate" && break
done
[ -n "$ASTRA" ] || { echo "astra-review.js not found; install ECC commands-core"; exit 2; }
node "$ASTRA" --dry-run [scope flags] | head -40

If the output says "Nothing to review", stop and tell the user.

Step 2: Run the review

node "$ASTRA" --consent-to-openai [scope flags] \
  --instructions "<extra text, if any>" \
  --output "$(mktemp -d)/astra-review.json"   # private dir, never a shared predictable path

The script prints a markdown report and exits 0 (PASS), 1 (FAIL), or 2 (error). On exit 2, report the error verbatim and stop. Typical causes: Codex not installed, not logged in, model not available on the account, timeout.

Step 3: Verdict gate

• **PASS** with no MEDIUM findings: report and finish.
• **PASS** with MEDIUM/LOW findings: list them, fix the ones that are clearly correct, and finish.
• **FAIL** (any CRITICAL or HIGH): go to Step 4.

Step 4: Fix cycle (max 3 rounds)

1. Show every CRITICAL and HIGH finding with file and line. 2. Verify each one against the code before changing anything (Opus does this, not a subagent). Astra can be wrong; if a finding is a false positive, say so and skip it with a one-line reason. 3. Prepare the round. Each Bash call starts a fresh shell, so print these paths once and reuse them literally (shell variables such as `$ASTRA` do not survive between calls):

• `mktemp -d` gives a private directory `<dir>`. Write the confirmed findings with the Write tool to `<dir>/confirmed.json`, as a JSON array taken from `review.findings` in the `--output` payload.
• Snapshot the working tree before any writer touches it: `git diff --binary HEAD > <dir>/before.patch` and `git ls-files --others --exclude-standard > <dir>/before-untracked.txt`. The default scope reviews uncommitted work, so the user's own edits are already in `git diff`; the snapshot is what separates them from the writer's.

4. Apply the fixes. **Try Fable first, fall back to Astra:**

• **Fable (default writer).** Launch one Agent with `model: "fable"` (subagent type `general-purpose`). Its prompt contains the confirmed findings, the instruction to change only what was flagged with no drive-by refactors, and the project's test command.
• **Fable usage limit detected.** Switch only when the Agent call itself fails with an API error whose type is `rate_limit` / `rate_limit_error` or whose status is HTTP 429 (for example `You've reached your Fable limit ... (error type rate_limit, HTTP 429 ...)`). Words such as "quota" or "rate limit" inside a successful result are never a trigger: code about rate limiting quotes them too. Do not retry Fable in this session, and tell the user once: `Fable usage limit reached; Astra is applying the fixes, Opus is verifying.` Then run, with the literal paths from item 3:

     node <astra-review.js path> --consent-to-openai --fix-findings <dir>/confirmed.json \
       --instructions "<extra text, if any>"

Astra edits the working tree in a `workspace-write` sandbox with the same isolation as the review (no web search, no network, MCP disabled, user config ignored, no API keys forwarded); the system temporary directory and `$TMPDIR` are excluded, so only the repository is writable. It does not commit or push. Exit 2 means the fix failed: report it and stop.

• **Any other Fabl