🤖 Agentic Reviewer SDK

An autonomous, self-hosted, ReAct-style AI code review engine.

Agentic Reviewer is an enterprise-grade Node.js SDK that brings autonomous, agentic code reviews to your GitHub Pull Requests. Instead of relying on a simple "pass diff to LLM" script, this SDK utilizes a robust ReAct (Reason + Act) tool-calling loop. The AI autonomously fetches code context, analyzes specific chunks, posts inline comments on specific lines, and delivers a final verdict—all without human intervention.

Crucially, it runs 100% locally. The SDK ships with an embedded Ollama binary and automatically downloads the model weights, guaranteeing zero data leakage and zero setup friction for your development team.

🏗️ System Architecture

By moving to a stateless SDK, you have the absolute freedom to embed this Agent into any architecture. Below is the standard architecture for deploying this SDK as an automated webhook server.

graph TD
    A[GitHub PR Webhook] -->|Trigger| B(Webhook Server<br/>Node.js / Express)
    B -->|Enqueue Job| C[Job Queue<br/>BullMQ + Redis]
    C -->|Dequeue| D{Agent Worker<br/>ReviewAgent SDK}
    
    D -.->|Tool: fetch diff| E[GitHub API]
    D -.->|Spawn Engine| F[Embedded Ollama<br/>qwen2.5-coder]
    D -.->|Tool: post comments| E
    
    F -.->|Reason & Act| D
    
    C -->|Save Result| G[(PostgreSQL<br/>History)]

🔄 The Agentic Loop

This is what separates the project from a simple 'call LLM with diff' script. The model runs in a ReAct-style loop — it reasons, picks a tool, observes the result, reasons again — until it decides the review is complete.

1. Receive PR Event: You pass a GitHub PR URL to the SDK.
2. Fetch Diff: The SDK calls the fetch_diff tool. GitHub API returns file-level diffs.
3. Feed to Ollama: Diff + strict bug-hunter prompt + tool definitions are sent to the local qwen2.5-coder engine.
4. Tool-Calling Loop: The model calls analyze_code_chunk, post_inline_comment, or fetch_file_content iteratively. The loop exits only when the model determines no further analysis is needed.
5. Post Comments: The model calls post_summary_comment as its final action to approve, comment, or request changes.

🛠️ Tool Definitions

Four core tools give the agent everything it needs to conduct a thorough review:

| Tool | Parameters | What it does | |------|------------|--------------| | fetch_file_content | filename | Fetches the full file for deeper context beyond the diff. | | analyze_code_chunk | filename, chunk, focus | Analyzes a diff chunk for bugs, security issues, or style problems. | | post_inline_comment | filename, line, comment, severity | Posts a review comment on a specific line (info/warning/error). | | post_summary_comment| summary, verdict | Posts the final PR summary with approve, request_changes, or comment. |

🧠 Model Selection

All models run locally via Ollama. By default, the SDK installs the 1.5b model. You can override this by setting the AGENTIC_MODEL environment variable before running npm install.

| Install Command Prefix | Model | Size | Why it fits | |----------------------|-------|------|-------------| | (None - Default) | qwen2.5-coder:1.5b | ~1 GB | Fast & Lightweight. Great for general reviews, CI/CD runners, and standard laptops. | | AGENTIC_MODEL=qwen2.5-coder:7b | qwen2.5-coder:7b | ~4.7 GB | Recommended. Best-in-class at 7B for code, native tool-calling support. Requires more RAM/VRAM. | | AGENTIC_MODEL=deepseek-coder-v2 | deepseek-coder-v2| ~9 GB | Stronger reasoning for complex diffs. (You can pass any model name here, as long as Ollama supports it and it has native tool-calling capabilities). |

🚀 Installation & Setup

Because the SDK utilizes an embedded version of Ollama, there are no external system dependencies required (No Docker, no Python, no C++ build tools).

1. Install the SDK

By default, installing the SDK will automatically download the 1.5b model.

npm install @agentic-reviewer/core

If you want the more powerful 7b model (recommended if you have 16GB+ RAM), prepend the install command with the model environment variable:

# Mac/Linux:
AGENTIC_MODEL=qwen2.5-coder:7b npm install @agentic-reviewer/core

# Windows (PowerShell):
$env:AGENTIC_MODEL="qwen2.5-coder:7b"; npm install @agentic-reviewer/core

(Note: Because the SDK downloads real AI model weights, the first-time installation will take ~5 minutes depending on your internet connection. NPM hides script output by default and will just show a spinning circle. If you want to see the live download progress bar, append --foreground-scripts to your install command!)

2. Environment Configuration

Securely store your GitHub Personal Access Token (requires repo scope).

GITHUB_TOKEN=ghp_your_secure_token_here

3. Usage

import 'dotenv/config';
import { ReviewAgent } from '@agentic-reviewer/core';

async function runReview() {
  // The SDK automatically spawns the background Ollama engine, 
  // runs the agentic loop, and cleanly shuts down.
  const result = await ReviewAgent.analyzePR('https://github.com/owner/repo/pull/123', {
    githubToken: process.env.GITHUB_TOKEN,
    model: 'qwen2.5-coder:1.5b' // Must match the package you installed
  });

  console.log('Verdict:', result.verdict);
  console.log('Summary:', result.summary);
}

runReview();

💡 Use Cases

1. The Automated Webhook Server (Express + BullMQ)

Build a lightweight Express server combined with BullMQ. When GitHub fires a webhook, push the URL to the queue, and let your Worker execute the SDK.

2. CI/CD Pipeline Integration (GitHub Actions)

Run the SDK directly inside a GitHub Actions runner. Because the SDK is self-contained and downloads its own Ollama binary, it can block PR merges natively inside your CI/CD pipeline.

3. Custom Internal Developer Tools (CLI)

Wrap the SDK in a local CLI tool (npm run review --pr=123). The SDK outputs the review results directly to the terminal, allowing developers to fix bugs locally before anyone else sees them.

📝 License

MIT License.