Review Buddy AI 🤖✨

🆕 New Feature: You can now CHAT with Review Buddy! Just reply to any comment with /buddy to ask questions or debate the review. 💬

Review Buddy is an intelligent, AI-powered GitHub Action that acts as your personal pair programmer. It doesn't just review your code—it understands it.

What does it do?

Review Buddy automates the boring parts of Code Review:

1. Code Quality & Comments: It reviews your code line-by-line using AI to find bugs, security risks, and bad practices. (Note: It performs static AI analysis, it does NOT run your unit tests).
2. Smart Metadata Updates:
   • PR Title: Renames your PR to follow Conventional Commits (e.g., fix: login bug instead of update).
   • Description: Writes a full, formatted description (Summary, Changes, Testing Guide) if you didn't provides one.
   • Labels: Automatically adds relevant labels based on change type, quality score, and detected issues.
3. Best Practices Suggestions: Identifies code patterns that can be improved with modern best practices (e.g., if (a == undefined) → if (!a), using const/let instead of var, arrow functions, template literals, etc.) with before/after examples.
4. Engaging Feedback: comments on your PR in your chosen tone (Professional or Roast).
5. Final Recommendation: Provides a clear recommendation (Approve/Request Changes/Reject) with actionable next steps for reviewers.
6. Interactive Chat: Reply to any comment with /Buddy (e.g., "Why is this wrong? /Buddy") and Review Buddy will explain!

---

🚀 Quick Start

Copy this into .github/workflows/review_buddy.yml:

name: Review Buddy
on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]
permissions:
    pull-requests: write
    contents: read
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nexoral/ReviewBuddy@main
        with:
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}

💰 Cost-Efficient: Small PRs get reviewed in a single AI call. Large PRs automatically split into a bounded per-file review (hard-capped file count, budget-aware) instead of one giant prompt — cost scales predictably, never unbounded.

🧠 Full-Repo Context: Review Buddy checks out your repo and reviews full-file, import-aware context — not just a bare diff — so it doesn't hallucinate architecture from 3 lines of surrounding code.

🔌 Multi-Provider: Supports Gemini (default), OpenRouter (access 100+ models), and GitHub Models. Bring your own API key and model!

🚀 Simple & Smart: Just add one API key with a small config file, and your Repo PR becomes smarter!

💡 Why I Built This

Let's be honest—writing PR descriptions is boring. We often push code with titles like "update" and leave the description empty, forcing reviewers to dig through files to guess what's happening.

I built Review Buddy to solve this:

• Context is King: It forces every PR to have a clear, descriptive summary so reviewers know exactly what they are looking at immediately.
• Standardization: It enforces clean titles and robust descriptions without any manual user effort.
• Decision Support: Reviewers no longer have to wonder "should I approve this?" - Review Buddy provides clear, data-driven recommendations.
• Fun Factor: Code reviews can be dry. Adding a "Hinglish Roast" mode makes the process engaging and bringing the team closer together through humor.

---

🚀 Features

• 🧠 Full-Repo Context Awareness: Instead of reviewing a bare diff (3 lines of context per change), Review Buddy checks out your repo and builds a full-file, import-aware view of every changed file — plus a one-hop "repo map" of the local files it imports — so the AI reasons from real code and architecture, not fragments.
• 📈 Scales to Massive PRs: Small PRs are reviewed in one AI call. Large PRs (or PRs that exceed your model's context window) automatically split into a per-file map step + one synthesis step, with a hard cap on files reviewed per run and bounded concurrency — cost and reliability stay predictable regardless of PR or repo size. Lockfiles, dist/, node_modules/, and other generated/binary files are filtered out automatically.
• 💬 Smarter /buddy Follow-ups: Replies reuse the review sections already posted (no re-sending the whole diff every time) — but if you push new commits after the review ran, Review Buddy detects that and fetches just the incremental change, so it's never arguing from stale code.
• 📝 Auto-Documentation: Automatically writes a detailed PR description (Summary + Changes + Testing) if the original is lacking.
• 🏷️ Smart Retitling: Detects the nature of changes and renames the PR to be semantic (e.g., fix:, feat:, chore:).
• 🏷️ Intelligent Label Management: Automatically adds relevant labels based on:
  • Change Type: enhancement (feat), bug (fix), documentation (docs), testing (test), maintenance (chore/ci/build)
  • Quality Score: good first review (90+), needs work (<50)
  • Security Concerns: security (if Critical/High issues detected)
  • Performance Issues: performance (if optimization opportunities found)
• 💡 Best Practices Suggestions: Identifies code patterns that can be improved:
  • Loose equality checks (==) → Strict equality (===)
  • if (a == undefined) → if (!a) or if (a === undefined)
  • var declarations → const or let
  • Traditional functions → Arrow functions (where appropriate)
  • Manual string concatenation → Template literals
  • Callback hell → async/await or Promises
  • For loops → Modern array methods (map, filter, reduce)
  • Each suggestion includes before/after code examples with explanations
• 🎯 Smart PR Recommendations: Posts a final recommendation comment with:
  • ✅ APPROVE: High quality code (80+), no critical issues - ready to merge
  • ⚠️ REQUEST CHANGES: Medium quality (40-79) or some concerns - needs improvements
  • 🚫 REJECT: Critical security issues or very low quality (<40) - major fixes required
  • Includes reasoning, review checklist, and clear next steps for reviewers
• 💬 Adaptive Persona:
  • roast (Default): Matches intensity to severity — clean code gets genuine praise ("Shabash!"), minor issues get calm Hinglish teaching, and real bugs/security holes get the full savage roast. Not everything gets roasted equally.
  • professional: Helpful, clean, and mentorship-focused.
  • funny: Adds humor using emojis and light jokes.
  • friendly: Encouraging and kind.
• 🌐 Multi-Language Support:
  • hinglish (Default): A mix of Hindi and English (Perfect for Indian dev teams!).
  • english: Standard Professional English.
  • Any other language supported by the AI model.
• 🔌 Multi-Provider Support:
  • gemini (Default): Google Gemini API (gemini-3-flash-preview by default).
  • openrouter: Access 100+ models via OpenRouter (Claude, GPT, Llama, Mistral, etc.).
  • github-models: Use GitHub Models API with access to OpenAI, Meta, Mistral models and more.

---

🛠 Inputs

Input	Description	Required	Default
github_token	GitHub Token (use secrets.GITHUB_TOKEN)	No	${{ github.token }}
gemini_api_key	Google Gemini API Key (required for gemini adapter)	Conditional	N/A
adaptive_api_token	Generic API Token for OpenRouter or GitHub Models	Conditional	N/A
adapter	AI provider (gemini, openrouter, or github-models)	No	gemini
model	Model name (optional - smart defaults for each adapter)	No	See below
model_context_tokens	Context window (in tokens) of your chosen model. Lets Review Buddy size/split large diffs correctly for any model instead of guessing.	No	32000
tone	The personality (professional, funny, roast, friendly)	No	roast
language	Language of the review (e.g., english, hinglish)	No	hinglish
pr_number	The PR number to process	No	Auto-detected

Default Models:

• gemini: gemini-3-flash-preview
• openrouter: openrouter/auto (auto-selects best free/cheap model)
• github-models: openai/gpt-4o

Required Permissions To function correctly, the github_token needs specific permissions. If using the default GITHUB_TOKEN, ensure your workflow YAML includes:

permissions:
  pull-requests: write  # Allowed to comment and update PR body/title
  contents: read        # Allowed to read the code diff

Token Permissions Guide

Option 1: Using the Default GITHUB_TOKEN (Recommended) Simply add this permissions block to your workflow file:

permissions:
  pull-requests: write  # Allows commenting & editing PR details
  contents: read        # Allows reading the code diff

Option 2: Creating a Personal Access Token (PAT) If you choose to use a PAT instead, follow these settings when creating it:

• Classic Token:
  • Check [x] repo (Full control of private repositories) or [x] public_repo.
• Fine-grained Token (More Secure):
  • Repository Access: Select target repositories.
  • Permissions:
    • Pull Requests: Read and Write
    • Contents: Read-only

---

📦 Usage

Create a workflow file in your repository at .github/workflows/review-buddy.yml.

1. Standard Configuration

Best for internal teams who want a mix of utility and fun.

name: Review Buddy CI

on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

permissions:
  pull-requests: write
  contents: read

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Run Review Buddy
        uses: nexoral/ReviewBuddy@main
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
          # Defaults: tone='roast', language='hinglish'

2. Professional Configuration

Best for open-source or strict business environments.

      - name: Run Review Buddy
        uses: nexoral/ReviewBuddy@main
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
          tone: 'professional'
          language: 'english'

3. Custom Gemini Model

Use a specific Gemini model.

      - name: Run Review Buddy
        uses: nexoral/ReviewBuddy@main
        with:
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
          model: 'gemini-2.5-pro'

4. OpenRouter Configuration

Use any model via OpenRouter (Claude, GPT, Llama, Mistral, etc.).

🎯 Smart Default: If you don't specify a model, Review Buddy uses openrouter/auto which automatically selects the best free or cheap model for your request!

⚠️ Important - Model Selection:

• Recommended models: anthropic/claude-3.5-sonnet, google/gemini-2.0-flash-exp:free, openai/gpt-4o-mini, meta-llama/llama-3.3-70b-instruct
• Avoid very small models (< 7B parameters) - they cannot follow complex JSON structures
• Small models may return errors, shallow reviews, and fail to update PR titles/descriptions

With automatic model selection:

      - name: Run Review Buddy
        uses: nexoral/ReviewBuddy@main
        with:
          adapter: 'openrouter'
          adaptive_api_token: ${{ secrets.OPENROUTER_API_KEY }}
          tone: 'roast'
          language: 'hinglish'
          # model is optional - will use openrouter/auto

With specific model:

      - name: Run Review Buddy
        uses: nexoral/ReviewBuddy@main
        with:
          adapter: 'openrouter'
          adaptive_api_token: ${{ secrets.OPENROUTER_API_KEY }}
          model: 'anthropic/claude-3.5-sonnet'
          tone: 'professional'
          language: 'english'

5. GitHub Models Configuration

Use GitHub Models API with your GitHub token. Access OpenAI GPT, Meta Llama, and more!

🆕 New Feature: GitHub Models provides access to cutting-edge AI models directly through your GitHub token. No separate API key needed!

🎯 Smart Default: Uses openai/gpt-4o by default - the best balance of quality and speed!

With default model (gpt-4o):

      - name: Run Review Buddy
        uses: nexoral/ReviewBuddy@main
        with:
          adapter: 'github-models'
          adaptive_api_token: ${{ secrets.GITHUB_TOKEN }}
          tone: 'roast'
          language: 'hinglish'
          # model is optional - will use openai/gpt-4o

With specific model:

      - name: Run Review Buddy
        uses: nexoral/ReviewBuddy@main
        with:
          adapter: 'github-models'
          adaptive_api_token: ${{ secrets.GITHUB_TOKEN }}
          model: 'openai/gpt-5'
          tone: 'roast'
          language: 'hinglish'

Available Models:

• openai/gpt-5 - Latest OpenAI (Recommended for best quality)
• openai/gpt-4o - Default, excellent balance (⭐ Default)
• openai/gpt-4o-mini - Fast and efficient
• meta-llama/llama-3.3-70b-instruct - Open source, powerful
• mistralai/mistral-large - Great for code

💡 Tip: You can use the default GITHUB_TOKEN or create a personal access token from your GitHub Settings > Developer settings > Tokens.

6. Handling Forked PRs (Open Source)

Important: PRs from forks have read-only permissions by default. To allow Review Buddy to comment and update descriptions on forked PRs, use pull_request_target.

name: Review Buddy CI

on:
  pull_request_target: # Required for Fork support
    types: [opened, synchronize]

permissions:
  pull-requests: write
  contents: read

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Review Buddy
        uses: nexoral/ReviewBuddy@main
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}

---

❓ FAQ

Q: Why did it change my PR Title? A: Review Buddy detected that your title didn't match the content of your code (or was too generic). It uses AI to generate a Conventional Commit title so your git history remains clean.

Q: What labels does Review Buddy add automatically? A: Review Buddy intelligently adds labels based on the PR analysis:

• Change Type: enhancement, bug, documentation, testing, maintenance
• Quality: good first review (high quality), needs work (low quality)
• Concerns: security, performance

Note: Labels must already exist in your repository. Review Buddy will skip labels that don't exist.

Q: What if the labels don't exist in my repository? A: Review Buddy will gracefully skip labels that don't exist. To use this feature fully, create the following labels in your repository:

• enhancement, bug, documentation, testing, maintenance
• good first review, needs work
• security, performance

Q: How does Review Buddy decide whether to recommend Approve, Request Changes, or Reject? A: Review Buddy uses AI-driven verdict determination. Gemini analyzes the code and returns a structured verdict that considers:

• The perspective and purpose of the changes (e.g., config/docs changes are judged leniently, auth/security PRs are judged strictly)
• Whether security issues are real and exploitable, not just theoretical
• The overall code quality, maintainability, and risk

The recommendation is posted as a final comment with detailed reasoning and next steps.

Q: Can I dispute Review Buddy's verdict? A: Yes! Reply with /buddy and explain your reasoning (e.g., "/buddy this is a config-only change, the security concerns don't apply here"). Review Buddy will re-evaluate the verdict based on your explanation and the full conversation context, and update the original recommendation comment if warranted.

Q: Does it review the whole repository, or just the diff? A: It reviews the diff, but with full context: Review Buddy checks out your repo and reads the complete content of every changed file (not just the changed lines), plus a one-hop map of the local files each changed file imports. This is what lets it catch architecture-level issues instead of guessing from a 3-line diff hunk.

Q: If I push new commits after the review already ran, does /buddy know about them? A: Yes. Review Buddy tracks which commit it last reviewed. If you push new commits and then comment /buddy, it detects the mismatch and fetches just the incremental diff since the last review, alongside the earlier findings — it won't reply based on stale code.

Q: What happens on a huge PR that touches hundreds of files? A: Review Buddy splits the review per-file (with bounded concurrency and a per-run file cap) instead of sending one massive prompt, then synthesizes the results into a single report. If a PR exceeds the cap, or the synthesis step itself would overflow the model's context, the lowest-priority items are dropped and called out transparently in the posted comment rather than silently ignored.

Q: What does @main mean in uses: ...@main? A: It tells GitHub Actions to use the latest version of the code from the main branch. For production stability, you may want to use a specific tag (e.g., @v1.0.0) once released.

---

⚙️ Setup

For Gemini (Default):

1. Get a Gemini API Key: Visit Google AI Studio to create a free API key.
2. Add Secrets: Go to your repository Settings > Secrets and variables > Actions and add GEMINI_API_KEY.
3. Add Workflow: Copy one of the usage examples above into a new yaml file in .github/workflows/.

For OpenRouter:

1. Get an OpenRouter API Key: Visit OpenRouter and create an API key.
2. Add Secrets: Add OPENROUTER_API_KEY to your repository secrets (or use ADAPTIVE_API_TOKEN for a generic approach).
3. Add Workflow: Use the OpenRouter configuration example above, setting adapter: 'openrouter' and your preferred model.

For GitHub Models:

1. Get GitHub Token: Your repository already has GITHUB_TOKEN available, or create a Personal Access Token from GitHub Settings.
2. Add Secrets (optional): If using a custom token, add it as GITHUB_TOKEN or ADAPTIVE_API_TOKEN to your repository secrets.
3. Add Workflow: Use the GitHub Models configuration example above, setting adapter: 'github-models' and your preferred model.

---

📂 Project Structure

Verified Source Code structure for contributors:

ReviewBuddy/
├── action.yml                      # GitHub Action definition & metadata (includes its own checkout step)
├── package.json                    # Dependencies & test scripts (npm test = jest)
├── VERSION                         # Current version tracker
├── LICENSE                         # MIT License
├── README.md                       # Documentation
├── CODE_OF_CONDUCT.md              # Community guidelines
├── CONTRIBUTING.md                 # Contribution guidelines
├── SECURITY.md                     # Security policy
├── SUPPORT.md                      # Support documentation
├── src/
│   ├── index.js                    # Entry point & orchestration logic (single-pass + map-reduce)
│   ├── github/
│   │   └── index.js                # GitHub API interactions (PR, comments, labels)
│   ├── utils/
│   │   ├── index.js                # Logging, scoring, recommendations
│   │   ├── gitContext.js           # Local git diff/full-file/repo-map context (fails soft to API diff)
│   │   ├── contextBudget.js        # Per-model token budget + merge-step size guard
│   │   └── concurrency.js          # Bounded-concurrency map helper for large PRs
│   ├── prompts/
│   │   ├── reviewPrompt.js         # Single-pass PR review prompt
│   │   ├── fileReviewPrompt.js     # Per-file review prompt (map phase)
│   │   ├── mergeReviewPrompt.js    # Synthesis prompt (reduce phase)
│   │   ├── chatPrompt.js           # /buddy chat reply prompt
│   │   └── toneInstructions.js     # Shared tone/language guidance
│   └── adapters/
│       ├── index.js                # Adapter registry & factory
│       ├── geminiAdapter.js        # Google Gemini API adapter
│       ├── openrouterAdapter.js    # OpenRouter API adapter
│       └── githubModelsAdapter.js  # GitHub Models API adapter
├── tests/                          # Jest unit tests (run with `npm test`)
│   ├── utils.test.js
│   ├── github.test.js
│   ├── gitContext.test.js
│   ├── contextBudget.test.js
│   └── concurrency.test.js
└── .github/
    ├── FUNDING.yml                 # GitHub Sponsors configuration
    ├── pull_request_template.md    # PR template
    ├── ISSUE_TEMPLATE/
    │   ├── bug_report.md           # Bug report template
    │   └── feature_request.md      # Feature request template
    └── workflows/
        ├── review_buddy.yml        # ReviewBuddy CI workflow
        └── auto-release.yml        # Automated release on version bump

🤝 Contributing

Contributions are welcome! Please ensure you:

1. Fork the repo.
2. Modify the scripts in src/.
3. Run npm install then npm test (Jest) to verify nothing broke.
4. Submit a PR (Review Buddy will likely roast it!).

📄 License

MIT