🤖 AI Code Review

Provider-agnostic code review using AI
Use Claude, Gemini, Codex, Ollama, or any AI to enforce your coding standards.
Zero dependencies. Pure Bash. Works everywhere.

Installation • Quick Start • Providers • Commands • Configuration • Example

🎯 Why?

You have coding standards. Your team ignores them. Code reviews catch issues too late.

AI Code Review runs on every commit, validating your staged files against your project's AGENTS.md (or any rules file). It's like having a senior developer review every line before it hits the repo.

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   git commit    │ ──▶ │  AI Review   │ ──▶ │  ✅ Pass/Fail   │
│  (staged files) │     │  (any LLM)   │     │  (with details) │
└─────────────────┘     └──────────────┘     └─────────────────┘

Key features:

🔌 Provider agnostic - Use whatever AI you have installed
📦 Zero dependencies - Pure Bash, no Node/Python/Go required
🪝 Git native - Installs as a standard pre-commit hook
⚙️ Highly configurable - File patterns, exclusions, custom rules
🚨 Strict mode - Fail CI on ambiguous responses
🍺 Homebrew ready - One command install

📦 Installation

Homebrew (Recommended) 🍺

brew tap gentleman-programming/tap
brew install ai-code-review

Or in a single command:

brew install gentleman-programming/tap/ai-code-review

Manual Installation

git clone https://github.com/Gentleman-Programming/ai-code-review.git
cd ai-code-review
./install.sh

Verify Installation

ai-code-review version
# Output: ai-code-review v1.0.0

🚀 Quick Start

# 1. Go to your project
cd ~/your-project

# 2. Initialize config
ai-code-review init

# 3. Create your rules file
touch AGENTS.md  # Add your coding standards

# 4. Install the git hook
ai-code-review install

# 5. Done! Now every commit gets reviewed 🎉

🎬 Real World Example

Let's walk through a complete example from setup to commit:

Step 1: Setup in your project

$ cd ~/projects/my-react-app

$ ai-code-review init

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  AI Code Review v1.0.0
  Provider-agnostic code review using AI
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Created config file: .ai-code-review

ℹ️  Next steps:
  1. Edit .ai-code-review to set your preferred provider
  2. Create AGENTS.md with your coding standards
  3. Run: ai-code-review install

Step 2: Configure your provider

$ cat .ai-code-review

# AI Provider (required)
PROVIDER="claude"

# File patterns to include in review (comma-separated)
FILE_PATTERNS="*.ts,*.tsx,*.js,*.jsx"

# File patterns to exclude from review (comma-separated)
EXCLUDE_PATTERNS="*.test.ts,*.spec.ts,*.test.tsx,*.spec.tsx,*.d.ts"

# File containing code review rules
RULES_FILE="AGENTS.md"

# Strict mode: fail if AI response is ambiguous
STRICT_MODE="true"

Step 3: Create your coding standards

$ cat > AGENTS.md << 'EOF'
# Code Review Rules

## TypeScript
- No `any` types - use proper typing
- Use `const` over `let` when possible
- Prefer interfaces over type aliases for objects

## React  
- Use functional components with hooks
- No `import * as React` - use named imports like `import { useState }`
- All images must have alt text for accessibility

## Styling
- Use Tailwind CSS utilities only
- No inline styles or CSS-in-JS
- No hardcoded colors - use design system tokens
EOF

Step 4: Install the git hook

$ ai-code-review install

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  AI Code Review v1.0.0
  Provider-agnostic code review using AI
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Installed pre-commit hook: /Users/dev/projects/my-react-app/.git/hooks/pre-commit

Step 5: Make some changes and commit

$ git add src/components/Button.tsx
$ git commit -m "feat: add new button component"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  AI Code Review v1.0.0
  Provider-agnostic code review using AI
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ️  Provider: claude
ℹ️  Rules file: AGENTS.md
ℹ️  File patterns: *.ts,*.tsx,*.js,*.jsx

Files to review:
  - src/components/Button.tsx

ℹ️  Sending to claude for review...

STATUS: FAILED

Violations found:

1. **src/components/Button.tsx:3** - TypeScript Rule
   - Issue: Using `any` type for props
   - Fix: Define proper interface for ButtonProps

2. **src/components/Button.tsx:15** - React Rule  
   - Issue: Using `import * as React`
   - Fix: Use `import { useState, useCallback } from 'react'`

3. **src/components/Button.tsx:22** - Styling Rule
   - Issue: Hardcoded color `#3b82f6`
   - Fix: Use Tailwind class `bg-blue-500` instead

❌ CODE REVIEW FAILED

Fix the violations listed above before committing.

Step 6: Fix issues and commit again

$ git add src/components/Button.tsx
$ git commit -m "feat: add new button component"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  AI Code Review v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ️  Provider: claude
ℹ️  Files to review:
  - src/components/Button.tsx

ℹ️  Sending to claude for review...

STATUS: PASSED

All files comply with the coding standards defined in AGENTS.md.

✅ CODE REVIEW PASSED

[main 4a2b3c1] feat: add new button component
 1 file changed, 45 insertions(+)
 create mode 100644 src/components/Button.tsx

📋 Commands

Command	Description	Example
`init`	Create sample `.ai-code-review` config file	`ai-code-review init`
`install`	Install git pre-commit hook in current repo	`ai-code-review install`
`uninstall`	Remove git pre-commit hook from current repo	`ai-code-review uninstall`
`run`	Run code review manually on staged files	`ai-code-review run`
`config`	Display current configuration and status	`ai-code-review config`
`help`	Show help message with all commands	`ai-code-review help`
`version`	Show installed version	`ai-code-review version`

Command Details

`ai-code-review init`

Creates a sample .ai-code-review configuration file in your project root with sensible defaults.

$ ai-code-review init
✅ Created config file: .ai-code-review

`ai-code-review install`

Installs a git pre-commit hook that automatically runs code review on every commit.

$ ai-code-review install
✅ Installed pre-commit hook: .git/hooks/pre-commit

If a pre-commit hook already exists, it will ask if you want to append to it.

`ai-code-review uninstall`

Removes the git pre-commit hook from your repository.

$ ai-code-review uninstall
✅ Removed pre-commit hook

`ai-code-review run`

Manually runs code review on currently staged files. Useful for testing before committing.

$ git add src/components/Button.tsx
$ ai-code-review run
# Reviews the staged file

`ai-code-review config`

Shows the current configuration, including where config files are loaded from and all settings.

$ ai-code-review config

Current Configuration:

Config Files:
  Global:  Not found
  Project: .ai-code-review

Values:
  PROVIDER:          claude
  FILE_PATTERNS:     *.ts,*.tsx,*.js,*.jsx
  EXCLUDE_PATTERNS:  *.test.ts,*.spec.ts
  RULES_FILE:        AGENTS.md
  STRICT_MODE:       true

Rules File: Found

🔌 Providers

Use whichever AI CLI you have installed:

Provider	Config Value	CLI Command Used	Installation
Claude	`claude`	`echo "prompt" \| claude --print`	claude.ai/code
Gemini	`gemini`	`echo "prompt" \| gemini`	github.com/google-gemini/gemini-cli
Codex	`codex`	`codex exec "prompt"`	`npm i -g @openai/codex`
Ollama	`ollama:<model>`	`ollama run <model> "prompt"`	ollama.ai

Provider Examples

# Use Claude (recommended - most reliable)
PROVIDER="claude"

# Use Google Gemini
PROVIDER="gemini"

# Use OpenAI Codex
PROVIDER="codex"

# Use Ollama with Llama 3.2
PROVIDER="ollama:llama3.2"

# Use Ollama with CodeLlama (optimized for code)
PROVIDER="ollama:codellama"

# Use Ollama with Qwen Coder
PROVIDER="ollama:qwen2.5-coder"

# Use Ollama with DeepSeek Coder
PROVIDER="ollama:deepseek-coder"

⚙️ Configuration

Config File: `.ai-code-review`

Create this file in your project root:

# AI Provider (required)
# Options: claude, gemini, codex, ollama:<model>
PROVIDER="claude"

# File patterns to review (comma-separated globs)
# Default: * (all files)
FILE_PATTERNS="*.ts,*.tsx,*.js,*.jsx"

# Patterns to exclude from review (comma-separated globs)
# Default: none
EXCLUDE_PATTERNS="*.test.ts,*.spec.ts,*.d.ts"

# File containing your coding standards
# Default: AGENTS.md
RULES_FILE="AGENTS.md"

# Fail if AI response is ambiguous (recommended for CI)
# Default: true
STRICT_MODE="true"

Configuration Options

Option	Required	Default	Description
`PROVIDER`	✅ Yes	-	AI provider to use
`FILE_PATTERNS`	No	`*`	Comma-separated file patterns to include
`EXCLUDE_PATTERNS`	No	-	Comma-separated file patterns to exclude
`RULES_FILE`	No	`AGENTS.md`	Path to your coding standards file
`STRICT_MODE`	No	`true`	Fail on ambiguous AI responses

Config Hierarchy (Priority Order)

Environment variable AI_CODE_REVIEW_PROVIDER (highest priority)
Project config .ai-code-review (in project root)
Global config ~/.config/ai-code-review/config (lowest priority)

# Override provider for a single run
AI_CODE_REVIEW_PROVIDER="gemini" ai-code-review run

# Or export for the session
export AI_CODE_REVIEW_PROVIDER="ollama:llama3.2"

📝 Rules File (AGENTS.md)

The AI needs to know your standards. Create an AGENTS.md file:

# Code Review Rules

## TypeScript
- Use `const` and `let`, never `var`
- No `any` types - always use proper typing
- Prefer interfaces over type aliases for objects
- Use optional chaining (`?.`) and nullish coalescing (`??`)

## React
- Functional components only, no class components
- No `import * as React` - use named imports
- Use semantic HTML elements
- All images need alt text
- Interactive elements need aria labels

## Styling
- Use Tailwind CSS utilities
- No inline styles
- No hex colors - use design tokens

## Testing
- All new features need tests
- Test files must be co-located with source files
- Use descriptive test names that explain the behavior

💡 Pro tip: Your AGENTS.md can also serve as documentation for human reviewers!

🎨 Project Examples

TypeScript/React Project

# .ai-code-review
PROVIDER="claude"
FILE_PATTERNS="*.ts,*.tsx"
EXCLUDE_PATTERNS="*.test.ts,*.test.tsx,*.spec.ts,*.d.ts,*.stories.tsx"
RULES_FILE="AGENTS.md"

Python Project

# .ai-code-review
PROVIDER="ollama:codellama"
FILE_PATTERNS="*.py"
EXCLUDE_PATTERNS="*_test.py,test_*.py,conftest.py,__pycache__/*"
RULES_FILE=".coding-standards.md"

Go Project

# .ai-code-review
PROVIDER="gemini"
FILE_PATTERNS="*.go"
EXCLUDE_PATTERNS="*_test.go,mock_*.go,*_mock.go"

Full-Stack Monorepo

# .ai-code-review
PROVIDER="claude"
FILE_PATTERNS="*.ts,*.tsx,*.py,*.go"
EXCLUDE_PATTERNS="*.test.*,*_test.*,*.mock.*,*.d.ts,dist/*,build/*"

🔄 How It Works

git commit -m "feat: add feature"
    │
    ▼
┌───────────────────────────────────────┐
│  Pre-commit Hook (ai-code-review run) │
└───────────────────────────────────────┘
    │
    ├──▶ 1. Load config from .ai-code-review
    │
    ├──▶ 2. Validate provider is installed
    │
    ├──▶ 3. Check AGENTS.md exists
    │
    ├──▶ 4. Get staged files matching FILE_PATTERNS
    │       (excluding EXCLUDE_PATTERNS)
    │
    ├──▶ 5. Read coding rules from AGENTS.md
    │
    ├──▶ 6. Build prompt: rules + file contents
    │
    ├──▶ 7. Send to AI provider (claude/gemini/codex/ollama)
    │
    └──▶ 8. Parse response
            │
            ├── "STATUS: PASSED" ──▶ ✅ Commit proceeds
            │
            └── "STATUS: FAILED" ──▶ ❌ Commit blocked
                                       (shows violation details)

🚫 Bypass Review

Sometimes you need to commit without review:

# Skip pre-commit hook entirely
git commit --no-verify -m "wip: work in progress"

# Short form
git commit -n -m "hotfix: urgent fix"

🔗 Integrations

AI Code Review works standalone with native git hooks, but you can also integrate it with popular hook managers.

Native Git Hook (Default)

This is what ai-code-review install does automatically:

# .git/hooks/pre-commit
#!/usr/bin/env bash
ai-code-review run || exit 1

Husky (Node.js projects)

Husky is popular in JavaScript/TypeScript projects.

Setup with Husky v9+

# Install husky
npm install -D husky

# Initialize husky
npx husky init

Edit .husky/pre-commit:

#!/usr/bin/env bash

# Run AI Code Review
ai-code-review run || exit 1

# Your other checks (optional)
npm run lint
npm run typecheck

With lint-staged (review only staged files)

# Install dependencies
npm install -D husky lint-staged

package.json:

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

.husky/pre-commit:

#!/usr/bin/env bash

# AI Review first (uses git staged files internally)
ai-code-review run || exit 1

# Then lint-staged for formatting
npx lint-staged

pre-commit (Python projects)

pre-commit is the standard for Python projects.

Setup

# Install pre-commit
pip install pre-commit

# Or with brew
brew install pre-commit

Create .pre-commit-config.yaml:

repos:
  # AI Code Review (runs first)
  - repo: local
    hooks:
      - id: ai-code-review
        name: AI Code Review
        entry: ai-code-review run
        language: system
        pass_filenames: false
        stages: [pre-commit]

  # Your other hooks
  - repo: https://github.com/psf/black
    rev: 24.4.2
    hooks:
      - id: black

  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy

Install the hooks:

pre-commit install

Running manually

# Run all hooks
pre-commit run --all-files

# Run only AI review
pre-commit run ai-code-review

Lefthook (Fast, language-agnostic)

Lefthook is a fast Git hooks manager written in Go.

Setup

# Install
brew install lefthook

# Or with npm
npm install -D lefthook

Create lefthook.yml:

pre-commit:
  parallel: false
  commands:
    ai-review:
      run: ai-code-review run
      fail_text: "AI Code Review failed. Fix violations before committing."

    lint:
      glob: "*.{ts,tsx,js,jsx}"
      run: npm run lint

    typecheck:
      run: npm run typecheck

Install hooks:

lefthook install

CI/CD Integration

You can also run AI Code Review in your CI pipeline:

GitHub Actions

# .github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install AI Code Review
        run: |
          git clone https://github.com/Gentleman-Programming/ai-code-review.git /tmp/ai-code-review
          chmod +x /tmp/ai-code-review/bin/ai-code-review
          echo "/tmp/ai-code-review/bin" >> $GITHUB_PATH

      - name: Install Claude CLI
        run: |
          # Install your preferred provider CLI
          npm install -g @anthropic-ai/claude-code
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Run AI Review
        run: |
          # Get changed files in PR
          git diff --name-only origin/${{ github.base_ref }}...HEAD > /tmp/changed_files.txt
          
          # Stage them for review
          cat /tmp/changed_files.txt | xargs git add
          
          # Run review
          ai-code-review run

GitLab CI

# .gitlab-ci.yml
ai-code-review:
  stage: test
  image: ubuntu:latest
  before_script:
    - apt-get update && apt-get install -y git curl
    - git clone https://github.com/Gentleman-Programming/ai-code-review.git /opt/ai-code-review
    - export PATH="/opt/ai-code-review/bin:$PATH"
    # Install your provider CLI here
  script:
    - git diff --name-only $CI_MERGE_REQUEST_DIFF_BASE_SHA | xargs git add
    - ai-code-review run
  only:
    - merge_requests

🐛 Troubleshooting

"Provider not found"

# Check if your provider CLI is installed and in PATH
which claude   # Should show: /usr/local/bin/claude or similar
which gemini
which codex
which ollama

# Test if the provider works
echo "Say hello" | claude --print

"Rules file not found"

The tool requires a rules file to know what to check:

# Create your rules file
touch AGENTS.md

# Add your coding standards
echo "# My Coding Standards" > AGENTS.md
echo "- No console.log in production" >> AGENTS.md

"Ambiguous response" in Strict Mode

The AI must respond with STATUS: PASSED or STATUS: FAILED as the first line. If it doesn't:

Try Claude (most reliable at following instructions)
Check your rules file isn't confusing the AI
Temporarily disable strict mode: STRICT_MODE="false"

Slow reviews on large files

The tool sends full file contents. For better performance:

# Add large/generated files to exclude
EXCLUDE_PATTERNS="*.min.js,*.bundle.js,dist/*,build/*,*.generated.ts"

🤝 Contributing

Contributions are welcome! Some ideas:

Add more providers (Copilot, Codeium, etc.)
Support for .ai-code-review.yaml format
Caching to avoid re-reviewing unchanged files
GitHub Action version
Output formats (JSON, SARIF for IDE integration)

# Fork, clone, and submit PRs!
git clone https://github.com/Gentleman-Programming/ai-code-review.git

📄 License

_{Built with 🧉 by developers who got tired of repeating the same code review comments}

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
bin		bin
lib		lib
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
uninstall.sh		uninstall.sh

License

Gentleman-Programming/ai-code-review

Folders and files

Latest commit

History

Repository files navigation

🤖 AI Code Review

🎯 Why?

📦 Installation

Homebrew (Recommended) 🍺

Manual Installation

Verify Installation

🚀 Quick Start

🎬 Real World Example

Step 1: Setup in your project

Step 2: Configure your provider

Step 3: Create your coding standards

Step 4: Install the git hook

Step 5: Make some changes and commit

Step 6: Fix issues and commit again

📋 Commands

Command Details

ai-code-review init

ai-code-review install

ai-code-review uninstall

ai-code-review run

ai-code-review config

🔌 Providers

Provider Examples

⚙️ Configuration

Config File: .ai-code-review

Configuration Options

Config Hierarchy (Priority Order)

📝 Rules File (AGENTS.md)

🎨 Project Examples

TypeScript/React Project

Python Project

Go Project

Full-Stack Monorepo

🔄 How It Works

🚫 Bypass Review

🔗 Integrations

Native Git Hook (Default)

Husky (Node.js projects)

Setup with Husky v9+

With lint-staged (review only staged files)

pre-commit (Python projects)

Setup

Running manually

Lefthook (Fast, language-agnostic)

Setup

CI/CD Integration

GitHub Actions

GitLab CI

🐛 Troubleshooting

"Provider not found"

"Rules file not found"

"Ambiguous response" in Strict Mode

Slow reviews on large files

🤝 Contributing

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

`ai-code-review init`

`ai-code-review install`

`ai-code-review uninstall`

`ai-code-review run`

`ai-code-review config`

Config File: `.ai-code-review`

Packages