code-review-ai 0.1.7

Multi-agent code review CLI powered by LLMs. Runs specialized agents in parallel to review GitHub PRs or local diffs.

Code Review AI

Multi-agent code review CLI powered by LLMs. Runs specialized agents in parallel to review GitHub pull requests or local diffs, deduplicates findings, and synthesizes results into a structured report with severity, file location, and actionable suggestions.

Built with Python 3.12+, Typer, Pydantic, and any OpenAI-compatible API.

Features

Review pipeline:

• 4 built-in agents (security, performance, style, test coverage) + custom YAML agents
• Parallel execution via ThreadPoolExecutor with configurable concurrency
• Iterative deepening -- multiple review rounds with convergence detection
• Validation loop -- skeptical validator agent filters false positives
• Cross-agent deduplication (exact, location-based, or similarity-based)
• Token budget enforcement with automatic diff truncation

Input/output:

• GitHub PR review (--pr owner/repo#123) or local diff (--diff file.patch)
• Rich terminal, JSON, and Markdown output formats
• Interactive findings navigator with triage and PR comment posting

Operations:

• SQLite review history with trends and export
• Prompt injection defense (random delimiters, instruction anchoring)
• Cost estimation with per-model pricing
• Graceful degradation -- partial results when agents fail
• Retry with exponential backoff for transient API errors

Extensibility:

• Custom agents defined in YAML (no Python required)
• File pattern matching -- agents run only on relevant file types
• Provider-agnostic -- NVIDIA, OpenRouter, or any OpenAI-compatible API. Full-screen provider browser for adding, editing, and managing providers and models

Quick Start

Install

# Install from PyPI (recommended)
pipx install code-review-ai

# Or with pip
pip install code-review-ai

From source (for development):

git clone https://github.com/minhtribk12/code-review-ai.git
cd code-review-ai
make install  # requires uv

Configure

On first launch of cra interactive, a provider setup panel appears automatically:

 LLM Provider Setup

  Select a provider and press Enter to input your API key.

 > nvidia (no key)       https://integrate.api.nvidia.com/v1
   openrouter (no key)   https://openrouter.ai/api/v1

  Up/Down navigate, Enter input key, c continue, q quit

Enter your API key for at least one provider. Keys are saved securely and persist across restarts. Local LLM servers (localhost, private IPs) are auto-detected and don't need keys.

Alternatively, configure via .env file:

cp .env.example .env

LLM_PROVIDER=nvidia
NVIDIA_API_KEY=your-nvidia-api-key    # get from build.nvidia.com

See docs/configuration.md for all settings.

Run

# Review a local diff
uv run cra review --diff path/to/file.patch

# Review a GitHub PR
uv run cra review --pr owner/repo#123

# JSON output for CI pipelines
uv run cra review --diff file.patch --format json --quiet

# Interactive mode
uv run cra interactive

CLI Usage

Review Commands

# Local diffs
cra review --diff changes.patch
cra review --diff changes.patch --agents security,performance
cra review --diff changes.patch --format json --output report.json

# GitHub PRs (requires GITHUB_TOKEN)
cra review --pr owner/repo#123
cra review --pr https://github.com/owner/repo/pull/123

# Open findings navigator after review
cra review --diff changes.patch --findings

Token Tiers

Tier	Default Agents	Budget	Use Case
free	security	5k tokens	Free-tier APIs, small context
standard	all 4 built-in	16k tokens	32k context models
premium	all 4 built-in	48k tokens	128k context models

Budget is auto-detected from the model's context window when possible. Override with --agents or MAX_PROMPT_TOKENS.

Custom Agents

Define domain-specific agents in YAML without writing Python:

# ~/.cra/agents/django_security.yaml
name: django_security
description: "Django-specific security review"
system_prompt: |
  You are a Django security expert. Focus on:
  - CSRF token usage in views
  - SQL injection via raw() and extra()
  - Insecure deserialization with pickle
priority: 10
file_patterns:
  - "*.py"

# Use custom agents alongside built-in ones
cra review --diff changes.patch --agents security,django_security

See docs/custom-agents.md for the full guide.

Interactive TUI

cra interactive

  code-review-ai v0.1.0
  Tab autocomplete | Ctrl+A agents | Ctrl+P provider | Ctrl+O repo | Ctrl+L graph | Ctrl+D exit

cra> _
------------------------------------------------------------------------
 Branch: main | Repo: acme/app:local | Reviews: 0 | Tokens: 0 | Tier: free

Git Commands

# Read
status                          # git status (branch + changed files)
diff                            # unstaged diff
diff staged                     # staged diff
diff HEAD~3                     # diff against N commits back
log                             # compact log (last 20)
show abc123                     # full commit detail with diff

# Write
branch                          # list local branches
branch switch feat/login        # switch branch
branch create feat/new          # create + switch
add src/main.py                 # stage specific file
commit -m "fix: resolve bug"    # commit staged changes
stash                           # stash / stash pop / stash list
cd ~/projects/other-repo        # change directory (Tab completes paths)

Code Review

review                          # auto-detects unstaged/staged diff
review staged                   # review staged changes only
review HEAD~1                   # review last commit
review --agents security        # single agent
review --format json            # JSON output

PR Commands

# Read
pr list                         # list open PRs
pr show 42                      # PR details
pr diff 42                      # PR diff with syntax highlighting
pr checks 42                    # CI/CD check status
pr review 42                    # run code review on PR

# Write
pr create --fill                # auto-fill from commits
pr merge 42 --strategy squash   # merge with pre-flight checks
pr approve 42                   # approve PR

# Workflow
pr mine                         # your open PRs
pr assigned                     # PRs where you're reviewer
pr stale --days 14              # stale PRs
pr ready                        # PRs ready to merge
pr conflicts                    # PRs with merge conflicts
pr summary --full               # dashboard overview

Findings Navigator

After a review, navigate, triage, and post findings to PRs:

findings                        # navigate last review
findings 42                     # navigate saved review #42

Key bindings: Up/Down navigate, f filter, s/S sort forward/backward, m mark false positive, p stage for PR posting, P submit staged to PR, q quit. Triage state (false positive, ignored) is persisted to SQLite across sessions.

Other Commands

config                          # show all settings
config edit                     # full-screen config editor (paste supported)
config set llm_temperature 0.3  # session override
config reset                    # reload from .env (preserves API keys)
config factory-reset            # full reset (clears history, keeps keys)
# Provider management
provider                        # full-screen provider browser (alias: pv)
provider add                    # add custom provider (wizard)
provider list                   # table view of all providers
provider models nvidia          # list models for a provider
provider remove my-custom       # remove a user-defined provider
history                         # past reviews
history trends --days 30        # aggregated stats
usage                           # session token/cost stats
watch --interval 10             # continuous monitoring
agents                          # list all agents (built-in + custom)

Provider Browser

Run provider or pv to open the full-screen provider/model browser:

 Provider Browser  (Up/Down navigate, Enter expand, a add provider, m add model, d delete, i edit, q quit)

 > v nvidia  [built-in]  https://integrate.api.nvidia.com/v1  (5 models)
       nvidia/nemotron-3-super-120b-a12b  (Nemotron 3 Super 120B free, 1,000,000 ctx)
       nvidia/nemotron-3-nano-30b-a3b  (Nemotron 3 Nano 30B free, 1,000,000 ctx)
   > openrouter  [built-in]  https://openrouter.ai/api/v1  (6 models)
   > ollama  [custom]  http://localhost:11434/v1  (1 models)

Key bindings: Enter expand/collapse, a add provider, m add model to selected provider, d delete (custom only), i edit any field (works on built-in too), q quit.

Architecture

CLI (Typer) / Interactive REPL
  |
  v
Orchestrator
  |-- Token budget enforcement (truncate oversized diffs)
  |-- Prompt injection scan
  |-- Agent dispatch (parallel, ThreadPoolExecutor)
  |     |-- [Security Agent]      \
  |     |-- [Performance Agent]    |-- built-in
  |     |-- [Style Agent]          |
  |     |-- [Test Coverage Agent] /
  |     |-- [Custom YAML Agents]  --- file_patterns filtering
  |-- Cross-agent deduplication
  |-- Iterative deepening loop (convergence-based)
  |-- Synthesis (LLM merges findings into summary + risk level)
  |-- Validation loop (skeptical validator filters false positives)
  |
  v
ReviewReport -> Rich terminal / JSON / Markdown
            -> SQLite history storage
            -> Findings navigator (interactive triage + PR posting)

See docs/architecture.md for full design details.

For the full command reference with all flags, smart behaviors, and workflows, see the detailed guides:

• CLI Guide -- all CLI commands, flags, CI/CD integration, exit codes
• Interactive Guide -- all REPL commands, findings navigator, PR workflows

Documentation

Document	Description
docs/cli-guide.md	CLI commands, flags, CI/CD integration, cost control
docs/interactive-guide.md	REPL commands, findings navigator, PR workflows
docs/architecture.md	System design, pipeline flow, component responsibilities
docs/configuration.md	All settings, provider URL resolution, secrets handling
docs/data-models.md	Pydantic models, StrEnums, LLM contracts
docs/custom-agents.md	YAML agent schema, examples, discovery, file patterns
interactive_tests/cli/README.md	Mock servers and interactive test suite

Development

make install    # Install dependencies
make fmt        # Auto-format code
make lint       # Run ruff linter
make typecheck  # Run mypy (strict mode)
make test       # Run pytest with coverage
make check      # All of the above

Test Suite

696 unit tests covering models, config, LLM client, agents, agent loader, CLI, report, orchestrator, deduplication, GitHub client, and the interactive TUI.

Interactive Tests

Run against mock servers (no API keys needed):

bash interactive_tests/cli/run_all_tests.sh     # Phase 1: 16 scenarios
bash interactive_tests/cli/run_phase2_tests.sh   # Phase 2: 22 scenarios
bash interactive_tests/cli/run_phase3_tests.sh   # Phase 3: 48 scenarios

Project Structure

src/code_review_agent/
  agents/
    base.py              # BaseAgent ABC with priority + validation
    security.py          # OWASP-focused security review
    performance.py       # Complexity, memory, I/O analysis
    style.py             # Naming, readability, dead code
    test_coverage.py     # Missing tests, edge cases
  interactive/
    commands/            # REPL commands (git, pr, review, config, etc.)
    tabs/                # Textual TUI tabs
    completers.py        # Tab completion
    provider_browser.py  # Full-screen provider/model browser
    provider_cmd.py      # Provider management commands
    repl.py              # REPL loop, dispatch, toolbar
    session.py           # Session state, PR cache
    startup_keys.py      # First-launch provider key setup panel
  agent_loader.py        # Custom YAML agent discovery + loading
  config.py              # Settings with pydantic-settings
  providers.py           # Provider registry (bundled + user ~/.cra/providers.json)
  provider_registry.json # Bundled provider/model knowledge base
  connection_test.py     # LLM connection verification
  dedup.py               # Cross-agent finding deduplication
  github_client.py       # GitHub API (PR read + write + rate limiting)
  llm_client.py          # OpenAI-compatible client with retry + JSON parsing
  main.py                # Typer CLI entry point
  models.py              # Pydantic models + StrEnums
  orchestrator.py        # Agent dispatch, deepening, validation, synthesis
  prompt_security.py     # Prompt injection defense
  report.py              # Rich terminal + Markdown rendering
  storage.py             # SQLite review history
  token_budget.py        # Tiers, budgets, cost estimation

tests/                   # 696 unit tests
interactive_tests/cli/   # Mock servers + scenario tests
docs/                    # Architecture, configuration, models, custom agents

License

Apache License 2.0 -- see LICENSE for details.