autoreview

# Auto Review Run the bundled structured review helper as a closeout check. This is code review, not Guardian `auto_review` approval routing. Codex review is the default when no engine is set. It uses `gpt-5.5` by default, usually delivers the best review results, and should remain the normal final closeout engine. Claude review is optional and uses `claude-fable-5` by default. Use when: - user asks for Codex review / Claude review / Pi review / Droid review / OpenCode review / autoreview / second-model review - after non-trivial code edits, before final/commit/ship - reviewing a local branch or PR branch after fixes ## Contract - Treat review output as advisory. Never blindly apply it. - Verify every finding by reading the real code path and adjacent files. - Read dependency docs/source/types when the finding depends on external behavior. - Reject unrealistic edge cases, speculative risks, broad rewrites, and fixes that over-complicate the codebase. - Prefer small fixes at the right ownership boundary; no refactor unless it clearly improves the bug class. - When an accepted finding shows a bug class or repeated pattern, inspect the current PR scope for sibling instances before fixing. - Fix the scoped bug class at once when practical; stop at touched surfaces, owner boundaries, and clear follow-up territory. - Keep going until structured review returns no accepted/actionable findings. - If a review-triggered fix changes code, rerun focused tests and rerun the structured review helper. - For security-audit suppression changes, verify accepted findings remain auditable: suppressed findings stay in structured output, active output keeps an unsuppressible suppression notice, and aggregate findings cannot hide unrelated active risk. - Never switch or override the requested review engine/model. If the review hits model capacity, retry the same command a few times with the same engine/model. - Be patient with large bundles. Structured review can take up to 30 minutes while the model call is active, especially with Codex tools or web search. - Treat heartbeat lines like `review still running: ... elapsed=... pid=...` as healthy progress, not a hang. Let the helper continue while heartbeats are advancing. Pass `--stream-engine-output` when live engine text is useful; Codex and Claude filter tool/file chatter, other engines pass raw output through. - Do not kill a review just because it has been quiet for 2-5 minutes, or because it is still running under the 30-minute window. Inspect the process only after missing multiple expected heartbeats, after 30 minutes, or after an obviously failed subprocess; prefer letting the same helper command finish. - Tools are useful in review mode. The helper allows read-only inspection tools and web search by default so reviewers can check dependency contracts, upstream docs, and current behavior. - Security perspective is always included, but it should not cripple legitimate functionality. Report security findings only when the change creates a concrete, actionable risk or removes an important safety check. - For regression provenance, keep roles separate: blamed code author, blamed PR author, PR merger/committer, current PR author, and PR/date. If no blamed PR is traceable, use the blamed commit as the provenance: commit SHA, date, and author username. Do not guess a merger or frame missing PR metadata as a separate finding. - If the blamed PR was merged by `clawsweeper[bot]` or another automation, identify the human trigger when practical. Check timeline/comments first; if rate-limited, use gitcrawl/cache or public PR HTML. Look for maintainer commands such as `@clawsweeper automerge`, `/landpr`, or labels/status comments that armed automerge. Report `automerge triggered by @login`; if not found, say trigger unknown. - Do not invoke built-in `codex review`, nested reviewers, or reviewer panels from inside the review. The helper builds one bundle, calls one selected engine, validates one structured result, and stops. - Stop as soon as the helper exits 0 with no accepted/actionable findings. Do not run an extra review just to get a nicer "clean" line, a second opinion, or clearer closeout wording. - Treat the helper's successful exit plus absence of actionable findings as the clean review result, even if the underlying Codex CLI output is terse. - Multi-reviewer panels are opt-in only. Use them when explicitly requested or when risk justifies the extra spend; the main agent still verifies every accepted finding before fixing. - If rejecting a finding as intentional/not worth fixing, add a brief inline code comment only when it explains a real invariant or ownership decision that future reviewers should know. - If `gh`/Gitcrawl reports `database disk image is malformed`, run `gitcrawl doctor --json` once to let the portable cache repair before retrying review; do not bypass the shim unless repair fails and freshness requires live GitHub. - If Gitcrawl reports a portable manifest mismatch, source/runtime DB health error, or stale portable-store checkout, run `gitcrawl doctor --json` and inspect `source_db_health`, `runtime_db_health`, and `portable_store_status` before falling back to live GitHub. - Do not push just to review. Push only when the user requested push/ship/PR update. ## Skill Path (set once) Set the skill script paths once, then use `"$AUTOREVIEW"` and `"$AUTOREVIEW_HARNESS"` in the examples below. Choose one: ```bash # Project-local skill in the current repo: export AUTOREVIEW=".agents/skills/autoreview/scripts/autoreview" export AUTOREVIEW_HARNESS=".agents/skills/autoreview/scripts/test-review-harness" ``` ```bash # Source checkout of openclaw/agent-skills: export AUTOREVIEW="skills/autoreview/scripts/autoreview" export AUTOREVIEW_HARNESS="skills/autoreview/scripts/test-review-harness" ``` ```bash # Global skill: export AGENTS_HOME="${AGENTS_HOME:-$HOME/.agents}" export AUTOREVIEW="$AGENTS_HOME/skills/autoreview/scripts/autoreview" export AUTOREVIEW_HARNESS="$AGENTS_HOME/skills/autoreview/scripts/test-review-harness" ``` When using Claude Code, set `AGENTS_HOME="$HOME/.claude"` for global skills. Project-local skills live under `.claude/skills/` in the current repo. ## Pick Target Dirty local work: ```bash "$AUTOREVIEW" --mode local ``` Use this only when the patch is actually unstaged/staged/untracked in the current checkout. `--mode uncommitted` is accepted as an alias for `--mode local`. For committed, pushed, or PR work, point the helper at the commit or branch diff instead; do not force dirty modes just because the helper docs mention dirty work first. A clean local review only proves there is no local patch. Branch/PR work: ```bash "$AUTOREVIEW" --mode branch --base origin/main ``` Optional review context is first-class: ```bash "$AUTOREVIEW" --mode branch --base origin/main --prompt-file /tmp/review-notes.md --dataset /tmp/evidence.json ``` If an open PR exists, use its actual base: ```bash base=$(gh pr view --json baseRefName --jq .baseRefName) "$AUTOREVIEW" --mode branch --base "origin/$base" ``` Committed single change: ```bash "$AUTOREVIEW" --mode commit --commit HEAD ``` Use commit review for already-landed or already-pushed work on `main`. Reviewing clean `main` against `origin/main` is usually an empty diff after push. For a small stack, review each commit explicitly or review the branch before merging with `--base`. ## Parallel Closeout Format first if formatting can change line locations. Then it is OK to run tests and review in parallel: ```bash "$AUTOREVIEW" --parallel-tests "<focused test command>" ``` On Windows, the default `--parallel-tests` shell preserves the platform `cmd.exe` semantics used by Python `shell=True`. Use `--parallel-tests-shell powershell` or `--parallel-tests-shell pwsh` when the focused test command is PowerShell-specific. Tradeoff: tests may force code changes that stale the review. If tests or review lead to code edits, rerun the affected tests and rerun review until no accepted/actionable findings remain. Once that rerun exits cleanly, stop; do not spend another long review cycle on redundant confirmation. ## Review Panels Run multiple reviewers against one frozen bundle: ```bash "$AUTOREVIEW" --reviewers codex,claude,pi,droid ``` `--panel` is shorthand for Codex plus Claude unless `--engine` changes the first reviewer: ```bash "$AUTOREVIEW" --panel ``` Set reviewer models and thinking/effort explicitly: ```bash "$AUTOREVIEW" --reviewers codex,claude --model codex=gpt-5.5 --thinking codex=high --model claude=claude-fable-5 --thinking claude=max ``` Inline syntax is also supported for simple model IDs: ```bash "$AUTOREVIEW" --reviewers codex:gpt-5.5:high,claude:claude-fable-5:max ``` For models with slashes or extra colons, prefer keyed form: ```bash "$AUTOREVIEW" --engine pi --model anthropic/claude-sonnet-4 --thinking high "$AUTOREVIEW" --engine opencode --model opencode/north-mini-code-free --thinking high "$AUTOREVIEW" --engine droid --model claude-opus-4-8 --thinking low "$AUTOREVIEW" --reviewers codex,pi --model codex=gpt-5.5 --model pi=anthropic/claude-sonnet-4 "$AUTOREVIEW" --reviewers codex,opencode --model codex=gpt-5.5 --model opencode=opencode/north-mini-code-free "$AUTOREVIEW" --reviewers codex,droid --model codex=gpt-5.5 --model droid=claude-opus-4-8 ``` ## Models and thinking The helper accepts `--model` globally or per engine (`engine=model`) and `--thinking` globally or per engine (`engine=level`). Repeat either flag for multiple reviewers. Recommended model defaults: | Engine | Default model | Source note | |--------|---------------|-------------| | **codex** (default) | `gpt-5.5` | OpenAI's current GPT-5.5 alias | | **claude** | `claude-fable-5` | Anthropic's most capable widely released Claude model | CLI flags and environment variables override these defaults. Droid, Copilot, Pi, and OpenCode do not get built-in model defaults here because their provider catalogs are external to the Codex/Claude closeout path and may vary by installation. | Engine | Model flag | Example model IDs | Thinking flag | Accepted levels | |--------|------------|-------------------|---------------|-----------------| | **codex** (default) | `codex --model X exec ...` | `gpt-5.5`, `gpt-5.5-2026-04-23` | `-c model_reasoning_effort=Y` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` | | **claude** | `claude --model X` | `claude-fable-5`, `claude-opus-4-8`, `claude-sonnet-4-6`, `claude-haiku-4-5` | `--effort Y` | `low`, `medium`, `high`, `xhigh`, `max` | | **droid** | `droid exec --model X` | `claude-opus-4-8`, Factory model IDs | `-r, --reasoning-effort Y` | `off`, `none`, `low`, `medium`, `high` | | **copilot** | `copilot --model X` | `gpt-5.2`, Copilot model aliases | not supported | n/a | | **pi** | `pi --model X` | `anthropic/claude-sonnet-4`, `openai/gpt-4o` | `--thinking Y` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` | | **opencode** | `opencode run -m X` | `opencode/north-mini-code-free`, OpenCode provider/model IDs | `--variant Y` | `minimal`, `low`, `medium`, `high`, `max` | Claude also supports `--fallback-model a,b` for availability-based fallback chains ([model-config](https://code.claude.com/docs/en/model-config)). Current Claude docs note that auth, billing, rate-limit, request-size, and transport errors do not trigger fallback, and the changelog documents interactive-session support in `v2.1.166`. Examples matching current `main` behavior: ```bash # Codex with explicit model and reasoning "$AUTOREVIEW" --engine codex --model gpt-5.5 --thinking high # Claude Code aliases or full model names, with optional availability fallback "$AUTOREVIEW" --engine claude --model claude-fable-5 --thinking max "$AUTOREVIEW" --engine claude --model claude-fable-5 --fallback-model claude-opus-4-8,claude-sonnet-4-6 # Factory Droid with explicit model and reasoning effort "$AUTOREVIEW" --engine droid --model claude-opus-4-8 --thinking low # GitHub Copilot (model only; no thinking knob) "$AUTOREVIEW" --engine copilot --model gpt-5.2 # Pi with explicit model and thinking level "$AUTOREVIEW" --engine pi --model anthropic/claude-sonnet-4 --thinking high --pi-bin pi # OpenCode with explicit provider/model and variant "$AUTOREVIEW" --engine opencode --model opencode/north-mini-code-free --thinking high ``` ### Environment defaults CLI flags take precedence over environment variables. | Variable | Purpose | |----------|---------| | `AUTOREVIEW_MODEL` | Override the built-in default `--model` for all engines | | `AUTOREVIEW_THINKING` | Default `--thinking` for all engines | | `AUTOREVIEW_FALLBACK_MODEL` | Default Claude `--fallback-model` chain | | `AUTOREVIEW_<ENGINE>_MODEL` | Per-engine model override, for example `AUTOREVIEW_CODEX_MODEL=gpt-5.5` | | `AUTOREVIEW_<ENGINE>_THINKING` | Per-engine thinking override | | `AUTOREVIEW_CLAUDE_FALLBACK_MODEL` | Claude-only fallback chain | Codex maps thinking to `model_reasoning_effort`. Claude maps thinking to `--effort`. Droid maps thinking to `-r, --reasoning-effort`. Pi maps thinking to `--thinking`. OpenCode maps thinking to `--variant`. Copilot rejects `--thinking`. Only Claude accepts `--fallback-model`; global CLI/env fallback requires at least one Claude reviewer, and engine-specific fallback overrides require that reviewer to be selected. Non-Claude fallback overrides, including `AUTOREVIEW_<NONCLAUDE>_FALLBACK_MODEL`, fail closed instead of being silently ignored. ## Review engine isolation When autoreview runs inside the repository under review, external reviewer CLIs must not load project-local trust or configuration that the branch controls. | Engine | Isolation flags | Reference | |--------|-----------------|-----------| | **codex** | `-c project_doc_max_bytes=0`, repo `trust_level="untrusted"`, `exec --ignore-user-config --ignore-rules`, plus read-only sandbox | Codex CLI `exec --help` | | **claude** | `--safe-mode --setting-sources user --strict-mcp-config --disallowedTools mcp__*` plus explicit `--allowedTools` (`--safe-mode` requires Claude Code `v2.1.169+`) | Claude Code [CLI reference](https://code.claude.com/docs/en/cli-reference) | | **pi** | `--no-approve --no-session --no-context-files --no-extensions --no-skills --no-prompt-templates --no-themes`, plus read-only tool allowlist | Pi CLI `--help`; requires Pi `v0.79.0+` | | **opencode** | `opencode run --dir <repo> --pure --format json`, prompt over stdin, neutral subprocess cwd, injected deny-by-default permissions, project config disabled | OpenCode CLI `--help` |