{
  "markdown": "<h1 align=\"center\">Selvage: AI-Powered Code Review Automation Tool</h1>\n\n<p align=\"center\">🌐 <a href=\"README_KR.md\"><strong>한국어</strong></a></p>\n\n<p align=\"center\"><strong>A modern CLI tool that helps AI analyze Git diffs to improve code quality, find bugs, and identify security vulnerabilities.</strong></p>\n\n<p align=\"center\">🤖 <strong>AI Agents</strong>: Read our documentation at <code>https://selvage.ai/llms.txt</code></p>\n\n<p align=\"center\">\n  <a href=\"https://pypi.org/project/selvage/\"><img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/selvage\"></a>\n  <a href=\"LICENSE\"><img alt=\"License\" src=\"https://img.shields.io/badge/license-Apache--2.0-blue.svg\"></a>\n  <img alt=\"Python\" src=\"https://img.shields.io/badge/python-3.10+-blue\">\n  <img alt=\"AI Models\" src=\"https://img.shields.io/badge/AI-GPT--5.2%20%7C%20Claude%20%7C%20Gemini-green\">\n</p>\n\n<!-- TODO: Add demo GIF -->\n<!-- <p align=\"center\"> <img src=\"[Demo GIF URL]\" width=\"100%\" alt=\"Selvage Demo\"/> </p> -->\n\n<p align=\"center\">\n  <a href=\"https://pub-96dcfc8e21ae4525bb6f566e02497d31.r2.dev/assets/489282979-338766d9-535e-47cb-ad10-1f8ce069401d.mp4\" target=\"_blank\"><strong>▶ Watch Demo Video</strong></a>\n</p>\n\n**Selvage: Code reviews with an edge!**\n\nNo more waiting for reviews! AI instantly analyzes your code changes to provide quality improvements and bug prevention.\nWith smart context analysis (AST-based) that's accurate and cost-effective, plus multi-turn processing for large codebases - seamlessly integrated with all Git workflows.\n\n<details>\n<summary><strong>Table of Contents</strong></summary>\n\n- [✨ Key Features](#-key-features)\n- [🚀 Quick Start](#-quick-start)\n- [🎯 Practical Usage Guide](#-practical-usage-guide)\n  - [MCP Mode Usage](#mcp-mode-usage)\n  - [⌨️ CLI Usage](#️-cli-usage)\n- [🌐 Smart Context Analysis and Supported AI Models](#-smart-context-analysis-and-supported-ai-models)\n  - [🎯 Smart Context Analysis](#-smart-context-analysis)\n  - [Supported AI Models](#supported-ai-models)\n- [📄 Review Result Storage Format](#-review-result-storage-format)\n- [🔧 Troubleshooting](#-troubleshooting)\n- [🤝 Contributing](#-contributing)\n- [📜 License](#-license)\n- [📋 Change Log](#-change-log)\n- [📞 Contact and Community](#-contact-and-community)\n\n</details>\n\n## ✨ Key Features\n\n- **🤖 Multiple AI Model Support**: Leverage the latest LLM models including OpenAI GPT-5, Anthropic Claude Sonnet-4, Google Gemini, and more\n- **🔍 Git Workflow Integration**: Support for analyzing staged, unstaged, and changes between specific commits/branches\n- **🎯 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\n- **🔄 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)\n- **🤖 MCP Mode Support**: Register as MCP mode in Cursor, Claude Code, etc., and request code reviews through natural language like \"Review current changes\"\n- **🔌 Claude Code Plugin**: Install via marketplace with a single command — includes dedicated `/review` skill and `selvage-reviewer` agent for seamless integration\n- **🧠 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**\n- **📖 Open Source**: Freely use and modify under Apache-2.0 License\n\n## 🚀 Quick Start\n\n### Common Setup\n\n#### 1. Installation\n\n**Recommended Method (using uv)**\n\n```bash\n# Install uv (run once)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install Selvage\nuv tool install selvage\n```\n\n**Alternative Method (using pipx)**\n\n```bash\n# Install pipx (macOS)\nbrew install pipx\n\n# Install Selvage\npipx install selvage\n```\n\n**Traditional Method (pip)**\n\n```bash\n# ⚠️ May cause externally-managed-environment error on some systems\npip install selvage\n```\n\n**macOS/Linux users**: If you encounter errors with `pip install`, please use the uv or pipx methods above.\n\n#### 2. API Key Setup\n\nGet an API key from [OpenRouter](https://openrouter.ai) and set it up:\n\n```bash\nexport OPENROUTER_API_KEY=\"your_openrouter_api_key_here\"\n```\n\n### MCP Mode Usage (Recommended)\n\nRegister as MCP mode in Cursor, Claude Code, etc., to request code reviews through natural language.\n\n#### Cursor Integration\n\nRegister in Cursor's MCP configuration file (path may vary depending on user environment):\n\n**Common path:** `~/.cursor/mcp.json`\n\n```json\n// Method 1: Using environment variables (if already set)\n{\n  \"mcpServers\": {\n    \"selvage\": {\n      \"command\": \"uvx\",\n      \"args\": [\"selvage\", \"mcp\"]\n    }\n  }\n}\n\n// Method 2: Direct specification\n{\n  \"mcpServers\": {\n    \"selvage\": {\n      \"command\": \"uvx\",\n      \"args\": [\"selvage\", \"mcp\"],\n      \"env\": {\n        \"OPENROUTER_API_KEY\": \"your_openrouter_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Code Integration\n\n##### Method A: Plugin via Marketplace (Recommended)\n\nInstall the Selvage plugin from the marketplace to get the dedicated `/review` skill and `selvage-reviewer` agent:\n\n```bash\n# Step 1: Add Selvage marketplace\n/plugin marketplace add selvage-lab/selvage\n\n# Step 2: Install the plugin\n/plugin install selvage@selvage-lab-selvage\n```\n\nAfter installation, use the `/review` skill directly:\n\n```\n/review                      # Review unstaged changes\n/review staged               # Review staged changes\n/review branch main          # Review against main branch\n/review commit abc1234       # Review from specific commit\n```\n\n> 💡 **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.\n\n##### Method B: MCP Server Registration\n\n```bash\n# Method 1: Using environment variables (if already set)\nclaude mcp add selvage -- uvx selvage mcp\n\n# Method 2: Direct specification\nclaude mcp add selvage -e OPENROUTER_API_KEY=your_openrouter_api_key_here -- uvx selvage mcp\n```\n\n#### Usage\n\nAfter restarting your IDE, request reviews from your Coding Assistant:\n\n```\nPlease review current changes using selvage mcp\nReview changes between current branch and main branch using claude-sonnet-4-thinking with selvage mcp\n```\n\n🎉 **Done!** Selvage will analyze the code, review it, and deliver results through your Coding Assistant.\n\n### CLI Mode Usage\n\nFor direct terminal usage:\n\n```bash\nselvage review --model claude-sonnet-4-thinking\n```\n\n**💡 More Options:** [CLI Usage](#️-cli-usage) | [Practical Usage Guide](#-practical-usage-guide)\n\n---\n\n## 🎯 Practical Usage Guide\n\n### MCP Mode Usage\n\n#### Basic Usage\n\n```\n# Basic review request\nPlease review current changes using selvage mcp\n\n# Review staged changes\nReview staged work using gpt-5-high with selvage mcp\n\n# Review against specific branch\nReview current branch against main branch using selvage mcp\n\n# Review with automatic model selection\nReview current branch against main branch using selvage mcp, automatically selecting appropriate model\n```\n\n#### Agent-Delegated Review (No API Key Required)\n\nThe `get_review_context` tool returns structured review context so host agents can perform code reviews with their own LLM — **no Selvage API key needed**.\n\n```\n# Request agent-delegated review context\nGet review context for current changes using selvage mcp, then review the code\n\n# Agent-delegated review for staged changes\nGet review context for staged changes using selvage mcp\n\n# Agent-delegated review against branch\nGet review context comparing current branch to main using selvage mcp\n```\n\n> 💡 **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.\n\n#### Advanced Workflows\n\n**Multi-model Comparison Review**\n\n```\nReview staged work using both gpt-5-high and claude-sonnet-4-thinking with selvage mcp, then compare the results\n```\n\n**Stepwise Code Improvement Workflow**\n\n```\n1. Review current changes using claude-sonnet-4-thinking with selvage mcp\n2. Critically evaluate review feedback for validity against current codebase and set priorities\n3. Apply improvements sequentially based on established priorities\n```\n\n**CI/CD Integration Scenarios**\n\n```\n# Code quality verification before PR creation\nReview changes against main branch using selvage mcp for code quality verification before PR creation\n\n# Final check before deployment\nPerform comprehensive review of staged changes using selvage mcp for final check before deployment\n```\n\n### ⌨️ CLI Usage\n\nDirect terminal usage method. While MCP mode is recommended, CLI is useful for scripts and CI/CD.\n\n#### Configuring Selvage\n\n```bash\n# View all settings\nselvage config list\n\n# Set default model\nselvage config model <model_name>\n\n# Set default language\nselvage config language <language_name>\n\n```\n\n#### Code Review\n\n```bash\nselvage review [OPTIONS]\n```\n\n##### Key Options\n\n- `--repo-path <path>`: Git repository path (default: current directory)\n- `--staged`: Review only staged changes\n- `--target-commit <commit_id>`: Review changes from specific commit to HEAD (e.g., abc1234)\n- `--target-branch <branch_name>`: Review changes between current branch and specified branch (e.g., main)\n- `--model <model_name>`: AI model to use (e.g., claude-sonnet-4-thinking)\n- `--open-ui`: Automatically launch UI after review completion\n- `--no-print`: Don't output review results to terminal (terminal output enabled by default)\n- `--skip-cache`: Perform new review without using cache\n\n##### Usage Examples\n\n```bash\n# Review current working directory changes\nselvage review\n\n# Final check before commit\nselvage review --staged\n\n# Review specific files only\ngit add specific_files.py && selvage review --staged\n\n# Code review before sending PR\nselvage review --target-branch develop\n\n# Quick and economical review for simple changes\nselvage review --model gemini-2.5-flash\n\n# Review and then view detailed results in web UI\nselvage review --target-branch main --open-ui\n```\n\n#### Git Workflow Integration\n\n##### Team Collaboration Scenarios\n\n```bash\n# Code quality verification before Pull Request creation\nselvage review --target-branch main --model claude-sonnet-4-thinking\n\n# Pre-analysis of changes for code reviewers\nselvage review --target-branch develop --model claude-sonnet-4-thinking\n\n# Comprehensive review of all changes after specific commit\nselvage review --target-commit a1b2c3d --model claude-sonnet-4-thinking\n```\n\n##### Development Stage Quality Management\n\n```bash\n# Quick feedback during development (before WIP commit)\nselvage review --model gemini-2.5-flash\n\n# Final verification of staged changes (before commit)\nselvage review --staged --model claude-sonnet-4-thinking\n\n# Emergency review before hotfix deployment\nselvage review --target-branch main --model claude-sonnet-4-thinking\n```\n\n##### Large-scale Code Review\n\n```bash\n# Large codebases are automatically handled\nselvage review --model claude-sonnet-4  # Usage is the same, multi-turn processing automatically applied after detection\n```\n\nSelvage automatically handles large code changes that exceed LLM model context limits.\nOnce usage reaches roughly 200k tokens (tiktoken basis), Large Context Mode starts automatically, so just wait for it to complete.\n\n##### Cost Optimization\n\n```bash\n# Use economical models for small changes\nselvage review --model gemini-2.5-flash\n```\n\n#### Viewing Results\n\nReview results are **output directly to the terminal** and automatically saved to files simultaneously.\n\nFor **additional review management and re-examination**, you can use the web UI:\n\n```bash\n# Manage all saved review results in web UI\nselvage view\n\n# Run UI on different port\nselvage view --port 8502\n```\n\n**Key UI Features:**\n\n- 📋 Display list of all review results\n- 🎨 Markdown format display\n- 🗂️ JSON structured result view\n\n---\n\n## 🌐 Smart Context Analysis and Supported AI Models\n\n### 🎯 Smart Context Analysis\n\nSelvage uses **Tree-sitter based AST analysis** to precisely extract only the code blocks related to changed lines, **ensuring both cost efficiency and review quality simultaneously**.\n\n#### How Smart Context Works\n\n- **Precise Extraction**: Extracts only the minimal function/class blocks containing changed lines + related dependencies (imports, etc.)\n- **Cost Optimization**: Dramatically reduces token usage by sending only necessary context instead of entire files\n- **Quality Assurance**: Maintains high review accuracy through AST-based precise code structure understanding\n\n#### Smart Context Automatic Application\n\nSelvage analyzes file size and change scope to **automatically select the most efficient review method**:\n\n```\n🎯 Small Changes           → Fast and accurate analysis with Smart Context\n📄 Small Files            → Complete context understanding with full file analysis\n📋 Partial Edits in Large Files → Focused analysis of related code with Smart Context\n📚 Large Changes in Big Files   → Comprehensive review with full file analysis\n```\n\n> 💡 **Automatic Optimization**: The optimal analysis method for each situation is automatically applied without requiring any manual configuration.\n\n#### Smart Context Supported Languages\n\n- **Python**, **JavaScript**, **TypeScript**, **Java**, **Kotlin**\n\n#### Universal Context Extraction Support\n\n- **Major Programming Languages**: Go, Ruby, PHP, C#, C/C++, Rust, Swift, Dart, etc.\n\n> 🚀 **Universal context extraction method** provides **excellent code review quality** for major programming languages.\n> Smart Context supported languages are continuously expanding.\n\n---\n\n### Supported AI Models\n\n🚀 **Manage all models below with just one OpenRouter API key!**\n\n#### OpenAI Models (OpenRouter or OpenAI API Key)\n\n- **gpt-5.2-codex**: ⭐ **Recommended** - Most capable agentic coding model with stronger reasoning (400K context)\n\n#### Anthropic Models (OpenRouter or Anthropic API Key)\n\n- **claude-opus-4.6**: ⭐ **Recommended** - Frontier reasoning model with extended thinking (1M context)\n- **claude-sonnet-4.5**: Hybrid reasoning model with extended thinking for advanced coding (1M context)\n\n#### Google Models (OpenRouter or Google API Key)\n\n- **gemini-3-pro**: ⭐ **Recommended** - Most advanced reasoning model (1M+ tokens)\n- **gemini-3-flash**: High speed, high value model for agentic workflows (1M+ tokens)\n\n#### 🌟 OpenRouter Provided Models (OpenRouter API Key Only)\n\n- **minimax-m2.5** (MiniMax): ⭐ **Recommended** - State-of-the-art open-source model for coding (SWE-bench 80.2%, 200K context)\n- **glm-5** (Zhipu AI): Flagship 745B MoE model for complex systems (200K context)\n- **qwen3-coder** (Qwen): Coding-specialized model (262K context)\n- **kimi-k2.5** (Moonshot AI): Large context processing model (262K context)\n- **deepseek-r1-0528** (DeepSeek): Reasoning-specialized model (163K context)\n- **deepseek-v3-0324** (DeepSeek): Advanced conversation model (163K context)\n\n> Free tier models available: qwen3-coder-free, kimi-k2.5-free, deepseek-v3-0324-free, deepseek-r1-0528-free\n\n## 📄 Review Result Storage Format\n\nReview results are saved as **structured files** simultaneously with terminal output:\n\n- **📋 Markdown Format**: Clean structure that's easy for humans to read, including summary, issue list, and improvement suggestions\n- **🔧 JSON Format**: For programmatic processing and integration with other tools\n\n<p align=\"center\">\n  <img src=\"assets/demo-ui.png\" width=\"100%\" alt=\"Selvage UI Demo\"/>\n</p>\n\n## 💡 Advanced Settings (For Developers/Contributors)\n\n<details>\n<summary><strong>Development and Advanced Settings Options</strong></summary>\n\n### Development Version Installation\n\n#### Using uv (recommended)\n\n```bash\ngit clone https://github.com/selvage-lab/selvage.git\ncd selvage\n\n# Install all development dependencies automatically\nuv sync --dev --extra e2e\n\n# Run\nuv run selvage --help\n```\n\n#### Using pip\n\n```bash\ngit clone https://github.com/selvage-lab/selvage.git\ncd selvage\npip install -e .\n```\n\n### Development Environment Installation\n\n#### Using uv (recommended)\n\n```bash\n# Development dependencies only\nuv sync --dev\n\n# E2E test environment included\nuv sync --dev --extra e2e\n\n# Run tests\nuv run pytest tests/\n```\n\n#### Using pip\n\n```bash\n# Install with development dependencies (pytest, build, etc.)\npip install -e .[dev]\n\n# Install with development + E2E test environment (testcontainers, docker, etc.)\npip install -e .[dev,e2e]\n```\n\n### Individual Provider API Key Usage\n\nYou can also set individual provider API keys instead of OpenRouter:\n\n```bash\nexport OPENAI_API_KEY=\"your_openai_api_key_here\"\nexport ANTHROPIC_API_KEY=\"your_anthropic_api_key_here\"\nexport GEMINI_API_KEY=\"your_gemini_api_key_here\"\n```\n\n### Development and Debugging Settings\n\n```bash\n# Set default model to use (for advanced users)\nselvage config model claude-sonnet-4-thinking\n\n# Check configuration\nselvage config list\n\n# Enable debug mode (for troubleshooting and development)\nselvage config debug-mode on\n```\n\n</details>\n\n## 🔧 Troubleshooting\n\n### Installation Errors\n\n**`externally-managed-environment` Error (macOS/Linux)**\n\n```bash\n# Solution 1: Use uv (recommended)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nuv tool install selvage\n\n# Solution 2: Use pipx\nbrew install pipx  # macOS\npipx install selvage\n\n# Solution 3: Use virtual environment\npython3 -m venv ~/.selvage-env\nsource ~/.selvage-env/bin/activate\npip install selvage\n```\n\n### API Key Errors\n\n```bash\n# Check environment variable\necho $OPENROUTER_API_KEY\n\n# Permanent setup (Linux/macOS)\necho 'export OPENROUTER_API_KEY=\"your_key_here\"' >> ~/.bashrc\nsource ~/.bashrc\n```\n\n**Model not found Error**\n\n```bash\n# Check available model list\nselvage models\n\n# Use correct model name\nselvage review --model claude-sonnet-4-thinking\n```\n\n**Network Connection Error**\n\n```bash\n# Retry ignoring cache\nselvage review --skip-cache\n\n# Check detailed info with debug mode\nselvage config debug-mode on\nselvage review\n```\n\n## 🤝 Contributing\n\nSelvage is an open-source project and we always welcome your contributions! Bug reports, feature suggestions, documentation improvements, code contributions - any form of contribution is appreciated.\n\n**How to Contribute:**\n\n- 🐛 Bug reports or feature suggestions on [GitHub Issues](https://github.com/selvage-lab/selvage/issues)\n- 🔧 Code contributions through Pull Requests\n- 📚 Documentation improvements and translations\n\n**Detailed contribution guidelines can be found in [CONTRIBUTING.md](CONTRIBUTING.md).**\n\n## 📜 License\n\nSelvage is distributed under the [Apache License 2.0](LICENSE). This license permits commercial use, modification, and distribution, with comprehensive patent protection and trademark restrictions included.\n\n## 📋 Change Log\n\nCheck out all version changes and new features of Selvage.\n\n**[📋 View Complete Change Log →](CHANGELOG.md)**\n\nYou can find detailed changes for each version, including new features, bug fixes, and performance improvements.\n\n## 📞 Contact and Community\n\n- **🐛 Bug Reports and Feature Requests**: [GitHub Issues](https://github.com/selvage-lab/selvage/issues)\n- **📧 Direct Contact**: contact@selvage.me\n\n---\n\n<p align=\"center\">\n  <strong>Write better code with Selvage! 🚀</strong><br>\n  ⭐ If this project helped you, please give us a Star on GitHub!\n</p>\n\n<!-- mcp-name: io.github.selvage-lab/selvage -->\n",
  "bytes": 19630,
  "sha": "5d7b3fcf01756347f91d29d91feda5f1e5e264ac553c421c3d9be55212569b34",
  "repo_slug": "selvage-lab/selvage",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_selvage_lab_selvage_7a47f5d7/readme"
}