# 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](#-primary-use-case-cicd-integration)
- [⚙️ Secondary Use Cases](#️-secondary-use-cases)
- [Local Usage (Container)](#local-usage-container)
- [Local Usage (CLI Tool)](#local-usage-cli-tool)
- [Remote Reviews](#remote-reviews)
- [🔧 Configuration](#-configuration)
- [⚡ Smart Skip Review](#-smart-skip-review)
- [For Developers](#for-developers)
- [🔧 Common Issues](#-common-issues)
- [📖 Documentation](#-documentation)
- [🤖 AI Tools Disclaimer](#-ai-tools-disclaimer)
- [📄 License](#-license)
- [👥 Author](#-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`:
```yaml
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`:
```yaml
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.
```bash
# 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.
```bash
# 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.
```bash
# 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)
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
# 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
```bash
# 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](docs/user-guide.md)**
## ⚡ 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](docs/user-guide.md#smart-skip-review)
## For Developers
### Development Setup
```bash
# Install using uv (recommended)
uv sync
# Or with pip
pip install -e .
```
> To install or learn more about `uv`, check here:
[uv](https://docs.astral.sh/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:
```bash
# 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](docs/user-guide.md)** - Complete usage, configuration, and troubleshooting
- **[Context Generator Guide](docs/context-generator.md)** - AI context generation for better reviews (requires Git repository)
- **[Context7 Integration Guide](docs/context7-integration.md)** - Enhanced reviews with official library documentation (optional)
- **[Developer Guide](docs/developer-guide.md)** - Development setup, architecture, and contributing
## 🤖 AI Tools Disclaimer
<details>
<summary>This project was developed with the assistance of artificial intelligence tools</summary>
**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.
</details>
## 📄 License
MIT License - see LICENSE file for details.
## 👥 Author
- **Author:** Juanje Ojeda
- **Email:** juanje@redhat.com
- **URL:** <https://gitlab.com/redhat/edge/ci-cd/ai-code-review>
Raw data
{
"_id": null,
"home_page": null,
"name": "ai-code-review-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ai, assistant, automation, code quality, code review, coding, developer tools, devops, git, github, github actions, gitlab, gitlab-ci, llm, static code analysis, workflows",
"author": null,
"author_email": "Juanje Ojeda <juanje@redhat.com>",
"download_url": "https://files.pythonhosted.org/packages/01/a8/0583cb638a827ee7f871041a9a29003e93bfde8a436e45ff7f4fc763aadd/ai_code_review_cli-1.14.2.tar.gz",
"platform": null,
"description": "# AI Code Review\n\nAI-powered code review tool with **3 powerful use cases**:\n\n- \ud83e\udd16 **CI Integration** - Automated reviews in your CI/CD pipeline (GitLab or GitHub)\n- \ud83d\udd0d **Local Reviews** - Review your local changes before committing\n- \ud83c\udf10 **Remote Reviews** - Analyze existing MRs/PRs from the terminal\n\n## \ud83d\udcd1 Table of Contents\n\n- [\ud83d\ude80 Primary Use Case: CI/CD Integration](#-primary-use-case-cicd-integration)\n- [\u2699\ufe0f Secondary Use Cases](#\ufe0f-secondary-use-cases)\n - [Local Usage (Container)](#local-usage-container)\n - [Local Usage (CLI Tool)](#local-usage-cli-tool)\n - [Remote Reviews](#remote-reviews)\n- [\ud83d\udd27 Configuration](#-configuration)\n- [\u26a1 Smart Skip Review](#-smart-skip-review)\n- [For Developers](#for-developers)\n- [\ud83d\udd27 Common Issues](#-common-issues)\n- [\ud83d\udcd6 Documentation](#-documentation)\n- [\ud83e\udd16 AI Tools Disclaimer](#-ai-tools-disclaimer)\n- [\ud83d\udcc4 License](#-license)\n- [\ud83d\udc65 Author](#-author)\n\n## \ud83d\ude80 Primary Use Case: CI/CD Integration\n\nThis is the primary and recommended way to use the AI Code Review tool.\n\n### GitLab CI\n\nAdd to `.gitlab-ci.yml`:\n```yaml\nai-review:\n stage: code-review\n image: registry.gitlab.com/redhat/edge/ci-cd/ai-code-review:latest\n variables:\n AI_API_KEY: $GEMINI_API_KEY # Set in CI/CD variables\n script:\n - ai-code-review --post\n rules:\n - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\"'\n allow_failure: true\n```\n\n### GitHub Actions\n\nAdd to `.github/workflows/ai-review.yml`:\n```yaml\nname: AI Code Review\non:\n pull_request:\n types: [opened, synchronize]\n\njobs:\n ai-review:\n runs-on: ubuntu-latest\n permissions:\n contents: read\n pull-requests: write\n container:\n image: registry.gitlab.com/redhat/edge/ci-cd/ai-code-review:latest\n steps:\n - name: Run AI Review\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n AI_API_KEY: ${{ secrets.GEMINI_API_KEY }}\n run: ai-code-review --pr-number ${{ github.event.pull_request.number }} --post\n```\n\n## \u2699\ufe0f Secondary Use Cases\n\n### Local Usage (Container)\n\nThis is the recommended way to use the tool locally, as it doesn't require any installation on your system.\n\n```bash\n# Review local changes\npodman run -it --rm -v .:/app -w /app registry.gitlab.com/redhat/edge/ci-cd/ai-code-review:latest --local\n\n# Review a remote MR\npodman 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\n```\n\n> **Note**: You can use `docker` instead of `podman` and the command should work the same.\n\n### Local Usage (CLI Tool)\n\nThis is a good option if you have Python installed and want to use the tool as a CLI command.\n\n> **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`.\n\n`pipx` is a more mature and well-known tool for the same purpose. It handles the package vs. command name difference automatically.\n\n```bash\n# Install pipx\npip install pipx\npipx ensurepath\n\n# Install the package\npipx install ai-code-review-cli\n\n# Run the command\nai-code-review --local\n```\n\n### Remote Reviews\n\nYou can also analyze existing MRs/PRs from your terminal.\n\n```bash\n# GitLab MR\nai-code-review group/project 123\n\n# GitHub PR\nai-code-review --platform github owner/repo 456\n\n# Save to file\nai-code-review group/project 123 -o review.md\n\n# Post the review to the MR/PR\nai-code-review group/project 123 --post\n```\n\n## \ud83d\udd27 Configuration\n\n### Required Setup\n\n#### 1. Platform Token (Not needed for local reviews)\n\n```bash\n# For GitLab remote reviews\nexport GITLAB_TOKEN=glpat_xxxxxxxxxxxxxxxxxxxx\n\n# For GitHub remote reviews\nexport GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx\n\n# Local reviews don't need platform tokens! \ud83c\udf89\n```\n\n#### 2. AI API Key\n\n```bash\n# Get key from: https://makersuite.google.com/app/apikey\nexport AI_API_KEY=your_gemini_api_key_here\n```\n\n### Configuration Methods (Priority Order)\n\nThe tool supports **4 configuration methods** with the following priority:\n\n1. **\ud83d\udd34 CLI Arguments** (highest priority) - `--provider anthropic --model claude-sonnet-4-20250514`\n2. **\ud83d\udfe1 Environment Variables** - `export AI_PROVIDER=anthropic`\n3. **\ud83d\udfe2 Configuration File** - `.ai_review/config.yml`\n4. **\u26aa Field Defaults** (lowest priority) - Built-in defaults\n\n### Configuration File\n\nCreate a YAML configuration file for persistent settings:\n\n```bash\n# Create from template\ncp .ai_review/config.yml.example .ai_review/config.yml\n\n# Edit your project settings\nnano .ai_review/config.yml\n```\n\n**Key benefits:**\n- \u2705 **Project-specific settings** - Different configs per repository\n- \u2705 **Team sharing** - Commit to git for consistent team settings\n- \u2705 **Reduced typing** - Set common options once\n- \u2705 **Layered override** - CLI arguments still override everything\n\n**File locations:**\n- **Auto-detected**: `.ai_review/config.yml` (loaded automatically if exists)\n- **Custom path**: `--config-file path/to/custom.yml`\n- **Disable loading**: `--no-config-file` flag\n\n### Environment Variables\n\nFor sensitive data and CI/CD environments:\n```bash\n# Copy template\ncp env.example .env\n\n# Edit and set your tokens\nGITLAB_TOKEN=glpat_xxxxxxxxxxxxxxxxxxxx\nAI_API_KEY=your_gemini_api_key_here\n```\n\n### Common Options\n\n```bash\n# Different AI providers\nai-code-review project/123 --provider anthropic # Claude\nai-code-review project/123 --provider ollama # Local Ollama\n\n# Custom server URLs\nai-code-review project/123 --gitlab-url https://gitlab.company.com\n\n# Output options\nai-code-review project/123 -o review.md # Save to file\nai-code-review project/123 2>logs.txt # Logs to stderr\n```\n\n**For all configuration options, troubleshooting, and advanced usage \u2192 see [User Guide](docs/user-guide.md)**\n\n## \u26a1 Smart Skip Review\n\n**AI Code Review automatically skips unnecessary reviews** to reduce noise and costs:\n\n- \ud83d\udd04 **Dependency updates** (`chore(deps): bump lodash 4.1.0 to 4.2.0`)\n- \ud83e\udd16 **Bot changes** (from `dependabot[bot]`, `renovate[bot]`)\n- \ud83d\udcdd **Documentation-only** changes (if enabled)\n- \ud83c\udff7\ufe0f **Tagged PRs/MRs** (`[skip review]`, `[automated]`)\n- \ud83d\udcdd **Draft/WIP PRs/MRs** (work in progress)\n\n**Result:** Focus on meaningful changes, save API costs, faster CI/CD pipelines.\n\n> **\ud83d\udcd6 Learn more:** Configuration, customization, and CI integration \u2192 [User Guide - Skip Review](docs/user-guide.md#smart-skip-review)\n\n## For Developers\n\n### Development Setup\n\n```bash\n# Install using uv (recommended)\nuv sync\n\n# Or with pip\npip install -e .\n```\n\n> To install or learn more about `uv`, check here:\n[uv](https://docs.astral.sh/uv)\n\n## \ud83d\udd27 Common Issues\n\n### gRPC Warnings with Google Gemini\n\nWhen using Google Gemini provider, you may see harmless gRPC connection warnings:\n\n```\nWARNING: All log messages before absl::InitializeLog() is called are written to STDERR\nI0000 00:00:1759934851.372144 Other threads are currently calling into gRPC, skipping fork() handlers\n```\n\n**These warnings are harmless and don't affect functionality.** To suppress them:\n\n```bash\n# Suppress warnings by redirecting stderr\nai-code-review --local 2>/dev/null\nai-generate-context . 2>/dev/null\n\n# Or use alternative provider (no warnings)\nai-code-review --local --provider ollama\n```\n\n## \ud83d\udcd6 Documentation\n\n- **[User Guide](docs/user-guide.md)** - Complete usage, configuration, and troubleshooting\n- **[Context Generator Guide](docs/context-generator.md)** - AI context generation for better reviews (requires Git repository)\n- **[Context7 Integration Guide](docs/context7-integration.md)** - Enhanced reviews with official library documentation (optional)\n- **[Developer Guide](docs/developer-guide.md)** - Development setup, architecture, and contributing\n\n## \ud83e\udd16 AI Tools Disclaimer\n\n<details>\n<summary>This project was developed with the assistance of artificial intelligence tools</summary>\n\n**Tools used:**\n- **Cursor**: Code editor with AI capabilities\n- **Claude-Sonnet-4**: Anthropic's language model (claude-sonnet-4-20250514)\n\n**Division of responsibilities:**\n\n**AI (Cursor + Claude-Sonnet-4)**:\n- \ud83d\udd27 Initial code prototyping\n- \ud83d\udcdd Generation of examples and test cases\n- \ud83d\udc1b Assistance in debugging and error resolution\n- \ud83d\udcda Documentation and comments writing\n- \ud83d\udca1 Technical implementation suggestions\n\n**Human (Juanje Ojeda)**:\n- \ud83c\udfaf Specification of objectives and requirements\n- \ud83d\udd0d Critical review of code and documentation\n- \ud83d\udcac Iterative feedback and solution refinement\n- \u2705 Final validation of concepts and approaches\n\n**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.\n</details>\n\n## \ud83d\udcc4 License\n\nMIT License - see LICENSE file for details.\n\n## \ud83d\udc65 Author\n\n- **Author:** Juanje Ojeda\n- **Email:** juanje@redhat.com\n- **URL:** <https://gitlab.com/redhat/edge/ci-cd/ai-code-review>\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-powered code review tool with local Git, remote MR/PR analysis, and CI integration (GitLab or GitHub)",
"version": "1.14.2",
"project_urls": {
"Homepage": "https://gitlab.com/redhat/edge/ci-cd/ai-code-review",
"Issues": "https://gitlab.com/redhat/edge/ci-cd/ai-code-review/-/issues",
"Repository": "https://gitlab.com/redhat/edge/ci-cd/ai-code-review"
},
"split_keywords": [
"ai",
" assistant",
" automation",
" code quality",
" code review",
" coding",
" developer tools",
" devops",
" git",
" github",
" github actions",
" gitlab",
" gitlab-ci",
" llm",
" static code analysis",
" workflows"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9fb41898e3473f81670ecec07bc333318a2bcb8157fc36e6115eeec66051a406",
"md5": "e208bb500e55eac684300683b37c3f65",
"sha256": "9b94bec64658b605a9d235513d7a6ce28ecc341a25b9d8b326503305b285d18a"
},
"downloads": -1,
"filename": "ai_code_review_cli-1.14.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e208bb500e55eac684300683b37c3f65",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 119125,
"upload_time": "2025-10-18T16:34:05",
"upload_time_iso_8601": "2025-10-18T16:34:05.611288Z",
"url": "https://files.pythonhosted.org/packages/9f/b4/1898e3473f81670ecec07bc333318a2bcb8157fc36e6115eeec66051a406/ai_code_review_cli-1.14.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "01a80583cb638a827ee7f871041a9a29003e93bfde8a436e45ff7f4fc763aadd",
"md5": "55cc982131dc814d00c564c878078e80",
"sha256": "e4f7753fd0831d85d3ab23fac592e0741a7a6e35098301b7a6340a9b4bdccd67"
},
"downloads": -1,
"filename": "ai_code_review_cli-1.14.2.tar.gz",
"has_sig": false,
"md5_digest": "55cc982131dc814d00c564c878078e80",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 384125,
"upload_time": "2025-10-18T16:34:07",
"upload_time_iso_8601": "2025-10-18T16:34:07.555348Z",
"url": "https://files.pythonhosted.org/packages/01/a8/0583cb638a827ee7f871041a9a29003e93bfde8a436e45ff7f4fc763aadd/ai_code_review_cli-1.14.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-18 16:34:07",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "redhat",
"gitlab_project": "edge",
"lcname": "ai-code-review-cli"
}
JSON