Claude Code Review Action

A GitHub Action that performs automated code reviews using Claude Sonnet 4.5, Anthropic's latest AI model for code analysis.

Why Use Claude Code Review?

• Instant Feedback: Get AI-powered code reviews immediately on every pull request
• Consistent Quality: Apply consistent review standards across your entire codebase
• Save Time: Catch common issues before human review, allowing reviewers to focus on architecture and logic
• Learn & Improve: Get educational feedback that helps developers improve their coding skills
• 24/7 Availability: Reviews happen automatically, even outside business hours

Table of Contents

• Why Use Claude Code Review?
• Features
• Usage
• Setup
• Inputs
• Outputs
• Review Format
• Technical Details
• Limitations
• Troubleshooting
• Development
• Contributing
• FAQ
• License
• Support

Features

• 🤖 AI-Powered Reviews: Leverages Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) for intelligent code analysis
• 🔍 Comprehensive Analysis: Examines code changes in pull requests thoroughly
• 💡 Detailed Feedback: Provides actionable feedback on code quality and structure
• 🐛 Bug Detection: Identifies potential issues and suggests improvements
• 🔒 Security Scanning: Checks for security vulnerabilities and risks
• ⚡ Performance Insights: Highlights performance implications of code changes
• 📋 Best Practices: Ensures adherence to coding standards and best practices
• 🎯 Severity Ratings: Categorizes issues by severity (Critical/High/Medium/Low)
• 🔄 Automatic Retries: Built-in retry logic with exponential backoff for reliability
• ⏱️ Rate Limit Handling: Automatically manages API rate limits

Usage

Add this to your GitHub workflow file (e.g. .github/workflows/review.yml):

name: Claude Code Review

permissions:
  contents: read
  pull-requests: write

on:
  # Run on new/updated PRs
  pull_request:
    types: [opened, reopened, synchronize]
  
  # Allow manual triggers for existing PRs
  workflow_dispatch:
    inputs:
      pr_number:
        description: 'Pull Request Number'
        required: true
        type: string

jobs:
  code-review:
    runs-on: ubuntu-latest
    environment: development_environment
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          
      - name: Run Claude Review
        uses: pacnpal/claude-code-review@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          anthropic-key: ${{ secrets.ANTHROPIC_API_KEY }}
          pr-number: ${{ github.event.pull_request.number || inputs.pr_number }}

Manual Trigger

For existing pull requests, you can manually trigger the review:

1. Click on "Claude Code Review" Action under the Actions tab
2. Click "Run Workflow"
3. Fill in the branch and pull request number
4. Click "Run Workflow"

Disabling Auto-Review

You can disable automatic reviews and only use manual triggers by setting auto-review: false:

- name: Run Claude Review
  uses: pacnpal/claude-code-review@main
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    anthropic-key: ${{ secrets.ANTHROPIC_API_KEY }}
    pr-number: ${{ github.event.pull_request.number || inputs.pr_number }}
    auto-review: false  # Disables automatic reviews

You can also make it conditional based on labels or other criteria:

- name: Run Claude Review
  uses: pacnpal/claude-code-review@main
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    anthropic-key: ${{ secrets.ANTHROPIC_API_KEY }}
    pr-number: ${{ github.event.pull_request.number || inputs.pr_number }}
    auto-review: ${{ contains(github.event.pull_request.labels.*.name, 'needs-review') }}

Setup

Prerequisites

• A GitHub repository
• An Anthropic API key (Get one here)
• GitHub Actions enabled in your repository

Configuration Steps

1. Add Anthropic API Key:

   • Go to your repository Settings → Secrets and variables → Actions
   • Click "New repository secret"
   • Name: ANTHROPIC_API_KEY
   • Value: Your Anthropic API key
   • Click "Add secret"

2. GitHub Token:

   • The GITHUB_TOKEN is automatically provided by GitHub Actions
   • No additional configuration needed

3. Set Permissions:

   • Ensure your workflow has proper permissions (see Usage example above)
   • Required permissions: contents: read and pull-requests: write
   • For organization repositories, you may need to enable workflows to create/approve pull requests in Settings

4. Optional: Environment Protection:

   • For additional security, create a GitHub Environment (e.g., development_environment)
   • Add ANTHROPIC_API_KEY as an environment secret instead of repository secret
   • This provides additional control and approval gates for sensitive operations

Inputs

Input	Description	Required	Default
github-token	GitHub token for API access	Yes	N/A
anthropic-key	Anthropic API key for Claude	Yes	N/A
pr-number	Pull request number to review	Yes	N/A
auto-review	Enable automatic code reviews (set to false to skip)	No	true

Outputs

Output	Description
diff_size	Size of the relevant code changes
review	Generated code review content

Review Format

The action provides detailed code reviews covering:

1. Potential conflicts with existing codebase
2. Code correctness and potential bugs
3. Security vulnerabilities and risks
4. Performance implications
5. Maintainability and readability issues
6. Adherence to best practices
7. Suggestions for improvements

Each issue found includes:

• Clear problem explanation
• Severity rating (Critical/High/Medium/Low)
• Specific recommendations
• Code examples where helpful

Technical Details

Model Configuration

• Model: Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Max Tokens: 4096 tokens per review
• Temperature: 0.7 for balanced creativity and consistency
• Context: 10 lines of context around each change (git diff -U10)

Reliability Features

Automatic Retry Logic:

• Network failures are automatically retried up to 4 times
• Exponential backoff strategy (2s, 4s, 8s, 16s delays)
• Non-retryable errors (401, 403, 400) fail immediately

Timeout Protection:

• API requests timeout after 2 minutes
• Prevents hanging workflows on slow responses

Rate Limit Handling:

• Automatically respects Retry-After headers
• Graceful handling of 429 rate limit responses

Diff Size Limits

• Maximum Diff Size: ~100KB (100,000 bytes)
• Large diffs are automatically truncated with a notice
• Helps stay within API token limits and ensures fast reviews

Limitations

• Diff Size: Changes larger than ~100KB will be truncated
• Review Timeout: Reviews exceeding 2 minutes will timeout
• PR State: Can review closed PRs, but a warning is logged
• File Types: All text-based files are analyzed; binary files in diffs are ignored
• API Costs: Each review consumes Anthropic API credits based on diff size

Troubleshooting

Common Issues

Issue: "Failed to get PR details"

• Solution: Ensure GITHUB_TOKEN has pull-requests: read permission
• Solution: Verify the PR number is correct

Issue: "anthropic-key does not match expected format"

• Solution: Verify your API key starts with sk-ant-
• Solution: Check for extra spaces or newlines in the secret

Issue: "Diff is empty - no changes found"

• Solution: This is expected when comparing identical commits
• Solution: Ensure the PR has actual code changes

Issue: "Rate limited" or 429 errors

• Solution: The action will automatically retry with backoff
• Solution: Consider reducing review frequency if you hit limits often
• Solution: Check your Anthropic API rate limits and quotas

Issue: "API request timed out"

• Solution: This may happen with very large diffs (>100KB)
• Solution: Break large PRs into smaller, more focused changes
• Solution: The action will automatically truncate diffs that are too large

Issue: Action fails with authentication errors

• Solution: Verify ANTHROPIC_API_KEY is set correctly in repository secrets
• Solution: Ensure the API key is active and not expired
• Solution: Check that your Anthropic account has available credits

Debug Mode

To enable verbose logging, add this to your workflow:

- name: Run Claude Review
  uses: pacnpal/claude-code-review@main
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    anthropic-key: ${{ secrets.ANTHROPIC_API_KEY }}
    pr-number: ${{ github.event.pull_request.number }}
  env:
    ACTIONS_STEP_DEBUG: true

Example Review

# Claude Code Review

1. **Potential conflicts with existing codebase**:
   - No apparent conflicts identified
   
2. **Code correctness and potential bugs**:
   - **Medium Severity**: Potential null pointer in user handling
   - Recommendation: Add null check before accessing user object
   
3. **Security vulnerabilities and risks**: 
   - **High Severity**: SQL injection vulnerability in query construction
   - Recommendation: Use parameterized queries

Development

Local Development Setup

1. Clone the repository:

   git clone https://github.com/pacnpal/claude-code-review.git
   cd claude-code-review
   

2. Install dependencies:

   npm install
   

3. Make your changes:

   • Edit action.js for core functionality
   • The built output goes to dist/index.js

4. Build the action:

   npm run build
   

   This compiles action.js into dist/index.js using @vercel/ncc

5. Run tests:

   npm test
   

Project Structure

claude-code-review/
├── action.js          # Main action logic
├── action.yml         # Action metadata
├── dist/              # Built output (committed)
│   └── index.js       # Compiled action
├── package.json       # Dependencies
└── README.md          # Documentation

Testing Changes

• Test your changes in a fork before submitting a PR
• Use the workflow_dispatch trigger for manual testing
• Ensure npm run build completes without errors
• Verify all tests pass with npm test

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

Frequently Asked Questions

How much does it cost?

The action is free, but you'll need an Anthropic API subscription. Costs vary based on:

• Diff size (larger diffs = more tokens)
• Review frequency (more PRs = more API calls)
• Current Claude API pricing (check Anthropic's pricing)

Typical small PR review (~1-2KB diff) costs a few cents.

Can I use this with private repositories?

Yes! The action works with both public and private repositories. Just ensure:

• GitHub Actions is enabled for your repository
• You've added the ANTHROPIC_API_KEY secret
• Workflow permissions are properly configured

Will this slow down my CI/CD pipeline?

The action runs asynchronously and doesn't block other checks. Typical review times:

• Small PRs (<10KB): 10-30 seconds
• Medium PRs (10-50KB): 30-60 seconds
• Large PRs (50-100KB): 60-120 seconds

You can also use auto-review: false to only run reviews on-demand.

Can I customize the review criteria?

Currently, the review criteria are built into the action. Future versions may support custom prompts. You can:

• Fork the repository and modify action.js to customize the prompt
• Use the review as a baseline and add custom checks with other actions

Does it support languages other than English?

The action's prompts are in English, but Claude can analyze code in any programming language. Review comments will be in English.

What happens if my diff is too large?

Diffs larger than ~100KB are automatically truncated. A notice is added to the review indicating truncation. For large PRs:

• Consider breaking them into smaller, focused changes
• The most important changes (first ~100KB) will still be reviewed

Can I run this on forked PRs?

Yes, but be cautious with secrets. Use GitHub's pull_request_target event with proper security:

• Don't expose secrets to untrusted code
• Consider requiring manual approval for fork PRs
• Review GitHub's security hardening guide

How do I prevent reviews on draft PRs?

Add a condition to your workflow:

jobs:
  code-review:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    # ... rest of job

License

MIT License - see the LICENSE file for details

Support

Getting Help

• 🐛 Bug Reports: Open an issue with details and reproduction steps
• 💡 Feature Requests: Create an issue describing your use case
• 🤝 Contributions: Submit a PR following our contribution guidelines
• 📧 Questions: Open a discussion or contact the maintainers

Resources

• Anthropic Claude Documentation
• GitHub Actions Documentation
• Action Marketplace Listing

Acknowledgments

Built with:

• Anthropic Claude API - AI-powered code analysis
• GitHub Actions - CI/CD automation platform
• @actions/core - GitHub Actions toolkit
• @vercel/ncc - Node.js bundler

---

Made with ❤️ by PacNPal | Report Bug | Request Feature