ai-code-review-cli 1.14.1

AI-powered code review tool with local Git, remote MR/PR analysis, and CI integration (GitLab or GitHub)

AI Code Review

AI-powered code review tool with 3 powerful use cases:

• 🤖 CI Integration - Automated reviews in your CI/CD pipeline (GitLab or GitHub)
• 🔍 Local Reviews - Review your local changes before committing
• 🌐 Remote Reviews - Analyze existing MRs/PRs from the terminal

📑 Table of Contents

• 🚀 Primary Use Case: CI/CD Integration
• ⚙️ Secondary Use Cases
  • Local Usage (Container)
  • Local Usage (CLI Tool)
  • Remote Reviews
• 🔧 Configuration
• ⚡ Smart Skip Review
• For Developers
• 🔧 Common Issues
• 📖 Documentation
• 🤖 AI Tools Disclaimer
• 📄 License
• 👥 Author

🚀 Primary Use Case: CI/CD Integration

This is the primary and recommended way to use the AI Code Review tool.

GitLab CI

Add to .gitlab-ci.yml:

ai-review:
  stage: code-review
  image: registry.gitlab.com/redhat/edge/ci-cd/ai-code-review:latest
  variables:
    AI_API_KEY: $GEMINI_API_KEY  # Set in CI/CD variables
  script:
    - ai-code-review --post
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  allow_failure: true

GitHub Actions

Add to .github/workflows/ai-review.yml:

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    container:
      image: registry.gitlab.com/redhat/edge/ci-cd/ai-code-review:latest
    steps:
      - name: Run AI Review
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: ai-code-review --pr-number ${{ github.event.pull_request.number }} --post

⚙️ Secondary Use Cases

Local Usage (Container)

This is the recommended way to use the tool locally, as it doesn't require any installation on your system.

# Review local changes
podman run -it --rm -v .:/app -w /app registry.gitlab.com/redhat/edge/ci-cd/ai-code-review:latest --local

# Review a remote MR
podman run -it --rm -e GITLAB_TOKEN=$GITLAB_TOKEN -e AI_API_KEY=$AI_API_KEY registry.gitlab.com/redhat/edge/ci-cd/ai-code-review:latest group/project 123

Note: You can use docker instead of podman and the command should work the same.

Local Usage (CLI Tool)

This is a good option if you have Python installed and want to use the tool as a CLI command.

Note on package vs. command name: The package is registered on PyPI as ai-code-review-cli, but for ease of use, the command to execute remains ai-code-review.

pipx is a more mature and well-known tool for the same purpose. It handles the package vs. command name difference automatically.

# Install pipx
pip install pipx
pipx ensurepath

# Install the package
pipx install ai-code-review-cli

# Run the command
ai-code-review --local

Remote Reviews

You can also analyze existing MRs/PRs from your terminal.

# GitLab MR
ai-code-review group/project 123

# GitHub PR
ai-code-review --platform github owner/repo 456

# Save to file
ai-code-review group/project 123 -o review.md

# Post the review to the MR/PR
ai-code-review group/project 123 --post

🔧 Configuration

Required Setup

1. Platform Token (Not needed for local reviews)

# For GitLab remote reviews
export GITLAB_TOKEN=glpat_xxxxxxxxxxxxxxxxxxxx

# For GitHub remote reviews
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# Local reviews don't need platform tokens! 🎉

2. AI API Key

# Get key from: https://makersuite.google.com/app/apikey
export AI_API_KEY=your_gemini_api_key_here

Configuration Methods (Priority Order)

The tool supports 4 configuration methods with the following priority:

1. 🔴 CLI Arguments (highest priority) - --provider anthropic --model claude-sonnet-4-20250514
2. 🟡 Environment Variables - export AI_PROVIDER=anthropic
3. 🟢 Configuration File - .ai_review/config.yml
4. ⚪ Field Defaults (lowest priority) - Built-in defaults

Configuration File

Create a YAML configuration file for persistent settings:

# Create from template
cp .ai_review/config.yml.example .ai_review/config.yml

# Edit your project settings
nano .ai_review/config.yml

Key benefits:

• ✅ Project-specific settings - Different configs per repository
• ✅ Team sharing - Commit to git for consistent team settings
• ✅ Reduced typing - Set common options once
• ✅ Layered override - CLI arguments still override everything

File locations:

• Auto-detected: .ai_review/config.yml (loaded automatically if exists)
• Custom path: --config-file path/to/custom.yml
• Disable loading: --no-config-file flag

Environment Variables

For sensitive data and CI/CD environments:

# Copy template
cp env.example .env

# Edit and set your tokens
GITLAB_TOKEN=glpat_xxxxxxxxxxxxxxxxxxxx
AI_API_KEY=your_gemini_api_key_here

Common Options

# Different AI providers
ai-code-review project/123 --provider anthropic  # Claude
ai-code-review project/123 --provider ollama     # Local Ollama

# Custom server URLs
ai-code-review project/123 --gitlab-url https://gitlab.company.com

# Output options
ai-code-review project/123 -o review.md          # Save to file
ai-code-review project/123 2>logs.txt            # Logs to stderr

For all configuration options, troubleshooting, and advanced usage → see User Guide

⚡ Smart Skip Review

AI Code Review automatically skips unnecessary reviews to reduce noise and costs:

• 🔄 Dependency updates (chore(deps): bump lodash 4.1.0 to 4.2.0)
• 🤖 Bot changes (from dependabot[bot], renovate[bot])
• 📝 Documentation-only changes (if enabled)
• 🏷️ Tagged PRs/MRs ([skip review], [automated])
• 📝 Draft/WIP PRs/MRs (work in progress)

Result: Focus on meaningful changes, save API costs, faster CI/CD pipelines.

📖 Learn more: Configuration, customization, and CI integration → User Guide - Skip Review

For Developers

Development Setup

# Install using uv (recommended)
uv sync

# Or with pip
pip install -e .

To install or learn more about uv, check here: uv

🔧 Common Issues

gRPC Warnings with Google Gemini

When using Google Gemini provider, you may see harmless gRPC connection warnings:

WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1759934851.372144 Other threads are currently calling into gRPC, skipping fork() handlers

These warnings are harmless and don't affect functionality. To suppress them:

# Suppress warnings by redirecting stderr
ai-code-review --local 2>/dev/null
ai-generate-context . 2>/dev/null

# Or use alternative provider (no warnings)
ai-code-review --local --provider ollama

📖 Documentation

• User Guide - Complete usage, configuration, and troubleshooting
• Context Generator Guide - AI context generation for better reviews (requires Git repository)
• Context7 Integration Guide - Enhanced reviews with official library documentation (optional)
• Developer Guide - Development setup, architecture, and contributing

🤖 AI Tools Disclaimer

This project was developed with the assistance of artificial intelligence tools

Tools used:

• Cursor: Code editor with AI capabilities
• Claude-Sonnet-4: Anthropic's language model (claude-sonnet-4-20250514)

Division of responsibilities:

AI (Cursor + Claude-Sonnet-4):

• 🔧 Initial code prototyping
• 📝 Generation of examples and test cases
• 🐛 Assistance in debugging and error resolution
• 📚 Documentation and comments writing
• 💡 Technical implementation suggestions

Human (Juanje Ojeda):

• 🎯 Specification of objectives and requirements
• 🔍 Critical review of code and documentation
• 💬 Iterative feedback and solution refinement
• ✅ Final validation of concepts and approaches

Collaboration philosophy: AI tools served as a highly capable technical assistant, while all design decisions, educational objectives, and project directions were defined and validated by the human.

📄 License

MIT License - see LICENSE file for details.

👥 Author

• Author: Juanje Ojeda
• Email: [e-mail]
• URL: https://gitlab.com/redhat/edge/ci-cd/ai-code-review