npm package: @sgeier/ai-review
Description: AI-powered code review tool with OpenAI GPT-4 and Claude Code integration
Author: sgeier
Latest version: 0.0.2

# 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)

```bash
npm install -g @sgeier/ai-review
```

### Use with npx (No Installation)

```bash
npx @sgeier/ai-review
```

## Prerequisites

1. **OpenAI API Key** - Get one from [OpenAI Platform](https://platform.openai.com/api-keys)
2. **Claude Code** (optional but recommended) - Install from [claude.ai/code](https://claude.ai/code)
3. **Git Repository** - Works with any git repository

## Quick Start

1. **Set your OpenAI API key globally:**
   ```bash
   # 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):**
   ```bash
   ai-review init
   ```

3. **Make some code changes and run:**
   ```bash
   ai-review
   ```

## Usage

### Basic Usage

```bash
# 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:

```json
{
  "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

```bash
# 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

```bash
# 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

```bash
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

```yaml
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

```bash
# .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"**
```bash
# Set your API key
export OPENAI_API_KEY=your-key-here
# Or create .env file with the key
```

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

**"No modified files found"**
```bash
# Make sure you have uncommitted changes
git status
# Or stage some changes
git add .
```

**"Claude Code not found"**
```bash
# 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:

```bash
DEBUG=ai-review* ai-review
```

### Validate Setup

Check if everything is configured correctly:

```bash
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

```bash
# 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](https://github.com/sorengeier)

## Support

- 🐛 [Report bugs](https://github.com/sgeier/ai-review-cli/issues)
- 💡 [Request features](https://github.com/sgeier/ai-review-cli/issues)
- 📖 [Documentation](https://github.com/sgeier/ai-review-cli#readme)
- 💬 [Discussions](https://github.com/sgeier/ai-review-cli/discussions)

---

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