agentic-code-reviewer

README

ACR - Agentic Code Reviewer

A CLI tool that runs parallel AI-powered code reviews using LLM agents (Antigravity CLI, Codex, Claude Code, or Gemini CLI for enterprise users) and aggregates findings intelligently.

Warning: Gemini CLI is deprecated for most ACR users as of ACR v0.16.0. Google is transitioning Gemini CLI users to Antigravity CLI (agy) and says Gemini CLI will stop serving requests for Google AI Pro, Ultra, and free Gemini Code Assist individual users on June 18, 2026. ACR still supports gemini for enterprise users whose Gemini CLI access remains available, but agy is the recommended Google agent for new and non-enterprise usage. See Google's Gemini CLI to Antigravity CLI transition announcement.

Quick Start

# Install ACR
brew install richhaase/tap/acr

# Install at least one LLM CLI (Codex shown here)
brew install codex

# Run a review in your repo
cd your-repo
acr

Prerequisites

You need at least one of the following LLM CLIs installed and authenticated:

Agent	Installation
Antigravity CLI	antigravity.google/docs/cli
Codex	github.com/openai/codex (default)
Claude Code	github.com/anthropics/claude-code
Gemini CLI	Enterprise Gemini CLI installation only; deprecated for consumer use

Claude Code billing warning: We recommend against using Claude Code as an ACR agent unless you explicitly accept Anthropic's non-interactive claude -p/Agent SDK billing model. When claude is selected, ACR invokes Claude Code in non-interactive mode (claude -p; ACR uses the equivalent --print flag internally) for each Claude reviewer and for Claude-powered summarization, false-positive filtering, and PR feedback, so one ACR run can start several non-interactive Claude sessions. Anthropic says that starting June 15, 2026, subscription-authenticated claude -p and Agent SDK usage will draw from a separate monthly Agent SDK credit instead of normal interactive Claude Code subscription limits. After that credit is exhausted, usage moves to extra usage at standard API rates only if extra usage is enabled; otherwise requests stop until the credit refreshes. API-key authentication with ANTHROPIC_API_KEY continues to use pay-as-you-go API billing and does not receive the Agent SDK credit. Prefer agy or codex for ACR runs if you want to avoid this Claude billing path. See Anthropic's Agent SDK plan billing and claude -p documentation.

Optional:

Tool	Installation	Purpose
gh CLI	cli.github.com	Post reviews to GitHub PRs

How It Works

ACR spawns multiple parallel reviewers, each invoking your chosen LLM agent (Antigravity, Codex, Claude, or enterprise Gemini) independently. The parallel approach increases coverage: different reviewers may catch different issues. After all reviewers complete, ACR aggregates and clusters similar findings using an LLM summarizer, filters out likely false positives, then presents a consolidated report.

graph TD
    A[acr] -->|spawns N reviewers| B
    subgraph Parallel Review
        B[Reviewer 1]
        C[Reviewer 2]
        D[Reviewer N]
    end
    A -->|if PR detected| P[PR Feedback Summarizer]
    P -->|summarizes prior discussion| F
    B & C & D --> E[Summarizer]
    E -->|clusters & deduplicates| F[FP Filter]
    F -->|removes false positives| G[Consolidated Report]
    G --> H{Post to PR?}
    H -->|--local| I[Done]
    H -->|findings| J[Request Changes / Comment]
    H -->|no findings| K[Approve / Comment]
    J --> I
    K --> I

Installation

Homebrew (macOS)

brew install richhaase/tap/acr

From Source

go install github.com/richhaase/agentic-code-reviewer/cmd/acr@latest

Usage

# Review current branch against main with 5 parallel reviewers
acr

# Review with custom settings
acr --reviewers 10 --base develop --timeout 10m

# Review a PR by number
acr --pr 123

# Review a specific branch in a temporary worktree
acr --worktree-branch feature/my-branch

# Review a PR from a forked repository
acr --worktree-branch username:feature-branch

# Local mode (don't post to PR)
acr --local

# Auto-approve without prompting
acr --yes

# Verbose mode (show reviewer messages as they arrive)
acr --verbose

Options

Flag	Short	Default	Description
--reviewers	-r	5	Number of parallel reviewers
--concurrency	-c	-r	Max concurrent reviewers (see below)
--base	-b	main	Base ref for diff comparison
--timeout	-t	10m	Timeout per reviewer
--retries	-R	1	Retry failed reviewers N times
--verbose	-v	false	Print agent messages in real-time
--local	-l	false	Skip posting to GitHub PR
--worktree-branch	-B		Review a branch in a temp worktree (supports user:branch for forks)
--yes	-y	false	Auto-submit without prompting
--fetch/--no-fetch		true	Fetch base ref from origin before diff
--no-fp-filter		false	Disable false positive filtering
--fp-threshold		75	False positive confidence threshold 1-100
--no-pr-feedback		false	Disable PR feedback summarization
--pr-feedback-agent			Agent for PR feedback summarization
--pr			Review a PR by number (fetches into temp worktree)
--guidance			Steering context appended to review prompt (env: ACR_GUIDANCE)
--guidance-file			Path to file containing review guidance (env: ACR_GUIDANCE_FILE)
--ref-file		false	Write diff to temp file instead of embedding in prompt (auto for large diffs)
--exclude-pattern			Exclude findings matching regex (repeat)
--no-config		false	Skip loading .acr.yaml config file
--reviewer-agent	-a	codex	Agent(s) for reviews, comma-separated (agy, codex, claude, gemini)
--summarizer-agent	-s	codex	Agent for summarization (agy, codex, claude, gemini)
--reviewer-model			LLM model for review agents (env: ACR_REVIEWER_MODEL)
--summarizer-model			LLM model for summarizer/FP filter agents (env: ACR_SUMMARIZER_MODEL)

Concurrency Control

The --concurrency flag limits how many reviewers run simultaneously, independent of the total reviewer count. This helps avoid API rate limits when running many reviewers or using high retry counts.

# Run 15 total reviewers, but only 5 at a time
acr -r 15 -c 5

# With retries, -c prevents retry storms from overwhelming the API
acr -r 10 -R 3 -c 3

By default, concurrency equals the reviewer count (all run in parallel).

Fork PR Support

Review pull requests from forked repositories using GitHub's username:branch notation:

# Review a PR from user "contributor" on branch "fix-bug"
acr --worktree-branch contributor:fix-bug

ACR will:

1. Query GitHub to find the open PR from that user's branch
2. Add a temporary remote pointing to the fork
3. Fetch the branch
4. Create a worktree and run the review
5. Clean up the temporary remote

This requires an open PR from the fork to the current repository. The gh CLI must be authenticated.

Agent Selection

ACR supports multiple AI backends for code review:

Agent	CLI	Description
agy	Antigravity CLI	Google's Antigravity via CLI
codex	Codex	Default. Uses built-in codex exec review
claude	Claude Code	Anthropic's Claude via CLI
gemini	Gemini CLI	Deprecated for consumer use; available for enterprise Gemini CLI users

# Use Claude instead of Codex for reviews
acr --reviewer-agent claude

# Use Antigravity CLI for reviews
acr -a agy

# Use Gemini CLI only if you have enterprise Gemini CLI access
acr -a gemini

# Use different agents for review and summarization
acr --reviewer-agent agy --summarizer-agent claude

# Use multiple agents in round-robin (reviewers alternate between agents)
acr -r 8 --reviewer-agent agy,codex,claude

# Override the model used by review agents
acr --reviewer-agent claude --reviewer-model sonnet-4

# Use different models for review and summarization
acr --reviewer-agent claude --reviewer-model opus-4 \
    --summarizer-agent claude --summarizer-model haiku-4

Antigravity CLI (agy) manages model selection in its own configuration; ACR does not pass --reviewer-model or --summarizer-model through to agy. Gemini CLI (gemini) remains supported for enterprise users, but Google recommends the Antigravity CLI transition for individual users.

Different agents may find different issues. When multiple agents are specified (comma-separated), reviewers are assigned to agents in round-robin order. The appropriate CLI must be installed and authenticated for all selected agents. Avoid selecting claude for ACR unless you intentionally want ACR's non-interactive claude -p usage under Anthropic's current billing model.

Review Guidance

Steer reviews with additional context without replacing the built-in prompts:

# Inline guidance
acr --guidance "Focus on security vulnerabilities and auth issues"

# Guidance from file
acr --guidance-file .acr-guidance.md

Guidance is appended to the default review prompts, preserving the tuned output format and skip rules. Use it to provide domain context, focus areas, or project conventions.

PR Feedback Summarization

When reviewing a PR (via --pr flag or auto-detected from the current branch), ACR can summarize prior PR discussion to improve false positive filtering. This helps avoid re-surfacing issues that have already been discussed and dismissed.

The summarizer fetches:

• PR description
• Review comments (inline code comments)
• Issue comments (general PR discussion)
• Review summaries (approve/request-changes/comment bodies)

This context is passed to the false positive filter, which can then recognize findings that were previously acknowledged as intentional or already addressed.

# Disable PR feedback summarization
acr --no-pr-feedback

# Use a specific agent for feedback summarization
acr --pr-feedback-agent claude

PR feedback summarization runs in parallel with the reviewers and is enabled by default. It only activates when:

1. A PR is detected (via --pr flag or auto-detection)
2. The false positive filter is enabled

Environment Variables

Variable	Description
ACR_REVIEWERS	Default number of reviewers
ACR_CONCURRENCY	Default max concurrent reviewers
ACR_BASE_REF	Default base ref
ACR_TIMEOUT	Default timeout (e.g., "5m" or "300")
ACR_RETRIES	Default retry count
ACR_FETCH	Fetch base ref from origin (true/false)
ACR_FP_FILTER	Enable false positive filtering (true/false)
ACR_FP_THRESHOLD	False positive confidence threshold 1-100
ACR_PR_FEEDBACK	Enable PR feedback summarization (true/false)
ACR_PR_FEEDBACK_AGENT	Agent for PR feedback summarization
ACR_REVIEWER_AGENT	Default reviewer agent(s), comma-separated
ACR_SUMMARIZER_AGENT	Default summarizer agent
ACR_SUMMARIZER_TIMEOUT	Timeout for summarizer phase (e.g., "5m" or "300")
ACR_FP_FILTER_TIMEOUT	Timeout for false positive filter phase (e.g., "5m" or "300")
ACR_GUIDANCE	Steering context appended to review prompt
ACR_GUIDANCE_FILE	Path to file containing review guidance

Configuration

Create .acr.yaml in your repository root to configure persistent settings:

# All fields are optional - defaults shown in comments
reviewers: 5              # Number of parallel reviewers
concurrency: 5            # Max concurrent reviewers (defaults to reviewers)
base: main                # Base ref for diff comparison
timeout: 10m              # Timeout per reviewer (supports "5m", "300s", or 300)
retries: 1                # Retry failed reviewers N times
fetch: true               # Fetch base ref from origin before diff

# Agent selection
# reviewer_agent: codex   # Single agent for reviews (agy, codex, claude, gemini)
# reviewer_agents:        # Multiple agents for round-robin assignment
#   - agy
#   - codex
#   - claude
# summarizer_agent: codex # Agent for summarization (agy, codex, claude, gemini)
# reviewer_model: ""      # LLM model override for review agents
# summarizer_model: ""    # LLM model override for summarizer/FP filter agents
summarizer_timeout: 5m    # Timeout for summarizer phase
fp_filter_timeout: 5m     # Timeout for false positive filter phase

# Review guidance (appended to built-in prompts)
# guidance_file: .acr-guidance.md

filters:
  exclude_patterns:       # Regex patterns to exclude from findings
    - "Next\\.js forbids"
    - "deprecated API"
    - "consider using"

fp_filter:
  enabled: true           # Enable LLM-based false positive filtering
  threshold: 75           # Confidence threshold 1-100 (100 = definitely false positive)

pr_feedback:
  enabled: true           # Summarize prior PR comments to improve FP filtering
  # agent: claude         # Agent for summarization (defaults to summarizer_agent)

Precedence

Configuration is resolved with the following precedence (highest to lowest):

1. CLI flags (e.g., --reviewers 10)
2. Environment variables (e.g., ACR_REVIEWERS=10)
3. Config file (.acr.yaml)
4. Built-in defaults

Behavior

• Config file is loaded from the git repository root
• Missing config file is not an error (empty defaults used)
• Invalid YAML or regex patterns produce an error
• Unknown keys in config file produce a warning with "did you mean?" suggestions
• CLI --exclude-pattern flags are merged with config patterns (union)
• Use --no-config to skip loading the config file for a single run

Exit Codes

Code	Meaning
0	No findings
1	Findings found
2	Error
130	Interrupted (SIGINT/SIGTERM)

GitHub Integration

When not in --local mode, ACR posts results as PR reviews (not comments), so they appear in the PR's Reviews tab.

When findings are found

You'll be prompted to choose how to post the review:

? Post review to PR #123? [R]equest changes / [C]omment / [S]kip:

• R (default): Post as a "request changes" review
• C: Post as a comment-only review
• S: Skip posting

When no findings (LGTM)

You'll be prompted to choose how to post the approval:

? Post LGTM to PR #123? [A]pprove / [C]omment / [S]kip:

• A (default): Approve the PR (checks CI status first)
• C: Post as a comment-only review
• S: Skip posting

Self-reviews (reviewing your own PR) only show Comment/Skip options since GitHub doesn't allow self-approval.

Use --yes to auto-submit with defaults (request-changes for findings, approve for LGTM).

Requires the gh CLI to be authenticated.

Development

# List available targets
make help

# Build with version info (outputs to bin/)
make build

# Run all quality checks (format, lint, vet, staticcheck, tests)
make check

# Run tests
make test

# Run linter
make lint

# Run staticcheck
make staticcheck

# Format code
make fmt

# Clean build artifacts
make clean

See CONTRIBUTING.md for contribution guidelines.

License

Apache License 2.0 - see LICENSE