🛠 Code Review Buddy

Code Review Buddy is an AI-powered CLI tool that reviews your staged Git changes before you commit. It detects bugs, security issues, secrets, and code smells, then suggests improvements and a commit message. It supports interactive and non-interactive modes, beautiful output, and is easy to integrate into any workflow or Git hook.

✨ Features

• 🤖 AI-Powered Analysis: Uses OpenRouter (GPT-4, Claude, Gemini, etc.) to review your code diffs
• 🔍 Secret & Issue Detection: Finds bugs, security vulnerabilities, hardcoded secrets (API keys, tokens, private keys), and code smells
• 📊 Quality Scoring: Assigns a 0-100 score, configurable threshold, and per-file breakdown
• 🖼️ Beautiful Output: Boxen summaries, color-coded CLI, and export to JSON, Markdown, or HTML
• 🗂️ Per-File Review: Optionally runs AI review on each staged file for granular feedback
• 🕹️ Interactive Mode: Accept/ignore/fix-later for each issue, with commit message editing
• 🪝 Git Hook Ready: Easy integration with Husky or manual hooks
• 🛡️ Configurable: .reviewbuddyrc for ignore patterns, custom scoring, and output settings
• 🕰️ History & Analytics: Tracks review history and summarizes recent code quality

📦 Installation

1. Global Install (Recommended)

npm install -g code-review-buddy

2. Local Project Install

npm install --save-dev code-review-buddy

3. From Source (Development)

git clone https://github.com/kammounmedaziz/code-review-buddy.git
cd code-review-buddy
npm install
npm link  # Optional: makes CLI available globally

⚙️ Configuration

1. Environment Variables (.env)

Create a .env file in your project root:

OPENROUTER_API_KEY=sk-or-v1-your-api-key-here   # Required
AI_MODEL=gpt-4o-mini                            # Optional (default: gpt-4o-mini)
REVIEW_SCORE_THRESHOLD=70                       # Optional (default: 0)
MAX_TOKENS=1200                                 # Optional
DEBUG=false                                     # Optional

2. Project Config (.reviewbuddyrc)

Create a .reviewbuddyrc JSON file to customize ignore patterns, scoring, and output:

{
   "ignore": ["**/secrets/**", "*.test.js"],
   "scoring": { "security": 30, "bug": 10 },
   "output": { "format": "markdown", "outFile": "review.md" },
   "history": { "enabled": true, "file": ".code-review-buddy/history.json" }
}

3. Get Your OpenRouter API Key

1. Visit OpenRouter.ai
2. Sign up and generate an API key
3. Add credits (pay-as-you-go)
4. Add your key to .env

🚀 Usage

1. Stage Your Changes

git add .

2. Run the Code Review

# Basic review
code-review-buddy

# Interactive mode (default)
code-review-buddy --interactive

# Per-file AI review (granular feedback)
code-review-buddy --per-file

# Output as JSON, Markdown, or HTML
code-review-buddy --format json --out review.json
code-review-buddy --format markdown --out review.md
code-review-buddy --format html --out review.html

# Force commit even if score is low
code-review-buddy --force

# Debug mode (see raw AI responses)
code-review-buddy --debug

CLI Options

Option	Description
-i, --interactive	Enable interactive mode (accept/ignore/fix-later)
--no-interactive	Disable interactive mode
-f, --force	Force commit even if score is below threshold
-d, --debug	Enable debug logging (saves AI responses to files)
--no-commit	Skip automatic commit message application
-F, --format	Output format: box, json, markdown, html
-o, --out	Output file path for reports
-p, --per-file	Analyze each staged file individually (per-file AI)
--no-history	Disable writing to review history
-V, --version	Output the version number
-h, --help	Display help information

🪝 Git Hook Setup

Automatic Review Before Every Commit

Option 1: Using Husky (Recommended)

# Install husky
npm install --save-dev husky

# Initialize husky
npx husky init

# Create pre-commit hook
echo "code-review-buddy" > .husky/pre-commit
chmod +x .husky/pre-commit

Option 2: Manual Git Hook

# Navigate to your project
cd your-project

# Create pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
code-review-buddy
EOF

# Make it executable
chmod +x .git/hooks/pre-commit

Option 3: Custom Git Hooks Directory

# Create hooks directory
mkdir -p .githooks

# Create pre-commit hook
cat > .githooks/pre-commit << 'EOF'
#!/bin/sh
code-review-buddy
EOF

# Configure git to use custom hooks directory
git config core.hooksPath .githooks

# Make executable
chmod +x .githooks/pre-commit

Bypass Hook When Needed

# Skip the review for emergency commits
git commit --no-verify -m "emergency fix"

# Or use the force flag
code-review-buddy --force

📊 Scoring & Issue Types

Code Review Buddy assigns a quality score from 0-100 based on detected issues:

Issue Type	Score Penalty	Example
🔐 Secret	-40 points	Exposed API keys, passwords
🔒 Security	-25 points	SQL injection, XSS vulnerabilities
🐛 Bug	-15 points	Null pointers, logic errors
⚡ Performance	-10 points	Inefficient loops, memory leaks
🎨 Style	-5 points	Formatting, naming conventions

Score Interpretation:

• 90-100: Excellent code quality ✅
• 70-89: Good code with minor issues ⚠️
• 50-69: Moderate issues, improvements needed 🔧
• 0-49: Significant issues, refactoring recommended ❌

🧪 Testing

Run All Tests

npm test

Test Coverage

The test suite covers:

• Interactive mode and CLI helpers
• Ora spinner/progress indicators
• Secret detection (API keys, tokens, private keys)
• Output formatters (JSON, Markdown, HTML)
• Config ignore patterns and merging
• History persistence and summarization

📖 How It Works

1. Stage Changes: Use git add to stage files
2. Run Review: Execute code-review-buddy
3. AI Analysis: Sends diff to OpenRouter AI
4. Parse Results: Extracts issues and suggestions
5. Score Calculation: Applies penalties based on issue types
6. Threshold Check: Compares score to configured threshold
7. Report: Displays formatted results with colors
8. Auto-Commit Message: Applies AI-suggested commit message (optional)

🎨 Output Example

══════════════════════════════════════════════════════════════
  📊 Code Review Results
══════════════════════════════════════════════════════════════

🏆 Quality Score: 75/100
📌 Suggested Commit: fix: add null check and improve error handling
⚙️  Threshold: 70/100

⚠  2 Issues Found
   Summary: 🐛 1 bug, ⚡ 1 performance

────────────────────────────────────────────────────────────
🐛 Null pointer exception [HIGH]
   📁 src/utils.js : line 45
   💡 Variable 'user' may be null before accessing properties
   ✨ Add null check before accessing user.name

────────────────────────────────────────────────────────────
⚡ Inefficient array operation [MEDIUM]
   📁 src/service.js : line 120
   💡 Using nested loops causes O(n²) complexity
   ✨ Replace with Map for O(n) lookup performance

══════════════════════════════════════════════════════════════

🔧 Troubleshooting

Common Issues

Issue: Missing credentials error

# Solution: Make sure .env file exists and contains OPENROUTER_API_KEY
cp .env.example .env
# Edit .env and add your API key

Issue: No staged changes found

# Solution: Stage files before running
git add .
code-review-buddy

Issue: AI returns invalid JSON

# Solution: Use debug mode to see raw response
code-review-buddy --debug
# Check debug-ai-response-*.json file

Issue: Score always blocks commits

# Solution 1: Lower threshold in .env
REVIEW_SCORE_THRESHOLD=50

# Solution 2: Use force flag
code-review-buddy --force

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/kammounmedaziz/code-review-buddy.git
cd code-review-buddy
npm install
cp .env.example .env
# Add your API key to .env
npm link

📄 License

MIT © kammounmedaziz

📞 Support

• 🐛 Report a Bug
• 💡 Request a Feature
• 💬 Discussions

---

Made with ❤️ by developers, for developers