selvage

Selvage：AI を活用したコードレビュー自動化ツール

🌐 한국어

AI が Git の差分を分析し、コード品質の向上、バグの発見、セキュリティの脆弱性の特定を支援する最新の CLI ツールです。

🤖 AI エージェント：https://selvage.ai/llms.txt のドキュメントをご覧ください

▶ デモ動画を見る

Selvage：ひと味違うコードレビュー！

レビュー待ちはもう不要です！AI がコードの変更を即座に分析し、品質向上とバグの予防に役立つ情報を提供します。 AST ベースのスマートなコンテキスト分析により、精度とコスト効率を両立し、大規模なコードベースには複数ターンの処理で対応します。あらゆる Git ワークフローにシームレスに統合できます。

✨ 主な機能

• 🤖 複数の AI モデルに対応：OpenAI GPT-5、Anthropic Claude Sonnet-4、Google Gemini など、最新の LLM モデルを活用できます
• 🔍 Git ワークフローとの統合：ステージ済み、未ステージの変更、および特定のコミットやブランチ間の変更を分析できます
• 🎯 最適化されたコンテキスト分析：Tree-sitter ベースの AST 分析により、変更行を含む最小のコードブロックとその依存関係を示す文を自動抽出し、状況に応じて最適化されたコンテキストを提供します
• 🔄 複数ターンの自動処理：コンテキスト制限を超えた場合、プロンプトを自動分割して大規模なコードレビューを安定して実行します（大規模コンテキストモードは、プロバイダーのエラーがなくても、合計トークン数が 200k を超えると自動的に開始します）
• 🤖 MCP モードに対応：Cursor、Claude Code などで MCP モードとして登録し、「現在の変更をレビューして」のような自然言語でコードレビューを依頼できます
• 🔌 Claude Code プラグイン：マーケットプレイスから単一のコマンドでインストールでき、専用の /review スキルと selvage-reviewer エージェントが含まれているため、シームレスに統合できます
• 🧠 エージェントに委任するレビュー（get_review_context）：構造化されたレビューコンテキスト（差分＋スマートコンテキスト＋システムプロンプト）を返すため、ホストエージェント（Claude Code、Cursor、Antigravity など）は独自の LLM でコードレビューを実行できます。API キーは不要です
• 📖 オープンソース：Apache-2.0 ライセンスのもと、自由に使用・変更できます

🚀 クイックスタート

共通のセットアップ

1. インストール

推奨方法（uv を使用）

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

# Install Selvage
uv tool install selvage

代替方法（pipx を使用）

# Install pipx (macOS)
brew install pipx

# Install Selvage
pipx install selvage

従来の方法（pip）

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

macOS/Linux ユーザーの方へ：pip install でエラーが発生した場合は、上記の uv または pipx を使用してください。

2. API キーの設定

OpenRouter から API キーを取得し、設定します。

export OPENROUTER_API_KEY="your_openrouter_api_key_here"

MCP モードの使い方（推奨）

Cursor、Claude Code などで MCP モードとして登録し、自然言語でコードレビューを依頼します。

Cursor との連携

Cursor の MCP 設定ファイルに登録します（パスはユーザー環境によって異なる場合があります）。

一般的なパス： ~/.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 との連携

方法 A：マーケットプレイス経由でプラグインを導入（推奨）

マーケットプレイスから Selvage プラグインをインストールすると、専用の /review スキルと selvage-reviewer エージェントを利用できます。

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

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

インストール後は、/review スキルを直接使用します。

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

💡 API キーは不要です！ このプラグインは get_review_context を使用して、Claude Code 自身の LLM を活用してコードレビューを行うため、外部 API キーは必要ありません。

方法 B：MCP サーバーの登録

# 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

使い方

IDE を再起動した後、コーディングアシスタントにレビューを依頼します。

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

🎉 完了です！ Selvage がコードを分析してレビューし、コーディングアシスタントを通じて結果を提示します。

CLI モードの使い方

ターミナルから直接使用する場合：

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

💡 その他のオプション： CLI の使い方 | 実践ガイド

🎯 実践ガイド

MCP モードの使い方

基本的な使い方

# 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

エージェントにレビューを委任（API キー不要）

get_review_context ツールは、ホストエージェントが自身の LLM でコードレビューを行えるよう、構造化されたレビューコンテキストを返します。Selvage の API キーは不要です。

# 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

💡 仕組み：Selvage は差分、AST ベースの Smart Context、システムプロンプトを抽出し、構造化されたコンテキストとして返します。その後、ホストエージェント（Claude Code、Cursor、Antigravity など）が外部 API キーを必要とせず、自身の LLM で直接レビューを行います。

高度なワークフロー

複数モデルによる比較レビュー

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

段階的なコード改善ワークフロー

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 連携のシナリオ

# 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 の使い方

ターミナルから直接使用する方法です。MCP モードを推奨しますが、CLI はスクリプトや CI/CD で便利です。

Selvage の設定

# View all settings
selvage config list

# Set default model
selvage config model <model_name>

# Set default language
selvage config language <language_name>

コードレビュー

selvage review [OPTIONS]

主なオプション

• --repo-path <path>：Git リポジトリのパス（デフォルト：現在のディレクトリ）
• --staged：ステージング済みの変更のみをレビュー
• --target-commit <commit_id>：指定したコミットから HEAD までの変更をレビュー（例：abc1234）
• --target-branch <branch_name>：現在のブランチと指定したブランチ間の変更をレビュー（例：main）
• --model <model_name>：使用する AI モデル（例：claude-sonnet-4-thinking）
• --open-ui：レビュー完了後に UI を自動的に起動
• --no-print：レビュー結果をターミナルに出力しない（デフォルトではターミナルに出力）
• --skip-cache：キャッシュを使用せず、新しいレビューを実行

使用例

# 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 ワークフローとの連携

チームでの共同作業のシナリオ

# 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

開発段階での品質管理

# 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 codebases are automatically handled
selvage review --model claude-sonnet-4  # Usage is the same, multi-turn processing automatically applied after detection

Selvage は、LLM モデルのコンテキスト上限を超える大規模なコード変更を自動的に処理します。 使用量が約 200k トークン（tiktoken 基準）に達すると、大規模コンテキストモードが自動的に開始されます。完了するまで待つだけです。

コストの最適化

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

結果の表示

レビュー結果はターミナルに直接出力され、同時にファイルにも自動的に保存されます。

追加のレビュー管理や再確認には、Web UI を使用できます。

# Manage all saved review results in web UI
selvage view

# Run UI on different port
selvage view --port 8502

主な UI 機能：

• 📋 すべてのレビュー結果の一覧を表示
• 🎨 Markdown 形式で表示
• 🗂️ JSON 形式の構造化された結果を表示

🌐 スマートコンテキスト分析と対応 AI モデル

🎯 スマートコンテキスト分析

Selvage は Tree-sitter ベースの AST 分析を使用して、変更行に関連するコードブロックのみを正確に抽出し、コスト効率とレビュー品質を同時に確保します。

Smart Context の仕組み

• 高精度な抽出：変更された行を含む関数／クラスのブロックと、関連する依存関係（インポートなど）のみを抽出します。
• コストの最適化：ファイル全体ではなく必要なコンテキストのみを送信することで、トークン使用量を大幅に削減します。
• 品質保証：AST ベースでコード構造を正確に理解し、高いレビュー精度を維持します。

Smart Context の自動適用

Selvage はファイルサイズと変更範囲を分析し、最も効率的なレビュー方法を自動的に選択します。

🎯 Small Changes           → Fast and accurate analysis with Smart Context
📄 Small Files            → Complete context understanding with full file analysis
📋 Partial Edits in Large Files → Focused analysis of related code with Smart Context
📚 Large Changes in Big Files   → Comprehensive review with full file analysis

💡 自動最適化：手動で設定しなくても、状況に応じた最適な分析方法が自動的に適用されます。

Smart Context 対応言語

• Python、JavaScript、TypeScript、Java、Kotlin

汎用コンテキスト抽出のサポート

• 主要なプログラミング言語：Go、Ruby、PHP、C#、C/C++、Rust、Swift、Dart など

🚀 汎用コンテキスト抽出方式により、主要なプログラミング言語で優れたコードレビュー品質を実現します。 Smart Context の対応言語は継続的に拡大しています。

対応 AI モデル

🚀 OpenRouter API キー 1 つだけで、以下のすべてのモデルを利用できます！

OpenAI モデル（OpenRouter または OpenAI API キー）

• gpt-5.2-codex：⭐ 推奨 - より高度な推論能力を備えた、最も高性能なエージェント型コーディングモデル（400K コンテキスト）

Anthropic モデル（OpenRouter または Anthropic API キー）

• claude-opus-4.6：⭐ 推奨 - 拡張思考機能を備えた最先端の推論モデル（1M コンテキスト）
• claude-sonnet-4.5：高度なコーディング向けに拡張思考機能を備えたハイブリッド推論モデル（1M コンテキスト）

Google モデル（OpenRouter または Google API キー）

• gemini-3-pro：⭐ 推奨 - 最も高度な推論モデル（1M+ トークン）
• gemini-3-flash：エージェント型ワークフロー向けの高速かつ高コストパフォーマンスなモデル（1M+ トークン）

🌟 OpenRouter 提供モデル（OpenRouter API キーのみ）

• minimax-m2.5（MiniMax）：⭐ 推奨 - コーディング向けの最先端オープンソースモデル（SWE-bench 80.2%、200K コンテキスト）
• glm-5（Zhipu AI）：複雑なシステム向けのフラッグシップ 745B MoE モデル（200K コンテキスト）
• qwen3-coder（Qwen）：コーディング特化モデル（262K コンテキスト）
• kimi-k2.5（Moonshot AI）：大規模コンテキスト処理モデル（262K コンテキスト）
• deepseek-r1-0528（DeepSeek）：推論特化モデル（163K コンテキスト）
• deepseek-v3-0324（DeepSeek）：高度な会話モデル（163K コンテキスト）

無料枠で利用可能なモデル：qwen3-coder-free、kimi-k2.5-free、deepseek-v3-0324-free、deepseek-r1-0528-free

📄 レビュー結果の保存形式

レビュー結果は、ターミナル出力と同時に構造化ファイルとして保存されます。

• 📋 Markdown 形式：概要、問題一覧、改善提案を含む、人が読みやすい明確な構成
• 🔧 JSON 形式：プログラムによる処理や他のツールとの連携向け

💡 詳細設定（開発者／コントリビューター向け）

git clone https://github.com/selvage-lab/selvage.git
cd selvage

# Install all development dependencies automatically
uv sync --dev --extra e2e

# Run
uv run selvage --help

git clone https://github.com/selvage-lab/selvage.git
cd selvage
pip install -e .

# Development dependencies only
uv sync --dev

# E2E test environment included
uv sync --dev --extra e2e

# Run tests
uv run pytest tests/

# Install with development dependencies (pytest, build, etc.)
pip install -e .[dev]

# Install with development + E2E test environment (testcontainers, docker, etc.)
pip install -e .[dev,e2e]

export OPENAI_API_KEY="your_openai_api_key_here"
export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
export GEMINI_API_KEY="your_gemini_api_key_here"

# Set default model to use (for advanced users)
selvage config model claude-sonnet-4-thinking

# Check configuration
selvage config list

# Enable debug mode (for troubleshooting and development)
selvage config debug-mode on

🔧 トラブルシューティング

インストールエラー

externally-managed-environment エラー（macOS/Linux）

# Solution 1: Use uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install selvage

# Solution 2: Use pipx
brew install pipx  # macOS
pipx install selvage

# Solution 3: Use virtual environment
python3 -m venv ~/.selvage-env
source ~/.selvage-env/bin/activate
pip install selvage

API キーのエラー

# Check environment variable
echo $OPENROUTER_API_KEY

# Permanent setup (Linux/macOS)
echo 'export OPENROUTER_API_KEY="your_key_here"' >> ~/.bashrc
source ~/.bashrc

モデルが見つからないエラー

# Check available model list
selvage models

# Use correct model name
selvage review --model claude-sonnet-4-thinking

ネットワーク接続エラー

# Retry ignoring cache
selvage review --skip-cache

# Check detailed info with debug mode
selvage config debug-mode on
selvage review

🤝 コントリビューション

Selvageはオープンソースプロジェクトです。皆さまからのコントリビューションをいつでも歓迎しています！バグ報告、機能の提案、ドキュメントの改善、コードの提供など、どのような形のコントリビューションも大切です。

コントリビューションの方法：

• 🐛 GitHub Issues でのバグ報告や機能の提案
• 🔧 プルリクエストによるコードの提供
• 📚 ドキュメントの改善や翻訳

詳しいコントリビューションガイドラインはCONTRIBUTING.mdをご覧ください。

📜 ライセンス

SelvageはApache License 2.0のもとで配布されています。このライセンスでは、包括的な特許保護と商標に関する制限のもと、商用利用、改変、再配布が認められています。

📋 変更履歴

Selvageのすべてのバージョン変更と新機能をご確認ください。

📋 変更履歴の全件を表示 →

新機能、バグ修正、パフォーマンスの改善など、各バージョンの詳しい変更内容をご確認いただけます。

📞 お問い合わせとコミュニティ

• 🐛 バグ報告と機能リクエスト：GitHub Issues
• 📧 直接のお問い合わせ：[email protected]

Selvageでより良いコードを書きましょう！ 🚀
⭐ このプロジェクトがお役に立ったら、GitHubでStarを付けてください！