ai-code-review-cli
Advanced tools
AI-powered code review tool with local Git, remote MR/PR analysis, and CI integration (GitLab, GitHub or Forgejo)
AI-powered code review tool with 3 powerful use cases:
This is the primary and recommended way to use the AI Code Review tool.
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
Add to .github/workflows/ai-review.yml:
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
ai-review:
runs-on: ubuntu-latest
if: github.event_name == 'pull_request'
continue-on-error: true
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
Add to .forgejo/workflows/ai-review.yml:
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
ai-review:
runs-on: codeberg-tiny # adjust for non-codeberg instances
continue-on-error: true
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:
AI_API_KEY: ${{ secrets.GEMINI_API_KEY }} # set in Forgejo Actions secrets
run: ai-code-review --pr-number ${{ github.event.pull_request.number }} --post
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 \
ai-code-review --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 \
ai-code-review group/project 123
Note: You can use
dockerinstead ofpodmanand the command should work the same.
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 remainsai-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
You can also analyze existing MRs/PRs from your terminal.
# GitLab MR
ai-code-review group/project 123
# GitHub PR
ai-code-review --platform-provider 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
# For GitLab remote reviews
export GITLAB_TOKEN=glpat_xxxxxxxxxxxxxxxxxxxx
# For GitHub remote reviews
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# For Forgejo remote reviews
export FORGEJO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Local reviews don't need platform tokens! 🎉
# Get key from: https://makersuite.google.com/app/apikey
export AI_API_KEY=your_gemini_api_key_here
The tool supports 4 configuration methods with the following priority:
--ai-provider anthropic --ai-model claude-sonnet-4-5export AI_PROVIDER=anthropic.ai_review/config.ymlCreate 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:
File locations:
.ai_review/config.yml (loaded automatically if exists)--config-file path/to/custom.yml--no-config-file flagFor 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
# Different AI providers
ai-code-review project/123 --ai-provider anthropic # Claude
ai-code-review project/123 --ai-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
For teams working on multiple projects, you can specify a shared team context that applies organization-wide:
# Remote team context (recommended - stored in central repo)
export TEAM_CONTEXT_FILE=https://gitlab.com/org/standards/-/raw/main/review.md
ai-code-review --local
# Or use CLI option
ai-code-review project/123 --team-context-file https://company.com/standards/review.md --post
# Local team context file
ai-code-review --team-context-file ../team-standards.md --local
Use cases:
Priority order: Team context → Project context → Commit history
This allows maintaining org standards while individual projects add specific guidelines.
See User Guide - Team Context for complete documentation.
The tool uses a two-phase approach to incorporate previous reviews and avoid repeating mistakes:
Phase 1 - Synthesis (automatic):
gemini-3-flash-preview) to synthesize key insightsPhase 2 - Main Review:
Benefits:
Configuration:
# Enable/disable (default: enabled)
enable_review_context: true
enable_review_synthesis: true
# Custom synthesis model (optional)
synthesis_model: "gemini-3-flash-preview" # Default for Gemini
# synthesis_model: "claude-haiku-4-5" # For Anthropic
# synthesis_model: "gpt-4o-mini" # For OpenAI
Skips automatically when:
AI Code Review automatically skips unnecessary reviews to reduce noise and costs:
chore(deps): bump lodash 4.1.0 to 4.2.0)dependabot[bot], renovate[bot])[skip review], [automated])Result: Focus on meaningful changes, save API costs, faster CI/CD pipelines.
📖 Learn more: Configuration, customization, and CI integration → User Guide - Skip Review
# Install using uv (recommended)
uv sync --all-extras
# Or with pip
pip install -e .
To install or learn more about
uv, check here: uv
Adding a .ai_review/project.md file to your repository is the single most effective thing
you can do to improve review quality. Without it, the AI reviewer sees only the diff — it
doesn't know your architecture, your internal libraries, or the conventions your team follows.
With it, the quality difference is dramatic.
Three specific problems a context file solves:
Stale knowledge — LLMs have a training cutoff. Without a context file, reviewers suggest outdated library versions, flag current versions as "non-existent", and recommend deprecated APIs. A context file with your actual dependency versions fixes this completely.
Diff-only visibility — The reviewer sees only the changed lines, not how they connect to the rest of the system. A context file explains your architecture, patterns, and abstractions so the reviewer can judge whether a change fits or conflicts with the codebase.
Internal/proprietary knowledge — Your internal libraries, custom frameworks, and team conventions are unknown to any LLM. Without documentation, the reviewer will make wrong assumptions about them. The context file tells it what's internal and how it works.
How to create one: Use the
context-generator skill — a standalone AI
agent skill for Claude Code and Cursor that generates and maintains .ai_review/project.md
automatically. Install it once and ask your assistant to generate the file:
# Install for Claude Code
git clone https://github.com/juanje/context-generator.git ~/.claude/skills/context-generator
# Install for Cursor
git clone https://github.com/juanje/context-generator.git ~/.cursor/skills/context-generator
Then: "Generate a context file for this project"
Commit .ai_review/project.md to your repository. The CI/CD review job picks it up
automatically on every MR/PR — no extra configuration needed.
Tools used:
Division of responsibilities:
AI (Cursor + Claude-Sonnet-4.5):
Human (Juanje Ojeda):
Crotchety old human (Adam Williamson):
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.
MIT License - see LICENSE file for details.
FAQs
AI-powered code review tool with local Git, remote MR/PR analysis, and CI integration (GitLab, GitHub or Forgejo)
We found that ai-code-review-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Socket detected malicious node-ipc versions with obfuscated stealer/backdoor behavior in a developing npm supply chain attack.
Security News
TeamPCP and BreachForums are promoting a Shai-Hulud supply chain attack contest with a $1,000 prize for the biggest package compromise.
Security News
Packagist urges PHP projects to update Composer after a GitHub token format change exposed some GitHub Actions tokens in CI logs.