Selvage: AI 기반 코드 리뷰 자동화 도구
🌐 English
Git diff를 AI가 분석하여 코드 품질 향상, 버그 발견, 보안 취약점 식별을 도와주는 현대적인 CLI 도구입니다.
🤖 AI Agents: Read our documentation at https://selvage.ai/llms.txt
▶ 데모 영상 보기
**Selvage: 코드 리뷰도 엣지있게!**
더 이상 리뷰를 기다리지 마세요. AI가 코드 변경사항을 즉시 분석하여 품질 개선과 버그 예방을 제공합니다.
스마트 컨텍스트 분석(AST 기반)으로 정확하고 비용 효율적이며, 멀티턴 처리로 대용량까지 - 모든 Git 워크플로우에 완벽 통합됩니다.
Table of Contents
- [✨ 주요 기능](#-주요-기능)
- [🚀 빠른 시작](#-빠른-시작)
- [🎯 실전 활용 가이드](#-실전-활용-가이드)
- [MCP 모드 사용 방법](#mcp-모드-사용-방법)
- [⌨️ CLI 사용법](#️-cli-사용법)
- [🌐 Smart Context 분석 및 지원 AI 모델](#-smart-context-분석-및-지원-ai-모델)
- [Smart Context 분석](#-smart-context-분석)
- [지원 AI 모델](#지원-ai-모델)
- [📄 리뷰 결과 저장 형식](#-리뷰-결과-저장-형식)
- [🔧 문제 해결](#-문제-해결)
- [🤝 기여하기](#-기여하기)
- [📜 라이선스](#-라이선스)
- [📋 업데이트 이력](#-업데이트-이력)
- [📞 문의 및 커뮤니티](#-문의-및-커뮤니티)
## ✨ 주요 기능
- **🤖 다양한 AI 모델 지원**: OpenAI GPT-5, Anthropic Claude Sonnet-4, Google Gemini 등 최신 LLM 모델 활용
- **🔍 Git 워크플로우와 통합**: staged, unstaged, 특정 커밋/브랜치 간 변경사항 분석 지원
- **🎯 최적화된 컨텍스트 분석**: Tree-sitter 기반 AST 분석을 통해 변경 라인이 속하는 가장 작은 코드 블록과 dependency statement를 자동 추출하여 상황에 따라 최적화된 컨텍스트 제공
- **🔄 자동 멀티턴 처리**: 컨텍스트 제한 초과 시 프롬프트를 자동 분할하여 안정적인 대용량 코드 리뷰 지원 (총 토큰이 약 200k(tiktoken 기준)을 넘으면 LLM 오류 여부와 관계없이 자동으로 Large Context Mode 실행)
- **🤖 MCP 모드 지원**: Cursor, Claude Code 등에 MCP 모드로 등록하여 "현재 변경사항 리뷰해줘" 같은 자연어로 대화하며 코드 리뷰 요청
- **🔌 Claude Code 플러그인**: 마켓플레이스에서 한 줄 명령으로 설치 — 전용 `/review` 스킬과 `selvage-reviewer` 에이전트 포함
- **🧠 Agent-Delegated Review (`get_review_context`)**: diff + Smart Context + 시스템 프롬프트를 구조화된 컨텍스트로 반환하여 호스트 에이전트(Claude Code, Cursor, Antigravity 등)가 자체 LLM으로 코드 리뷰 수행 — **API 키 불필요**
- **📖 오픈소스**: Apache-2.0 라이선스로 자유롭게 사용 및 수정 가능
## 🚀 빠른 시작
### 공통 준비
#### 1. 설치
**권장 방법 (uv 사용)**
```bash
# uv 설치 (한 번만 실행)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Selvage 설치
uv tool install selvage
```
**대안 방법 (pipx 사용)**
```bash
# pipx 설치 (macOS)
brew install pipx
# Selvage 설치
pipx install selvage
```
**전통적 방법 (pip)**
```bash
# ⚠️ 일부 환경에서 externally-managed-environment 에러 발생 가능
pip install selvage
```
**macOS/Linux 사용자**: `pip install` 시 에러가 발생하면 위의 uv 또는 pipx 방법을 사용해주세요.
#### 2. API 키 설정
[OpenRouter](https://openrouter.ai)에서 API 키를 발급받아 설정하세요:
```bash
export OPENROUTER_API_KEY="your_openrouter_api_key_here"
```
### MCP 모드 사용 (권장)
Cursor, Claude Code 등에 MCP 모드로 등록하여 자연어로 코드 리뷰를 요청할 수 있습니다.
#### Cursor 연동
Cursor의 MCP 설정 파일에 등록 (경로는 사용자 환경에 따라 다를 수 있음):
**일반적인 경로:** `~/.cursor/mcp.json`
```json
// 방법 1: 환경변수 사용 (이미 설정한 경우)
{
"mcpServers": {
"selvage": {
"command": "uvx",
"args": ["selvage", "mcp"]
}
}
}
// 방법 2: 직접 지정
{
"mcpServers": {
"selvage": {
"command": "uvx",
"args": ["selvage", "mcp"],
"env": {
"OPENROUTER_API_KEY": "your_openrouter_api_key_here"
}
}
}
}
```
#### Claude Code 연동
##### 방법 A: 마켓플레이스 플러그인 설치 (권장)
Selvage 플러그인을 마켓플레이스에서 설치하면 전용 `/review` 스킬과 `selvage-reviewer` 에이전트를 사용할 수 있습니다:
```bash
# 1단계: Selvage 마켓플레이스 추가
/plugin marketplace add selvage-lab/selvage
# 2단계: 플러그인 설치
/plugin install selvage@selvage-lab-selvage
```
설치 후 `/review` 스킬로 바로 리뷰 가능:
```
/review # unstaged 변경사항 리뷰
/review staged # staged 변경사항 리뷰
/review branch main # main 브랜치와 비교 리뷰
/review commit abc1234 # 특정 커밋부터 리뷰
```
> 💡 **API 키 불필요!** 플러그인은 `get_review_context`를 사용하여 Claude Code 자체 LLM으로 코드 리뷰를 수행하므로 외부 API 키가 필요 없습니다.
##### 방법 B: MCP 서버 등록
```bash
# 방법 1: 환경변수 사용 (이미 설정한 경우)
claude mcp add selvage -- uvx selvage mcp
# 방법 2: 직접 지정
claude mcp add selvage -e OPENROUTER_API_KEY=your_openrouter_api_key_here -- uvx selvage mcp
```
#### 사용법
IDE를 재시작 후 Coding Assistant에게 리뷰를 요청해보세요:
```
selvage mcp로 현재 변경사항 리뷰해줘
selvage mcp로 현재 브랜치와 main 브랜치 변경 내용을 claude-sonnet-4-thinking으로 리뷰해줘
```
🎉 **완료!** Selvage가 코드를 분석해 리뷰하고, Coding Assistant로 전달해줍니다.
### CLI 모드 사용
터미널에서 직접 사용하려면:
```bash
selvage review --model claude-sonnet-4-thinking
```
**💡 더 많은 옵션:** [CLI 사용법](#️-cli-사용법) | [실전 활용 가이드](#-실전-활용-가이드)
---
## 🎯 실전 활용 가이드
### MCP 모드 사용 방법
#### 기본 사용법
```
# 기본 리뷰 요청
selvage mcp로 현재 변경사항 리뷰해줘
# 스테이징된 변경사항 리뷰
selvage mcp로 스테이징된 작업 내용을 gpt-5-high로 리뷰해줘
# 특정 브랜치와 비교 리뷰
selvage mcp로 메인 브랜치와 현재 브랜치를 비교해서 리뷰해줘
# 모델 자동 선택 리뷰
selvage mcp로 메인 브랜치와 현재 브랜치를 리뷰하되 사용 모델을 확인해서 선정해서 리뷰해줘
```
#### Agent-Delegated Review (API 키 불필요)
`get_review_context` 도구는 구조화된 리뷰 컨텍스트를 반환하여 호스트 에이전트가 자체 LLM으로 코드 리뷰를 수행할 수 있습니다 — **Selvage API 키 불필요**.
```
# 에이전트 위임 리뷰 컨텍스트 요청
selvage mcp로 현재 변경사항의 리뷰 컨텍스트를 가져와서 코드 리뷰해줘
# staged 변경사항 에이전트 위임 리뷰
selvage mcp로 스테이징된 변경사항의 리뷰 컨텍스트를 가져와줘
# 브랜치 비교 에이전트 위임 리뷰
selvage mcp로 현재 브랜치와 main 비교 리뷰 컨텍스트를 가져와줘
```
> 💡 **작동 원리**: Selvage가 diff + AST 기반 Smart Context + 시스템 프롬프트를 추출하고 구조화된 컨텍스트로 반환합니다. 호스트 에이전트(Claude Code, Cursor, Antigravity 등)가 자체 LLM으로 직접 리뷰를 수행하므로 외부 API 키가 필요 없습니다.
#### 고급 워크플로우
**멀티 모델 비교 리뷰**
```
selvage mcp로 스테이징된 작업 내용을 gpt-5-high, claude-sonnet-4-thinking으로 각각 리뷰하고 결과를 비교해줘
```
**단계별 코드 개선 워크플로우**
```
1. selvage mcp로 현재 변경사항을 claude-sonnet-4-thinking으로 리뷰해줘
2. 리뷰 피드백이 현재 코드베이스에 관해 유효한지 비판적으로 검토 후 우선순위를 알려줘
3. 검토한 내역을 우선순위에 따라 순차적으로 반영해줘
```
**CI/CD 통합 시나리오**
```
# PR 생성 전 코드 품질 검증
selvage mcp로 PR 생성 전 코드 품질 검증을 위해 main 브랜치 대비 변경사항을 리뷰해줘
# 배포 전 최종 체크
selvage mcp로 배포 전 최종 체크를 위해 스테이징된 변경사항을 종합적으로 리뷰해줘
```
### ⌨️ CLI 사용법
터미널에서 직접 사용하는 방법입니다. MCP 모드 사용을 권장하지만, 스크립트나 CI/CD에서는 CLI가 유용합니다.
#### Selvage 설정하기
```bash
# 모든 설정 보기
selvage config list
# 기본 모델 설정
selvage config model <모델명>
# 기본 언어 설정
selvage config language <언어명>
```
#### 코드 리뷰하기
```bash
selvage review [OPTIONS]
```
##### 주요 옵션
- `--repo-path <경로>`: Git 저장소 경로 (기본값: 현재 디렉토리)
- `--staged`: 스테이징된 변경사항만 리뷰
- `--target-commit <커밋ID>`: 특정 커밋부터 HEAD까지의 변경사항 리뷰 (예: abc1234)
- `--target-branch <브랜치명>`: 현재 브랜치와 지정된 브랜치 간 변경사항 리뷰 (예: main)
- `--model <모델명>`: 사용할 AI 모델 (예: claude-sonnet-4-thinking)
- `--open-ui`: 리뷰 완료 후 자동으로 UI 실행
- `--no-print`: 터미널에 리뷰 결과를 출력하지 않음 (기본적으로 터미널 출력 활성화)
- `--skip-cache`: 캐시를 사용하지 않고 새로운 리뷰 수행
##### 사용 예시
```bash
# 현재 워킹 디렉토리 변경사항 리뷰
selvage review
# 커밋 전 최종 점검
selvage review --staged
# 특정 파일들만 리뷰
git add specific_files.py && selvage review --staged
# PR 보내기 전 코드 리뷰
selvage review --target-branch develop
# 빠르고 경제적인 모델로 간단한 변경사항 리뷰
selvage review --model gemini-2.5-flash
# 리뷰 후 웹 UI로 자세히 확인
selvage review --target-branch main --open-ui
```
#### Git 워크플로우 활용
##### 팀 협업 시나리오
```bash
# Pull Request 생성 전 코드 품질 검증
selvage review --target-branch main --model claude-sonnet-4-thinking
# 코드 리뷰어를 위한 변경사항 사전 분석
selvage review --target-branch develop --model claude-sonnet-4-thinking
# 특정 커밋 이후 모든 변경사항 종합 리뷰
selvage review --target-commit a1b2c3d --model claude-sonnet-4-thinking
```
##### 개발 단계별 품질 관리
```bash
# 개발 중 빠른 피드백 (WIP 커밋 전)
selvage review --model gemini-2.5-flash
# 스테이징된 변경사항 최종 검증 (커밋 전)
selvage review --staged --model claude-sonnet-4-thinking
# 핫픽스 배포 전 긴급 검토
selvage review --target-branch main --model claude-sonnet-4-thinking
```
##### 대용량 코드 리뷰
```bash
# 대용량 코드베이스도 자동으로 처리
selvage review --model claude-sonnet-4 # 사용 방법은 동일, 자동 감지 후 멀티턴 처리 적용
```
Selvage는 LLM model의 컨텍스트 제한을 초과하는 대용량 코드 변경사항도 처리합니다.
토큰 사용량이 tiktoken 기준으로 약 200k에 도달하면 Large Context Mode가 자동으로 실행되므로 결과를 기다려주세요.
##### 비용 최적화
```bash
# 작은 변경사항에는 경제적인 모델 사용
selvage review --model gemini-2.5-flash
```
#### 결과 확인하기
리뷰 결과는 **터미널에 바로 출력**되며, 동시에 파일로도 자동 저장됩니다.
**추가적인 리뷰 관리 및 재확인**을 위해 웹 UI를 사용할 수 있습니다:
```bash
# 저장된 모든 리뷰 결과를 웹 UI로 관리
selvage view
# 다른 포트에서 UI 실행
selvage view --port 8502
```
**UI 주요 기능:**
- 📋 모든 리뷰 결과 목록 표시
- 🎨 마크다운 형식 표시
- 🗂️ JSON 구조화된 결과 보기
---
## 🌐 Smart Context 추출 및 지원 AI 모델
### 🎯 Smart Context 추출
Selvage는 **Tree-sitter 기반 AST 분석**을 통해 변경된 라인과 관련된 코드 블록만 정확히 추출하여, **비용 효율성과 리뷰 품질을 동시에 보장**합니다.
#### Smart Context 작동 방식
- **정밀 추출**: 변경된 라인이 속한 최소 함수/클래스 블록 + 관련 의존성(import 등)만 추출
- **비용 최적화**: 전체 파일 대신 필요한 컨텍스트만 전송하여 토큰 사용량 대폭 절감
- **품질 보장**: AST 기반 정확한 코드 구조 이해로 높은 리뷰 정확도 유지
#### Smart Context 자동 적용
Selvage는 파일 크기와 변경 범위를 분석하여 **가장 효율적인 리뷰 방식을 자동 선택**합니다:
```
🎯 작은 변경사항 → Smart Context로 빠르고 정확한 분석
📄 작은 파일 → 전체 파일 분석으로 완전한 맥락 파악
📋 큰 파일의 부분 수정 → Smart Context로 관련 코드만 집중 분석
📚 큰 파일의 대규모 변경 → 전체 파일 분석으로 종합적 검토
```
> 💡 **자동 최적화**: 별도 설정 없이 상황에 맞는 최적의 분석 방식이 자동 적용됩니다.
#### Smart Context 지원 언어
- **Python**, **JavaScript**, **TypeScript**, **Java**, **Kotlin**
#### 범용 컨텍스트 추출 지원 언어
- **주요 프로그래밍 언어**: Go, Ruby, PHP, C#, C/C++, Rust, Swift, Dart 등
> 🚀 **범용 컨텍스트 추출 방식**으로 주요 프로그래밍 언어에서 **우수한 코드 리뷰 품질**을 제공합니다.
> Smart Context 지원 언어는 지속적으로 추가하고 있습니다.
---
### 지원 AI 모델
🚀 **OpenRouter API 키 하나로 아래 모든 모델을 통합 관리하세요!**
#### 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 형식**: 프로그래밍 방식 처리 및 다른 도구와의 통합에 활용
## 💡 고급 설정 (개발자/기여자용)
개발 및 고급 설정 옵션
### 개발 버전 설치
#### uv 사용 (권장)
```bash
git clone https://github.com/selvage-lab/selvage.git
cd selvage
# 모든 개발 의존성 자동 설치
uv sync --dev --extra e2e
# 실행
uv run selvage --help
```
#### 기존 pip 사용
```bash
git clone https://github.com/selvage-lab/selvage.git
cd selvage
pip install -e .
```
### 개발 환경 설치
#### uv 방식 (권장)
```bash
# 개발 의존성만
uv sync --dev
# E2E 테스트 환경 포함
uv sync --dev --extra e2e
# 실행
uv run pytest tests/
```
#### pip 방식
```bash
# 개발 의존성 포함 설치 (pytest, build 등)
pip install -e .[dev]
# 개발 + E2E 테스트 환경 설치 (testcontainers, docker 등)
pip install -e .[dev,e2e]
```
### 개별 Provider API 키 사용
OpenRouter 대신 각 provider API 키를 개별 설정할 수도 있습니다:
```bash
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"
```
### 개발 및 디버깅 설정
```bash
# 기본 사용할 모델 설정 (고급 사용자)
selvage config model claude-sonnet-4-thinking
# 설정 확인
selvage config list
# 디버그 모드 활성화 (문제 해결 및 개발시 사용)
selvage config debug-mode on
```
## 🔧 문제 해결
### 설치 관련 오류
**`externally-managed-environment` 에러 (macOS/Linux)**
```bash
# 해결 방법 1: uv 사용 (권장)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install selvage
# 해결 방법 2: pipx 사용
brew install pipx # macOS
pipx install selvage
# 해결 방법 3: 가상환경 사용
python3 -m venv ~/.selvage-env
source ~/.selvage-env/bin/activate
pip install selvage
```
### API 키 오류
```bash
# 환경변수 확인
echo $OPENROUTER_API_KEY
# 영구 설정 (Linux/macOS)
echo 'export OPENROUTER_API_KEY="your_key_here"' >> ~/.bashrc
source ~/.bashrc
```
**모델 not found 오류**
```bash
# 사용 가능한 모델 목록 확인
selvage models
# 모델명 정확히 확인하여 사용
selvage review --model claude-sonnet-4-thinking
```
**네트워크 연결 오류**
```bash
# 캐시 무시하고 재시도
selvage review --skip-cache
# 디버그 모드로 상세 정보 확인
selvage config debug-mode on
selvage review
```
## 🤝 기여하기
Selvage는 오픈소스 프로젝트이며, 여러분의 기여를 언제나 환영합니다! 버그 리포트, 기능 제안, 문서 개선, 코드 기여 등 어떤 형태의 기여든 좋습니다.
**기여 방법:**
- 🐛 [GitHub Issues](https://github.com/selvage-lab/selvage/issues)에서 버그 리포트 또는 기능 제안
- 🔧 Pull Request를 통한 코드 기여
- 📚 문서 개선 및 번역
**상세한 기여 가이드라인은 [CONTRIBUTING.md](CONTRIBUTING.md)에서 확인하실 수 있습니다.**
## 📜 라이선스
Selvage는 [Apache License 2.0](LICENSE) 하에 배포됩니다. 이 라이선스는 상업적 이용, 수정, 배포를 허용하며, 특허 보호 및 상표권 제한을 포함한 포괄적인 오픈소스 라이선스입니다.
## 📋 업데이트 이력
Selvage의 모든 버전 변경사항과 새로운 기능을 확인하세요.
**[📋 전체 업데이트 이력 보기 →](CHANGELOG.md)**
새로운 기능, 버그 수정, 성능 개선 사항 등 각 버전별 상세한 변경 내역을 확인할 수 있습니다.
## 📞 문의 및 커뮤니티
- **🐛 버그 리포트 및 기능 요청**: [GitHub Issues](https://github.com/selvage-lab/selvage/issues)
- **📧 직접 문의**: contact@selvage.me
---
Selvage와 함께 더 나은 코드를 작성하세요! 🚀
⭐ 프로젝트가 도움이 되셨다면 GitHub에서 Star를 눌러주세요!