PR Agent

An AI-powered tool that automatically analyzes pull requests and code changes using advanced AI models (Claude, GPT, Gemini). Available as both a CLI tool for local development and a GitHub Action for CI/CD integration.

🎥 Watch the setup tutorial on YouTube

Overview

PR Agent analyzes your code changes and provides:

Summary: Clear description of what the change does and its purpose
Potential Risks: Identification of possible bugs, edge cases, or issues
Complexity Rating: A 1-5 scale rating of complexity with file-level breakdown
Actionable Insights: Specific recommendations based on your codebase
Architecture-Aware Analysis: Leverages your .arch-docs for context-aware reviews

Features

✨ Intelligent Agent Mode - Automatically handles large diffs without chunking
🏗️ Architecture Documentation Integration - Uses .arch-docs for smarter analysis
🔌 Multiple AI Providers - Anthropic Claude, OpenAI GPT, Google Gemini
🖥️ CLI & GitHub Action - Use locally or in CI/CD pipelines
📊 File-Level Analysis - Individual risk and complexity scores per file
⚙️ Configurable - Customize models, providers, and analysis modes

Quick Reference

# Install
npm install -g @techdebtgpt/pr-agent

# Setup
pr-agent config --init

# Analyze (common commands)
pr-agent analyze                    # Analyze against origin/main
pr-agent analyze --staged           # Analyze staged changes
pr-agent analyze --branch develop   # Compare with develop branch
pr-agent analyze --full --verbose   # Full analysis with details

# Configuration
pr-agent config --list              # View config
pr-agent config --set ai.provider=anthropic
pr-agent help                       # Show help

Prerequisites

Before using PR Agent, you'll need:

AI Provider API Key (at least one):
- Anthropic Claude: Sign up at Anthropic Console (Recommended)
- OpenAI GPT: Get your key from OpenAI Platform
- Google Gemini: Get your key from Google AI Studio
For GitHub Action: Repository with permissions to add workflows and secrets

Installation

CLI Installation

Install PR Agent globally using npm:

npm install -g @techdebtgpt/pr-agent

Or use it directly with npx:

npx @techdebtgpt/pr-agent analyze

Verify Installation

pr-agent --version
pr-agent help

CLI Usage

Quick Start

Configure PR Agent (interactive setup):

pr-agent config --init

This will guide you through:

Selecting an AI provider (Anthropic/OpenAI/Google)
Choosing a model
Setting up API keys
Configuring analysis preferences

Analyze your changes:

# Analyze current branch against origin/main
pr-agent analyze

# Analyze staged changes
pr-agent analyze --staged

# Analyze against a specific branch
pr-agent analyze --branch develop

Analyze Command

The analyze command is the primary tool for analyzing code changes:

Basic Usage

# Default: analyze against origin/main
pr-agent analyze

# Analyze staged changes (before commit)
pr-agent analyze --staged

# Analyze against specific branch
pr-agent analyze --branch develop

# Analyze from a diff file
pr-agent analyze --file changes.diff

Analysis Modes

# Full analysis (summary + risks + complexity) - default
pr-agent analyze --full

# Only summary
pr-agent analyze --summary

# Only risks
pr-agent analyze --risks

# Only complexity
pr-agent analyze --complexity

Provider Options

# Use specific AI provider
pr-agent analyze --provider anthropic
pr-agent analyze --provider openai
pr-agent analyze --provider google

# Use specific model
pr-agent analyze --provider anthropic --model claude-sonnet-4-5-20250929
pr-agent analyze --provider openai --model gpt-4-turbo-preview

Advanced Options

# Enable verbose output (shows analysis strategy)
pr-agent analyze --verbose

# Set maximum cost limit
pr-agent analyze --max-cost 10.0

# Force agent mode for large diffs
pr-agent analyze --agent

# Specify PR title manually
pr-agent analyze --title "Add new authentication system"

Configuration

PR Agent uses a .pragent.config.json file for configuration:

Interactive Setup

pr-agent config --init

Manual Configuration

# View current configuration
pr-agent config --list

# Get specific value
pr-agent config --get ai.provider

# Set specific value
pr-agent config --set ai.provider=anthropic
pr-agent config --set ai.model=claude-sonnet-4-5-20250929
pr-agent config --set ai.temperature=0.2

# Validate configuration
pr-agent config --validate

# Reset to defaults
pr-agent config --reset

Configuration File Structure

.pragent.config.json:

{
  "ai": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-5-20250929",
    "temperature": 0.2,
    "maxTokens": 2000
  },
  "apiKeys": {
    "anthropic": "sk-ant-...",
    "openai": "",
    "google": ""
  },
  "analysis": {
    "defaultMode": "full",
    "maxCost": 5.0,
    "autoDetectAgent": true,
    "agentThreshold": 50000
  },
  "git": {
    "defaultBranch": "origin/main",
    "includeUntracked": true,
    "excludePatterns": [
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**"
    ]
  },
  "output": {
    "verbose": false,
    "showStrategy": true,
    "showRecommendations": true
  }
}

Environment Variables

Instead of storing API keys in the config file, you can use environment variables:

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI GPT
export OPENAI_API_KEY="sk-..."

# Google Gemini
export GOOGLE_API_KEY="..."

Add to your .bashrc, .zshrc, or .env file for persistence.

Default Branch Configuration

PR Agent automatically detects the default branch for your repository using the following priority:

Config file (git.defaultBranch) - If set in .pragent.config.json, this takes highest priority
GitHub API - If GITHUB_TOKEN is available, fetches the default branch from GitHub
Git commands - Falls back to detecting from local git repository
Fallback - Defaults to origin/main if nothing else works

Examples:

# Set default branch in config
pr-agent config --set git.defaultBranch=origin/develop

# For repositories using 'master' as default
pr-agent config --set git.defaultBranch=origin/master

# Override for a single analysis
pr-agent analyze --branch origin/feature-branch

Troubleshooting Branch Issues:

Branch not found: Run git fetch origin to update remote branch references
Wrong branch detected: Set git.defaultBranch in config or use --branch flag
GitHub API errors: Ensure GITHUB_TOKEN is valid, or rely on git fallback
Custom default branch: Configure it explicitly: pr-agent config --set git.defaultBranch=origin/your-branch

Architecture Documentation Integration

PR Agent can leverage your project's architecture documentation for context-aware analysis.

Setup Arch-Docs

Create .arch-docs folder in your repository root
Add markdown documentation files:

your-repo/
├── .arch-docs/
│   ├── index.md           # Overview and index
│   ├── architecture.md    # System architecture
│   ├── patterns.md        # Design patterns
│   ├── security.md        # Security guidelines
│   ├── flows.md          # Data flows
│   └── ...               # Other docs

Auto-Generated Arch-Docs

You can generate architecture documentation automatically using archdoc:

npm install -g @archdocs/cli
archdoc analyze

This will create a comprehensive .arch-docs folder with:

architecture.md - System components and layers
patterns.md - Design patterns detected in your code
security.md - Security analysis and recommendations
flows.md - Data flow visualizations
file-structure.md - Project organization
And more...

How It Works

When you run pr-agent analyze, it automatically:

Detects .arch-docs folder in your repository
Extracts relevant sections based on your PR changes
Provides context to the AI about your architecture
Identifies violations of documented patterns or guidelines
Suggests improvements aligned with your architecture

Example Output with Arch-Docs

$ pr-agent analyze

📚 Architecture documentation detected - including in analysis

✨ Agent Analysis Complete!

📋 Overall Summary
This PR adds a new authentication middleware...

⚠️ Risks by File

  src/middleware/auth.ts
    1. Missing error handling for token validation
       📚 From security.md:
       "All authentication endpoints must implement proper error handling..."
       → Implement try-catch blocks and return appropriate error codes

    2. Direct database access in middleware
       📚 From patterns.md:
       "Business logic should be separated from middleware..."
       → Consider moving to a service layer

📊 Overall Complexity: 3/5

📚 Architecture Documentation Impact
Documents analyzed: 8
Relevant sections used: 12

Stages influenced by arch-docs:
  🔍 file-analysis
  ⚠️ risk-detection
  📝 summary-generation

Key insights from arch-docs integration:
  1. Changes align with documented middleware pattern
  2. Security guidelines recommend additional validation
  3. Consider extracting business logic to service layer

Benefits of Arch-Docs Integration

✅ Context-Aware Analysis - AI understands your specific architecture
✅ Pattern Enforcement - Detects violations of documented patterns
✅ Security Alignment - Checks against your security guidelines
✅ Consistency - Ensures PRs follow established conventions
✅ Better Recommendations - Suggestions aligned with your architecture

GitHub Action Usage

Setup Instructions

Step 1: Add PR Agent Workflow to Your Repository

You need to create a GitHub Actions workflow file in your repository to enable PR Agent. This workflow will automatically run whenever a pull request is opened, updated, or reopened.

Create the workflows directory (if it doesn't exist):
```
mkdir -p .github/workflows
```

Create the workflow file .github/workflows/pr-analyzer.yml:

name: PR Analyzer
on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  pull-requests: write
  issues: write
  contents: read

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run PR Analyzer
        uses: techdebtgpt/pr-agent@v1.0.1
        with:
          config-path: .pr-analyzer.yml
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Commit and push the workflow file to your repository:

git add .github/workflows/pr-analyzer.yml
git commit -m "Add PR Analyzer workflow"
git push

Note: The workflow file must be named pr-analyzer.yml (or any .yml file in .github/workflows/). Once pushed, GitHub Actions will automatically recognize it and run the workflow on the specified events.

Quick Reference: Workflow File Structure

Your repository should have this structure after setup:

your-repo/
├── .github/
│   └── workflows/
       └── pr-analyzer.yml    ← This file triggers PR Agent

Step 2: Configure Secrets

Add your AI provider API key to your repository secrets:

Go to your repository on GitHub
Navigate to Settings → Secrets and variables → Actions
Click New repository secret
Name:
- For Anthropic: ANTHROPIC_API_KEY
- For OpenAI: OPENAI_API_KEY
- For Google: GOOGLE_API_KEY
Value: Your API key
Click Add secret

Note: GITHUB_TOKEN is automatically provided by GitHub Actions, no manual setup required.

Step 3: (Optional) Add Architecture Documentation

For enhanced, context-aware analysis, add a .arch-docs folder to your repository:

# Generate automatically with archdoc
npm install -g @archdocs/cli
archdoc analyze

# Or create manually
mkdir .arch-docs
# Add your architecture documentation as markdown files

Commit and push the .arch-docs folder. PR Agent will automatically use it for analysis.

Automatic Analysis

Once set up, PR Agent automatically runs on:

New pull requests (opened)
Updates to existing pull requests (synchronize)
Reopened pull requests (reopened)

What Happens

PR Opened/Updated: When a PR is created or updated, the workflow triggers
Fetch Changes: The action retrieves all file changes (diffs) from the PR
Architecture Context: Loads relevant sections from .arch-docs (if available)
AI Analysis: Sends the diff with architecture context to the AI for analysis
Post Comment: Posts a comprehensive analysis comment on the PR

Example Output

When PR Agent analyzes your pull request, it posts a comment like:

## 🤖 AI Analysis

### Summary
This PR refactors the authentication middleware to use JWT tokens instead of session-based auth. It introduces a new TokenService class and updates all route handlers to use the new authentication method.

### Potential Risks
- The migration from session to JWT may break existing authenticated users
- No token expiration handling is implemented in the TokenService
- Error handling in the authenticate middleware could expose sensitive information

### Complexity: 4/5
This is a significant architectural change affecting multiple parts of the application. Careful testing of all authenticated endpoints is recommended.

### Recommendations
- Add integration tests for the new authentication flow
- Implement token refresh mechanism
- Review error messages to ensure no sensitive data leaks

Development

If you want to contribute or modify PR Agent:

1. Clone the Repository

git clone https://github.com/YOUR_USERNAME/pr-agent.git
cd pr-agent

2. Install Dependencies

# Install dependencies (use --legacy-peer-deps to handle langchain peer dependency conflicts)
npm install --legacy-peer-deps

3. Build the Project

# Build everything (TypeScript + GitHub Action)
npm run build

# Build only TypeScript
npm run build:tsc

# Build only GitHub Action
npm run build:action

4. Test Locally

Test CLI

# Option 1: Link locally to use 'pr-agent' command
npm link
pr-agent config --init
pr-agent analyze --staged

# Option 2: Use npm script
npm run cli config --init
npm run cli analyze --staged

# Option 3: Run directly with node
node dist/cli/index.js config --init
node dist/cli/index.js analyze --staged

# Option 4: Development mode (no build needed)
npm run dev

Test GitHub Action

Set environment variables:
```
export ANTHROPIC_API_KEY="your-api-key"
```
Create a test PR in a repository you own
Use the action in .github/workflows/pr-analyzer.yml

5. Run Tests

npm test

Project Structure

pr-agent/
├── src/
│   ├── action.ts                    # GitHub Action entry point
│   ├── index.ts                     # Main exports
│   ├── pr-agent.ts                  # Core PR agent logic
│   ├── types.ts                     # TypeScript type definitions
│   ├── cli/                         # CLI implementation
│   │   ├── index.ts                 # CLI entry point
│   │   ├── commands/
│   │   │   ├── analyze.command.ts   # Analyze command
│   │   │   ├── config.command.ts    # Config command
│   │   │   └── help.command.ts      # Help command
│   │   └── utils/
│   │       └── config-loader.ts     # Configuration utilities
│   ├── agents/                      # AI Agent workflows
│   │   ├── base-pr-agent-workflow.ts
│   │   └── pr-analyzer-agent.ts
│   ├── providers/                   # AI Provider integrations
│   │   ├── anthropic.provider.ts
│   │   ├── openai.provider.ts
│   │   ├── google.provider.ts
│   │   └── factory.ts
│   ├── tools/                       # Agent tools
│   │   ├── pr-analysis-tools.ts
│   │   └── index.ts
│   └── utils/                       # Utilities
│       ├── arch-docs-parser.ts      # Parse .arch-docs files
│       └── arch-docs-rag.ts         # RAG for arch-docs
├── dist/                            # Compiled JavaScript (generated)
├── action.yml                       # GitHub Action configuration
├── package.json                     # Dependencies & scripts
├── tsconfig.json                    # TypeScript configuration
└── README.md                        # This file

How It Works

CLI Workflow

Configuration: Loads settings from .pragent.config.json or environment variables
Git Integration: Fetches diff from git (staged, branch comparison, or custom)
Arch-Docs Detection: Automatically detects and loads .arch-docs if available
Intelligent Agent: For large diffs (>50KB), uses agent-based analysis with:
- File-level grouping and analysis
- Strategic reasoning about approach
- Context-aware risk detection
- Architecture-guided recommendations
AI Analysis: Sends to chosen AI provider (Claude/GPT/Gemini) with architecture context
Results Display: Shows summary, risks, complexity, and recommendations in terminal

GitHub Action Workflow

Workflow Setup: The .github/workflows/pr-analyzer.yml file defines when and how PR Agent runs
Trigger: GitHub Action triggers automatically on PR events (opened, synchronize, reopened)
Fetch Diffs: Uses GitHub API to retrieve all changed files and their diffs
Arch-Docs Integration: Loads relevant architecture documentation from .arch-docs
AI Analysis: Sends to AI with full context (diff + architecture)
Parse Response: Extracts structured insights with architecture-aware recommendations
Post Comment: Creates a formatted comment on the PR using GitHub API

Intelligent Agent System

For large or complex PRs, PR Agent uses an intelligent agent system that:

Analyzes files in groups rather than all at once
Maintains context across the entire analysis
Reasons strategically about the best analysis approach
Integrates arch-docs at each stage for context-aware insights
Provides file-level details with individual risk and complexity scores
No manual chunking required - handles diffs of any size

Troubleshooting

CLI Issues

Command Not Found

# If pr-agent command not found after npm install -g
npm install -g @techdebtgpt/pr-agent

# Or use npx
npx @techdebtgpt/pr-agent analyze

API Key Not Recognized

# Check if environment variable is set
echo $ANTHROPIC_API_KEY

# Set it if missing
export ANTHROPIC_API_KEY="sk-ant-..."

# Or configure with CLI
pr-agent config --init

No Config File Found

# Initialize configuration
pr-agent config --init

# Or create manually
touch .pragent.config.json
pr-agent config --set ai.provider=anthropic

Git Diff Issues

# Make sure you're in a git repository
git status

# Check for changes
git diff origin/main

# If origin/main doesn't exist
git diff main

Analysis Fails

Rate Limit: Reduce diff size or wait before retrying
Invalid API Key: Check key is correct and has credits
Model Not Available: Try different model with --model flag
Network Issues: Check internet connection

GitHub Action Issues

Action Not Running

Verify the workflow file .github/workflows/pr-analyzer.yml exists and is committed to your repository
Check that the workflow file is in the correct location (.github/workflows/ directory)
Verify workflow triggers match PR events (opened, synchronize, reopened)
Ensure repository permissions allow Actions to run (check repository Settings → Actions → General)
Check if Actions are enabled for your repository

No Comments Posted

Verify API key secret is set correctly (e.g., ANTHROPIC_API_KEY)
Check workflow permissions include pull-requests: write
Review Action logs for error messages
Ensure the AI provider matches the API key (Anthropic for Claude, OpenAI for GPT, etc.)

Analysis Failed

Check if your API key is valid and has available credits
Verify the API key has not expired
Review Action logs for detailed error messages
For very large PRs, the agent mode should handle it automatically

Arch-Docs Issues

Arch-Docs Not Detected

# Check if folder exists
ls -la .arch-docs

# Create if missing
mkdir .arch-docs

# Generate with archdoc
npm install -g @archdocs/cli
archdoc analyze

Arch-Docs Not Being Used

Make sure .arch-docs folder is in repository root
Verify folder contains .md files
Check CLI output for "Architecture documentation detected" message
Use --arch-docs flag explicitly if needed

Large PRs

The intelligent agent automatically handles large diffs (>50KB)
No manual chunking required
Set --max-cost to control API spending
Use --verbose to see how the agent processes large diffs

Supported AI Models

Anthropic Claude (Recommended)

claude-sonnet-4-5-20250929 - Latest, most capable (default)
claude-3-5-sonnet-20241022 - Fast and efficient
claude-3-opus-20240229 - Most powerful for complex analysis

Best for: Overall quality, architecture understanding, and complex reasoning

OpenAI GPT

gpt-5.1 - Latest GPT-5.1 model (newest)
gpt-4-turbo-preview - Latest GPT-4 (recommended)
gpt-4 - Stable and reliable
gpt-3.5-turbo - Fast and cost-effective

Best for: Quick analysis and cost-conscious usage

Google Gemini

gemini-pro - Google's latest model
gemini-ultra - Most capable Gemini model

Best for: Alternative to Claude/GPT with competitive performance

Common Use Cases

1. Pre-Commit Review

Review your changes before committing:

# Stage your changes
git add .

# Analyze before committing
pr-agent analyze --staged

# If all looks good, commit
git commit -m "Your message"

2. Feature Branch Review

Compare your feature branch against main:

git checkout feature-branch
pr-agent analyze --branch main

3. Daily Standup Summary

Get a quick summary of your work:

pr-agent analyze --summary

4. Pre-PR Quality Check

Before opening a PR, ensure quality:

# Full analysis
pr-agent analyze --full --verbose

# Check for high-risk changes
pr-agent analyze --risks

5. Team Code Review

Use in your PR workflow:

# As PR author: analyze before pushing
pr-agent analyze

# As reviewer: analyze the PR branch
git checkout pr-branch
pr-agent analyze --branch main

6. Architecture Compliance

Ensure changes align with architecture:

# Make sure .arch-docs exists
archdoc analyze

# Analyze with arch-docs
pr-agent analyze --arch-docs

7. CI/CD Integration

Add to your CI pipeline:

# .github/workflows/pr-check.yml
- name: PR Quality Check
  run: |
    npm install -g @techdebtgpt/pr-agent
    pr-agent analyze --full
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

8. Multi-Provider Comparison

Compare analysis from different AI providers:

pr-agent analyze --provider anthropic > claude-analysis.txt
pr-agent analyze --provider openai > gpt-analysis.txt
pr-agent analyze --provider google > gemini-analysis.txt

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues, questions, or feature requests:

Open an issue on GitHub Issues
Check existing issues for solutions
Review Action logs for debugging

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for better code reviews

If you find PR Agent helpful, please ⭐ star the repository!

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.arch-docs		.arch-docs
.github/workflows		.github/workflows
dist		dist
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.pr-analyzer.yml		.pr-analyzer.yml
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

techdebtgpt/pr-agent

Folders and files

Latest commit

History

Repository files navigation

PR Agent

Overview

Features

Quick Reference

Table of Contents

Prerequisites

Installation

CLI Installation

Verify Installation

CLI Usage

Quick Start

Analyze Command

Basic Usage

Analysis Modes

Provider Options

Advanced Options

Configuration

Interactive Setup

Manual Configuration

Configuration File Structure

Environment Variables

Default Branch Configuration

Architecture Documentation Integration

Setup Arch-Docs

Auto-Generated Arch-Docs

How It Works

Example Output with Arch-Docs

Benefits of Arch-Docs Integration

GitHub Action Usage

Setup Instructions

Step 1: Add PR Agent Workflow to Your Repository

Quick Reference: Workflow File Structure

Step 2: Configure Secrets

Step 3: (Optional) Add Architecture Documentation

Automatic Analysis

What Happens

Example Output

Development

1. Clone the Repository

2. Install Dependencies

3. Build the Project

4. Test Locally

Test CLI

Test GitHub Action

5. Run Tests

Project Structure

How It Works

CLI Workflow

GitHub Action Workflow

Intelligent Agent System

Troubleshooting

CLI Issues

Command Not Found

API Key Not Recognized

No Config File Found

Git Diff Issues

Analysis Fails

GitHub Action Issues

Action Not Running

No Comments Posted

Analysis Failed

Arch-Docs Issues

Arch-Docs Not Detected

Arch-Docs Not Being Used

Large PRs

Supported AI Models

Anthropic Claude (Recommended)

OpenAI GPT

Google Gemini

Common Use Cases

1. Pre-Commit Review

2. Feature Branch Review

3. Daily Standup Summary

4. Pre-PR Quality Check

Packages