aeview 0.0.3

Fan code reviewers across multiple agent harnesses and merge one verdict.

aeview

Fan code reviewers across multiple AI agent harnesses, then merge one deduplicated verdict.

aeview runs the same change past several reviewers — each a prompt you check into your repo — across several agent harnesses (Claude Code, Codex, Copilot), in parallel. It collects every finding, deduplicates them with an LLM judge, and writes a single report.json plus an exit code you can loop on: 0 approve · 1 needs-attention · 2 error.

The bet: a reviewer is a versioned artifact (a prompt + the harnesses it runs on), and a panel of independent models catches what any single model misses.

# install the aeview-install skill, then run /aeview-install in your agent to set up the CLI:
npx skills add MarlzRana/aeview --skill aeview-install --global
cd your-repo
aeview run          # review your current changes (auto mode); exit 1 if anything needs attention

---

Contents

• How it works
• Requirements
• Install
• Quickstart
• Scopes — what to review
• Reviewers
• Auto mode, activation & .aeviewignore
• Harnesses
• Deduplication
• Configuration
• Commands
• The report & exit codes
• Runs, lifecycle & output
• Development
• License

---

How it works

A reviewer is a prompt (REVIEWER.md) plus a set of harness instances (an agent + a model). One aeview run does this:

1. Resolve reviewers — walk up from your cwd to home collecting .aeview/reviewers/*.
2. Resolve the scope — turn --scope into a concrete git diff (working tree, a branch, a PR, …).
3. Bundle the diff — small diffs are frozen inline; large ones hand the agent read-only git to self-collect, so nothing is silently truncated.
4. Fan out — run every reviewer × harness pair concurrently, each in a read-only sandbox (read anywhere, write nothing). Each emits findings against a fixed schema.
5. Dedupe & merge — an LLM judge groups duplicate findings across the panel; survivors are kept verbatim with their provenance and an agreement count. See Deduplication.
6. Report — write report.json and exit 0 / 1 / 2.

Everything is persisted under ~/.aeview/runs/<id>/, so a killed run can be resumed.

Requirements

• Python 3.14+ (the uv installer can fetch one for you).
• macOS or Linux.
• Harness auth. aeview drives each harness through its Python SDK, which bundles a pinned CLI binary — you don't install Claude Code / Codex / Copilot separately. You do need to be authenticated with each harness a reviewer uses. Run aeview doctor to see exactly what's missing for the reviewers you have.
• gh (GitHub CLI) — for --scope pr, for --post-comments (posting the review onto the PR), and to auto-detect a branch's base from its open PR. Optional otherwise: aeview falls back to origin/HEAD, then main/master/trunk, when gh or a PR isn't available.

Install

Install the aeview-install skill, then run it — it installs the aeview CLI, installs the reviewer skills, and verifies your setup:

npx skills add MarlzRana/aeview --skill aeview-install --global

Then run /aeview-install in your agent (Claude Code, …).

Prefer to install by hand?

uv tool install --prerelease=allow aeview   # recommended (see the note); also fetches Python 3.14
# or
pipx install aeview

Why --prerelease=allow for uv? aeview pulls a prerelease Codex runtime (the Codex Python SDK is still in beta), so you'll see openai-codex / openai-codex-cli-bin alpha/beta versions. pip / pipx allow that automatically (the dependency specifier names the prerelease), but uv requires --prerelease=allow (or UV_PRERELEASE=allow) for a transitive prerelease. The flag goes away once openai-codex ships a stable release. (Homebrew support is planned.)

After install, sanity-check your setup:

aeview doctor

Quickstart

cd your-repo

# Review your changes (auto mode: uncommitted work if the tree is dirty, else your branch vs base):
aeview run

# Preview the plan (roster + scope + bundle size) without spending anything:
aeview run --dry-run

# Review a branch against its base, with every reviewer you have:
aeview run --scope branch --reviewers all

# Get machine-readable output and act on the exit code:
aeview run --json && echo "approved" || echo "needs attention (or error)"

A run prints a human summary (or --json), writes report.json, and exits with the verdict code.

Scopes — what to review

--scope <type>[:value]. Omit --scope entirely for auto. Where a type takes a value, the "bare" form (no :value) uses the default shown:

Scope	Bare default	Reviews
working-tree	—	all uncommitted changes
staged	—	only the staged changes
branch[:base]	base = auto	your branch vs base
pr[:number]	current branch's PR	a PR's diff (via gh)
effective-pr[:base]	base = auto	branch commits + uncommitted work, vs base
commits[:a,b,c]	HEAD	exactly the commits listed, each vs its own parent
range:A..B	value required	the diff between A and B
patch:file	value required	a diff file (or - for stdin)
auto	—	dirty → working-tree, else your branch vs base

Notes:

• commits is a set, not a range: --scope commits:a,c,e reviews exactly those three commits, each shown against its own parent (a union of per-commit patches). A single commit is just the one-element case; bare commits is HEAD.
• --include-dirty folds uncommitted work onto a committed scope — use it with branch, auto, or staged; it's a no-op on working-tree.
• --allow-conflicts reviews despite an in-progress merge/rebase (refused by default).
• Base resolution order: explicit value → the PR base → origin/HEAD → main/master/trunk.

Posting the review to a PR

With --scope pr, add --post-comments to publish the merged review onto the PR on GitHub (via gh). aeview posts one review per run — a GitHub review with event COMMENT, so it never approves or requests changes and can't gate your merge — made of:

• a summary comment (verdict, summary, coverage), and
• one inline comment per finding, anchored to its file and line in the PR diff. A finding whose line isn't part of the diff (reviewers can read your whole tree) is listed in the summary instead, so nothing is dropped.

Findings on the same line are combined into one comment; each run posts a fresh review, so re-running across a loop leaves a thread-per-finding audit trail on the PR. A clean run still posts a short "approved — no findings" note. Every comment is authored by your gh account (aeview has no separate identity), so it carries a visible aeview (automated review panel) badge and names the reviewer(s) behind each finding. --post-comments requires an open PR and authenticated gh, and it's an error to pass it with any scope other than pr.

Reviewers

A reviewer lives at .aeview/reviewers/<name>/REVIEWER.md: YAML frontmatter + a prompt body.

---
name: security
description: Hunts auth, injection, and trust-boundary bugs.
harnesses:
  - { harness: claude-code, model: claude-opus-4-8 }
  - { harness: codex, model: gpt-5.5, thinking: xhigh }
  - { harness: copilot, model: gemini-3.1-pro-preview }
auto-activate-paths:
  - "src/api/**"
---

You are a security reviewer. Find the injection, the auth gap, the unsafe
deserialization... (the rest of the prompt)

Frontmatter fields:

Field	Required	Meaning
name	yes	Must equal the directory name.
description	no	One line, shown by aeview reviewers.
harnesses	no	List of { harness, model, thinking? }. Omit to use the global fallbackReviewerHarnesses.
auto-activate-paths	no	Globs that opt this reviewer into auto mode.

Resolution (walk-up)

aeview climbs from your cwd through its parent directories up to your home directory, looking for <dir>/.aeview/reviewers/<name>/REVIEWER.md. First match wins, so a repo-local reviewer shadows a personal one of the same name. Your home ~/.aeview/reviewers/ holds reviewers available everywhere — including the seeded default reviewer (an adversarial general-purpose reviewer).

Selecting reviewers

aeview run --reviewers security              # one
aeview run --reviewers security,tests        # several (comma-separated)
aeview run --reviewers security --reviewers tests   # or repeated
aeview run --reviewers all                   # every reviewer visible here

With no --reviewers, aeview uses auto mode.

Resource references

The reviewer's own directory (absolute path) is prepended to its prompt, so you can drop supporting files beside REVIEWER.md (references/checklist.md, scripts, …) and reference them with relative paths. Reviewers can read anywhere, so the links resolve.

Scaffolding

aeview init security                 # create .aeview/reviewers/security/REVIEWER.md
aeview init security --with-harness  # also scaffold a harnesses: block

Auto mode, activation & .aeviewignore

Auto mode (no --reviewers) builds the roster as:

default (always) ∪ every reviewer whose auto-activate-paths matches a changed file.

A reviewer with no auto-activate-paths never auto-runs (select it by name or with all). Matching uses literal globs (Python's PurePath.full_match), anchored at the reviewer's .aeview parent directory: a single * stops at /, ** crosses directories, there's no negation, and it's case-sensitive. So write backend/**, not backend/.

Auto-activation needs repo-root-relative paths, so --scope patch (and running outside a git repo) runs only default — name any extra reviewers explicitly there.

.aeviewignore filters files out of the diff before it's reviewed — handy for lockfiles, generated code, vendored trees. It uses faithful gitignore semantics (the pathspec library):

uv.lock
dist/
**/__snapshots__/
!important.generated.ts

Files are collected on the same cwd→home walk (your home file is ~/.aeviewignore); each file's patterns anchor at its own directory, nearest rules win, and ! negation is supported.

Like auto-activation, .aeviewignore is skipped for --scope patch (its paths aren't repo-root-relative) — a patch is reviewed exactly as supplied.

Harnesses

A harness instance is { harness, model, thinking? }. Supported harnesses:

harness	Driven via	Example model
claude-code	claude-agent-sdk	claude-opus-4-8
codex	openai-codex	gpt-5.5 (e.g. thinking: xhigh)
copilot	github-copilot-sdk	a Copilot-served model

Every harness runs read-anywhere, write-nowhere: a reviewer can read any file (to gather context) but cannot modify your repo. Claude Code and Codex enforce this with their native read-only sandboxes; Copilot uses a deny-by-default permission handler that only approves reads.

Each SDK ships a pinned binary, so aeview is insulated from your own CLI upgrades. To point a harness at a different binary, set overrideHarnessBinaries.

Deduplication

A panel of independent reviewers will report the same issue more than once. After the fan-out, aeview pools every finding and hands the pool to a single dedup judge — the harness named by deduplicationHarness — whose job is deliberately narrow: it only groups.

• It never rewrites, re-scores, or summarizes a finding. Per group it just names one survivor (kept verbatim) and the duplicate ids merged into it; anything it doesn't mention stays as its own group of one.
• Precision over recall. It's instructed to merge only when confident, because a wrong merge hides a distinct problem while a wrong split only shows two views of one issue — the cheaper mistake. When in doubt, findings stay separate.
• "Same issue" means same root cause at substantially the same location — not merely the same file, category, or severity.

Each survivor becomes one finding in the report carrying its whole group's provenance: agreement (the group size) and sources (one entry per merged finding, naming the review it came from). Findings are handed to the judge as untrusted data, not instructions, so a crafted finding can't steer it into over-merging (and silently hiding real issues).

Customizing the judge

The judge's full instructions are a prompt file seeded to ~/.aeview/DEDUPLICATION.md on first run — write-if-absent, so your edits are never clobbered. Edit it to tune how aggressively findings merge (or how survivor is chosen); any YAML frontmatter is stripped before it's sent to the harness. (Leaving deduplicationHarness unset leaves findings ungrouped — but aeview reports that as a failed dedup with a warning, not a silent off-switch; see below.)

When dedup is skipped or fails

The panel's findings are never discarded — if the judge doesn't run or errors, they pass through as a raw union (one group each). dedup.status in the report records what happened:

dedup.status	When	Findings
ok	the judge ran and grouped	merged (deduplicated)
skipped	only one review contributed, or only one finding total — nothing could be a duplicate	raw union, no billed call
failed	the judge errored/timed out, or no deduplicationHarness is configured	raw union + a loud warning that duplicates were not removed; resume re-runs it

Configuration

Global settings live in ~/.aeview/settings.json, seeded (write-if-absent) on first run. Its keys are camelCase; the JSON run artifacts (report.json, review.json) use snake_case.

{
  "fallbackReviewerHarnesses": [
    { "harness": "claude-code", "model": "claude-opus-4-8" }
  ],
  "deduplicationHarness": { "harness": "claude-code", "model": "claude-opus-4-8" },
  "retention": { "keepLast": 20, "ttlDays": 14 },
  "reviewTimeoutSeconds": 1200,
  "overrideHarnessBinaries": { "codex": "/usr/local/bin/codex" }
}

Key	Meaning
fallbackReviewerHarnesses	Harnesses a reviewer runs on when its REVIEWER.md has no harnesses: block.
deduplicationHarness	The harness used to deduplicate findings across the panel.
retention	Auto-prune old runs: keep at least the newest keepLast, and drop runs that are also older than ttlDays days.
reviewTimeoutSeconds	Timeout (seconds) per harness attempt; transient errors retry, so a review's total time can exceed it. A timed-out review fails fast (no retry); resume re-runs it.
overrideHarnessBinaries	Optional per-harness override of the bundled CLI binary, by path. Keys: claude-code, codex, copilot.

Commands

Command	What it does
aeview run	Run reviewers over a scope; print the gate (verdict + findings, see below) and exit 0/1/2.
aeview status [run-id]	Per-review progress + coverage (defaults to the latest run). --wait blocks to a terminal state and adopts its exit code.
aeview result [run-id]	Print a finished run's full report; exit with its 0/1/2 code.
aeview resume <run-id>	Re-run a run's non-done reviews against its frozen bundle, then re-merge.
aeview list	Recent runs, newest first: id, time, scope, verdict, coverage.
aeview reviewers [name]	List the reviewers visible here (walk-up), or show one's detail.
aeview init <name>	Scaffold a repo reviewer. --with-harness adds a harnesses: block.
aeview doctor	Preflight: reviewer config, harness binaries + auth, and gh. Exits 1 on failure.
aeview version	Print the version.

Common run flags: --scope, --reviewers, --include-dirty, --allow-conflicts, --post-comments (with --scope pr), --dry-run, --json. Most commands accept --json for machine-readable output.

The report & exit codes

The full merged artifact is report.json — what aeview result and the on-disk file give you:

{
  "verdict": "needs-attention",          // "approve" | "needs-attention"
  "summary": "...",
  "findings": [
    {
      "id": "f3",                          // stable run-local id assigned during merge
      "title": "Unvalidated path used in file read",
      "body": "...",
      "severity": "high",                // critical | high | medium | low
      "category": "security",            // bug | security | regression | test_gap | maintainability
      "confidence": 0.9,                 // 0.0–1.0
      "location": { "file": "src/api/files.py", "line_start": 42, "line_end": 48 },
      "recommendation": "...",
      "agreement": 2,                    // size of the dedup group (findings merged into this one)
      "sources": [                         // one entry per merged finding, with its originating review
        { "review": "security__codex-gpt-5.5", "severity": "high", "confidence": 0.9 },
        { "review": "security__claude-code-claude-opus-4-8", "severity": "high", "confidence": 0.85 }
      ]
    }
  ],
  "next_steps": [ { "source": "security__...", "steps": ["..."] } ],
  "coverage": { "contributed": 3, "failed": 0 },   // reviews that completed vs. reviews that failed
  "dedup": { "status": "ok", "harness": "...", "reason": null, "warning": null },
  "usage": { "reviews": {...}, "dedup": {...}, "total": { "input_tokens": 0, "output_tokens": 0, "cost_usd": 0.0 } }
}

The agreement count, the sources provenance, and the dedup block all come from Deduplication.

aeview run prints a gate, not the full report: it's report.json with a top-level run_id added and the result-only detail omitted — findings[].id, next_steps, usage, and the dedup fields other than status (and dedup is dropped entirely when the run had a single review — there's nothing to deduplicate). The kept fields keep their report.json names, so a consumer that reads only the gate's fields works against both run and result. The dropped detail (token/cost accounting, per-review next steps, dedup provenance, per-finding ids) lives in aeview result.

Exit codes (the loop-until-clean contract):

Code	Meaning
0	approve — no actionable findings
1	needs-attention — at least one finding to act on
2	error — the run couldn't be trusted (e.g. every review failed)

Runs, lifecycle & output

Each run is a directory under ~/.aeview/runs/<id>/:

runs/<id>/
  run.json                               # the manifest: scope, roster, dedup plan, state, pid
  bundle/                                # the frozen diff under review
  reviewers/<reviewer>/<instance>/
    review.json                          # that review's findings + status + usage
    review.log                           # raw harness-SDK event stream (JSONL)
  dedup/<instance>/result.json           # the dedup judge's grouping decision
  report.json                            # the merged verdict

• Timeout & fail-fast. Each harness attempt is bounded by reviewTimeoutSeconds; a timed-out review fails fast (timeouts aren't retried). A failed review is recorded — the run continues — and resume re-runs it.
• Crash recovery. Runs record their pid; a crashed run is reconciled to interrupted and can be resumed. aeview status --wait blocks until a run reaches a terminal state.
• Retention. On each run, terminal runs outside the newest keepLast and older than ttlDays are pruned (keepLast is a guaranteed floor).

Development

git clone https://github.com/MarlzRana/aeview
cd aeview
uv sync                    # install deps (incl. dev group)
uv run pytest              # the offline test suite (no model calls)
uv run ruff check          # lint
uv run pyright             # type-check
uv run aeview --help

License

MIT