AI Review CLI

🤖 AI-powered code review tool with OpenAI GPT-4 and Claude Code integration

Overview

AI Review CLI automatically detects modified files in your git repository, analyzes them with OpenAI GPT-4 for issues, and can automatically apply fixes using Claude Code. Perfect for maintaining code quality across any project.

Features

• 🔍 Automatic Git Integration - Detects modified and staged files
• 🤖 OpenAI GPT-4 Analysis - Intelligent code review with categorized feedback
• 🛠️ Claude Code Integration - Automated fix application
• ⚙️ Configurable - Customizable project context and focus areas
• 🎯 Interactive Selection - Choose which issues to fix
• 📊 Severity Classification - High, medium, low priority issues
• 🏷️ Category Grouping - Security, performance, bugs, style, maintainability

Installation

Global Installation (Recommended)

npm install -g @sgeier/ai-review

Use with npx (No Installation)

npx @sgeier/ai-review

Prerequisites

1. OpenAI API Key - Get one from OpenAI Platform
2. Claude Code (optional but recommended) - Install from claude.ai/code
3. Git Repository - Works with any git repository

Quick Start

1. Set your OpenAI API key globally:

   # Set for current session
   export OPENAI_API_KEY=your-key-here
      
   # Or add to your shell profile for persistence (recommended)
   echo "export OPENAI_API_KEY=your-key-here" >> ~/.zshrc
   # Then restart your terminal or run: source ~/.zshrc

   Note: You can also create a .env file in individual projects, but the global approach works everywhere.

2. Initialize configuration (optional):

   ai-review init

3. Make some code changes and run:

   ai-review

Usage

Basic Usage

# Review all modified files
ai-review

# Initialize configuration for your project
ai-review init

# Initialize with specific project type  
ai-review init gatsby-react-typescript

# Validate your setup
ai-review validate

# Show version
ai-review version

# Show help
ai-review help

Interactive Selection

When issues are found, you can select which ones to fix:

• Specific numbers: 1,3,5 or 1-5
• By severity: high, medium, low
• By category: security, performance, bug, style, maintainability
• Shortcuts: all, none, green (low), yellow (medium), red (high)
• Exit: quit or q

Configuration

Create a .ai-review.json file in your project root to customize behavior:

{
  "projectType": "gatsby-react-typescript",
  "description": "Gatsby 5 + React 18 + TypeScript project",
  "technologies": ["React", "TypeScript", "SCSS", "Three.js"],
  "focus": [
    "TypeScript best practices",
    "React 18 patterns", 
    "performance optimization",
    "accessibility",
    "security"
  ],
  "model": "gpt-4",
  "temperature": 0.1,
  "autoFix": false,
  "includeFileTypes": [".js", ".jsx", ".ts", ".tsx", ".vue"],
  "excludeFileTypes": [".min.js", ".bundle.js", ".d.ts"],
  "excludePaths": ["node_modules/", "dist/", "build/"],
  "claudeInstructions": "Follow the project's existing conventions"
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | projectType | string | "generic" | Type of project for context | | description | string | "Software development project" | Project description | | technologies | array | [] | Technologies used in project | | focus | array | ["code quality", "best practices", "security", "performance"] | Areas to focus on | | model | string | "gpt-4" | OpenAI model to use | | temperature | number | 0.1 | Model creativity (0-2) | | autoFix | boolean | false | Automatically fix all issues | | includeFileTypes | array | Common file extensions | File types to include | | excludeFileTypes | array | Build/generated files | File types to exclude | | excludePaths | array | ["node_modules/", ...] | Paths to exclude | | claudeInstructions | string | Generic instructions | Custom instructions for Claude Code |

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OPENAI_API_KEY | ✅ | - | Your OpenAI API key | | OPENAI_MODEL | ❌ | gpt-4.1 | OpenAI model to use | | OPENAI_TEMPERATURE | ❌ | 0.1 | Model temperature (0-2) | | AI_REVIEW_AUTO_FIX | ❌ | false | Enable auto-fix mode |

Examples

Example 1: Basic Review

# Make some changes to your code
git add .
ai-review

# Output:
# 🚀 Starting AI Code Review...
# 📁 Found 3 modified files:
#   - src/components/Button.tsx
#   - src/utils/helpers.js  
#   - styles/main.scss
# 
# 🤖 Sending code to OpenAI for review...
# 
# 📋 AI Code Review Results (5 issues found):
# ============================================================
# 
# 1. 🔴 🔒 Missing input validation
#    📁 src/utils/helpers.js:15
#    📝 Function accepts user input without validation
#    💡 Add input validation and sanitization

Example 2: Project-Specific Configuration

# Initialize for a React TypeScript project
ai-review init react-typescript

# This creates .ai-review.json with React/TypeScript specific settings
# Then run normal review
ai-review

Example 3: Selective Fixing

ai-review

# When prompted, choose what to fix:
# 👉 Enter your choice: security,high
# 
# This will fix all security issues and all high-priority issues

Integration Examples

GitHub Actions

name: AI Code Review
on: [pull_request]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm install -g @sgeier/ai-review
      - run: ai-review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Pre-commit Hook

# .git/hooks/pre-commit
#!/bin/bash
export OPENAI_API_KEY=your-key-here
ai-review --auto-fix

Project Types

The CLI comes with built-in configurations for common project types:

• gatsby-react-typescript - Gatsby + React + TypeScript
• nextjs-react-typescript - Next.js + React + TypeScript
• vue-typescript - Vue.js + TypeScript
• nodejs-express - Node.js + Express
• python-django - Python + Django
• python-fastapi - Python + FastAPI
• java-spring - Java + Spring Boot
• csharp-dotnet - C# + .NET
• go - Go projects
• rust - Rust projects
• generic - General software project

Troubleshooting

Common Issues

"OPENAI_API_KEY not found"

# Set your API key
export OPENAI_API_KEY=your-key-here
# Or create .env file with the key

"Not a git repository"

# Make sure you're in a git repository
git init
git add .
git commit -m "Initial commit"

"No modified files found"

# Make sure you have uncommitted changes
git status
# Or stage some changes
git add .

"Claude Code not found"

# Install Claude Code from https://claude.ai/code
# Or run fixes manually from the generated ai-review-fixes.md file

Debug Mode

For detailed logging, run with debug output:

DEBUG=ai-review* ai-review

Validate Setup

Check if everything is configured correctly:

ai-review validate

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Add tests if applicable
5. Run the linter: npm run lint
6. Submit a pull request

Development

# Clone the repository
git clone https://github.com/sorengeier/ai-review-cli.git
cd ai-review-cli

# Install dependencies
npm install

# Link for local development
npm link

# Test locally
ai-review --help

License

MIT © Soren Geier

Support

• 🐛 Report bugs
• 💡 Request features
• 📖 Documentation
• 💬 Discussions

Made with ❤️ using OpenAI GPT-4 and Claude Code