Selvage

Selvage: Code reviews with an edge!

No more waiting for reviews! AI instantly analyzes your code changes to provide quality improvements and bug prevention. With smart context analysis (AST-based) that's accurate and cost-effective, plus multi-turn processing for large codebases - seamlessly integrated with all Git workflows.

• ✨ Key Features
• 🚀 Quick Start
• 🎯 Practical Usage Guide
  • MCP Mode Usage
  • ⌨️ CLI Usage
• 🌐 Smart Context Analysis and Supported AI Models
  • 🎯 Smart Context Analysis
  • Supported AI Models
• 📄 Review Result Storage Format
• 🔧 Troubleshooting
• 🤝 Contributing
• 📜 License
• 📋 Change Log
• 📞 Contact and Community

✨ Key Features

• 🤖 Multiple AI Model Support: Leverage the latest LLM models including OpenAI GPT-5, Anthropic Claude Sonnet-4, Google Gemini, and more
• 🔍 Git Workflow Integration: Support for analyzing staged, unstaged, and changes between specific commits/branches
• 🎯 Optimized Context Analysis: Tree-sitter based AST analysis automatically extracts the smallest code blocks containing changed lines along with their dependency statements, providing contextually optimized information for each situation
• 🔄 Automatic Multi-turn Processing: Automatic prompt splitting when context limits are exceeded, supporting stable large-scale code reviews (Large Context Mode now auto-triggers once total tokens exceed 200k, even without provider errors)
• 🤖 MCP Mode Support: Register as MCP mode in Cursor, Claude Code, etc., and request code reviews through natural language like "Review current changes"
• 🔌 Claude Code Plugin: Install via marketplace with a single command — includes dedicated /review skill and selvage-reviewer agent for seamless integration
• 🧠 Agent-Delegated Review (get_review_context): Returns structured review context (diff + Smart Context + system prompt) so host agents (Claude Code, Cursor, Antigravity, etc.) can perform code reviews with their own LLM — no API key required
• 📖 Open Source: Freely use and modify under Apache-2.0 License

🚀 Quick Start

Common Setup

1. Installation

Recommended Method (using uv)

# Install uv (run once)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Selvage
uv tool install selvage

Alternative Method (using pipx)

# Install pipx (macOS)
brew install pipx

# Install Selvage
pipx install selvage

Traditional Method (pip)

# ⚠️ May cause externally-managed-environment error on some systems
pip install selvage

macOS/Linux users: If you encounter errors with pip install, please use the uv or pipx methods above.

2. API Key Setup

Get an API key from OpenRouter and set it up:

export OPENROUTER_API_KEY="your_openrouter_api_key_here"

MCP Mode Usage (Recommended)

Register as MCP mode in Cursor, Claude Code, etc., to request code reviews through natural language.

Cursor Integration

Register in Cursor's MCP configuration file (path may vary depending on user environment):

Common path: ~/.cursor/mcp.json

// Method 1: Using environment variables (if already set)
{
  "mcpServers": {
    "selvage": {
      "command": "uvx",
      "args": ["selvage", "mcp"]
    }
  }
}

// Method 2: Direct specification
{
  "mcpServers": {
    "selvage": {
      "command": "uvx",
      "args": ["selvage", "mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here"
      }
    }
  }
}

Claude Code Integration

Method A: Plugin via Marketplace (Recommended)

Install the Selvage plugin from the marketplace to get the dedicated /review skill and selvage-reviewer agent:

# Step 1: Add Selvage marketplace
/plugin marketplace add selvage-lab/selvage

# Step 2: Install the plugin
/plugin install selvage@selvage-lab-selvage

After installation, use the /review skill directly:

/review                      # Review unstaged changes
/review staged               # Review staged changes
/review branch main          # Review against main branch
/review commit abc1234       # Review from specific commit

💡 No API key required! The plugin uses get_review_context to leverage Claude Code's own LLM for code review, so no external API key is needed.

Method B: MCP Server Registration

# Method 1: Using environment variables (if already set)
claude mcp add selvage -- uvx selvage mcp

# Method 2: Direct specification
claude mcp add selvage -e OPENROUTER_API_KEY=your_openrouter_api_key_here -- uvx selvage mcp

Usage

After restarting your IDE, request reviews from your Coding Assistant:

Please review current changes using selvage mcp
Review changes between current branch and main branch using claude-sonnet-4-thinking with selvage mcp

🎉 Done! Selvage will analyze the code, review it, and deliver results through your Coding Assistant.

CLI Mode Usage

For direct terminal usage:

selvage review --model claude-sonnet-4-thinking

💡 More Options: CLI Usage | Practical Usage Guide

🎯 Practical Usage Guide

MCP Mode Usage

Basic Usage

# Basic review request
Please review current changes using selvage mcp

# Review staged changes
Review staged work using gpt-5-high with selvage mcp

# Review against specific branch
Review current branch against main branch using selvage mcp

# Review with automatic model selection
Review current branch against main branch using selvage mcp, automatically selecting appropriate model

Agent-Delegated Review (No API Key Required)

The get_review_context tool returns structured review context so host agents can perform code reviews with their own LLM — no Selvage API key needed.

# Request agent-delegated review context
Get review context for current changes using selvage mcp, then review the code

# Agent-delegated review for staged changes
Get review context for staged changes using selvage mcp

# Agent-delegated review against branch
Get review context comparing current branch to main using selvage mcp

💡 How it works: Selvage extracts diff + AST-based Smart Context + system prompt and returns it as structured context. The host agent (Claude Code, Cursor, Antigravity, etc.) then performs the review directly with its own LLM, without needing an external API key.

Advanced Workflows

Multi-model Comparison Review

Review staged work using both gpt-5-high and claude-sonnet-4-thinking with selvage mcp, then compare the results

Stepwise Code Improvement Workflow

1. Review current changes using claude-sonnet-4-thinking with selvage mcp
2. Critically evaluate review feedback for validity against current codebase and set priorities
3. Apply improvements sequentially based on established priorities

CI/CD Integration Scenarios

# Code quality verification before PR creation
Review changes against main branch using selvage mcp for code quality verification before PR creation

# Final check before deployment
Perform comprehensive review of staged changes using selvage mcp for final check before deployment

⌨️ CLI Usage

Direct terminal usage method. While MCP mode is recommended, CLI is useful for scripts and CI/CD.

Configuring Selvage

# View all settings
selvage config list

# Set default model
selvage config model <model_name>

# Set default language
selvage config language <language_name>

Code Review

selvage review [OPTIONS]

Key Options

• --repo-path <path>: Git repository path (default: current directory)
• --staged: Review only staged changes
• --target-commit <commit_id>: Review changes from specific commit to HEAD (e.g., abc1234)
• --target-branch <branch_name>: Review changes between current branch and specified branch (e.g., main)
• --model <model_name>: AI model to use (e.g., claude-sonnet-4-thinking)
• --open-ui: Automatically launch UI after review completion
• --no-print: Don't output review results to terminal (terminal output enabled by default)
• --skip-cache: Perform new review without using cache

Usage Examples

# Review current working directory changes
selvage review

# Final check before commit
selvage review --staged

# Review specific files only
git add specific_files.py && selvage review --staged

# Code review before sending PR
selvage review --target-branch develop

# Quick and economical review for simple changes
selvage review --model gemini-2.5-flash

# Review and then view detailed results in web UI
selvage review --target-branch main --open-ui

Git Workflow Integration

Team Collaboration Scenarios

# Code quality verification before Pull Request creation
selvage review --target-branch main --model claude-sonnet-4-thinking

# Pre-analysis of changes for code reviewers
selvage review --target-branch develop --model claude-sonnet-4-thinking

# Comprehensive review of all changes after specific commit
selvage review --target-commit a1b2c3d --model claude-sonnet-4-thinking

Development Stage Quality Management

# Quick feedback during development (before WIP commit)
selvage review --model gemini-2.5-flash

# Final verification of staged changes (before commit)
selvage review --staged --model claude-sonnet-4-thinking

# Emergency review before hotfix deployment
selvage review --target-branch main --model claude-sonnet-4-thinking

Large-scale Code Review

# Large codebases are automatically handled
selvage review --model claude-sonnet-4  # Usage is the same, multi-turn processing automatically applied after detection

Selvage automatically handles large code changes that exceed LLM model context limits. Once usage reaches roughly 200k tokens (tiktoken basis), Large Context Mode starts automatically, so just wait for it to complete.

Cost Optimization

# Use economical models for small changes
selvage review --model gemini-2.5-flash

Viewing Results

Review results are output directly to the terminal and automatically saved to files simultaneously.

For additional review management and re-examination, you can use the web UI:

# Manage all saved review results in web UI
selvage view

# R

…