codereview-ai

Zero-config AI code review for every commit — using the CLI tools you already have.

codereview-ai adds a git pre-commit (or pre-push) hook that reviews your staged diff with Claude Code or OpenAI Codex CLI. No API keys. No cloud accounts. No configuration required.

Quick Start

# 1. Install the hook in your project
npx codereview-ai init

# 2. Stage your changes as usual
git add .

# 3. Commit — the review runs automatically
git commit -m "feat: add new feature"

That's it. Your next commit will be reviewed by your local AI CLI before it lands.

Features

• Zero API keys — uses your locally installed claude or codex binary
• Zero config — works out of the box with sensible defaults
• Dual CLI support — auto-detects Claude Code CLI and OpenAI Codex CLI; prefers Claude when both are installed
• Structured review output — colored terminal output with severity levels (error / warning / info)
• Configurable exit codes — block commits on issues or run in advisory mode
• Ignore paths — skip node_modules/, dist/, and any other paths you configure
• Custom prompts — append project-specific conventions to the base review prompt
• CI-friendly — no color output when stdout is not a TTY

Prerequisites

At least one of:

• Claude Code CLI — run claude --version to verify
• OpenAI Codex CLI — run codex --version to verify

Node.js >= 18 is required.

How It Works

git commit
     │
     ▼
pre-commit hook
     │
     ▼
codereview-ai review
     │
     ├─ git diff --cached        (extract staged changes)
     ├─ filter ignorePaths        (remove noise)
     ├─ detect claude / codex     (find available CLI)
     └─ pipe diff to CLI ─────► AI review
                                   │
                          structured JSON response
                                   │
                     ┌─────────────┴──────────────┐
                     │                            │
                  PASS (exit 0)             FAIL (exit 1)
               commit proceeds            commit blocked

The diff is piped to your local AI CLI with a structured prompt that asks for:

• Bug detection
• Security vulnerabilities
• Performance issues
• Code smells
• Error handling gaps

The AI responds with a JSON list of issues. codereview-ai renders them in your terminal, then exits 0 (pass) or 1 (fail) based on your configuration.

Configuration

Create an optional .ai-reviewerrc.json in your project root to override defaults:

{
  "preferredCLI": "claude",
  "timeout": 90,
  "failOnIssues": true,
  "severityThreshold": "warning",
  "ignorePaths": ["node_modules", "dist", ".git", "coverage"],
  "customPrompt": "Follow our team's TypeScript style guide at docs/style.md"
}

Config Reference

| Field | Type | Default | Description | |---|---|---|---| | hook | "pre-commit" | "pre-push" | "pre-commit" | Git hook that triggers the review | | preferredCLI | "claude" | "codex" | "auto" | "auto" | Which AI CLI to prefer | | timeout | number | 60 | Seconds to wait for the CLI before aborting | | failOnIssues | boolean | true | Exit 1 (block commit) when issues are found | | severityThreshold | "error" | "warning" | "info" | "warning" | Minimum severity that counts as a failure | | ignorePaths | string[] | ["node_modules","dist",".git"] | Path prefixes/substrings to exclude from the diff | | customPrompt | string | — | Extra instructions appended to the base review prompt |

CLI Usage

codereview-ai [command] [options]

Commands:
  review   Run AI code review on staged changes
  init     Set up husky git hooks in the current project

Options:
  --version, -v   Print version
  --help, -h      Show help

Review options:
  --hook <type>   Override hook type for this run (pre-commit | pre-push)

Init options:
  --hook <type>   Which git hook to install (default: pre-commit)
  --rc            Create a sample .ai-reviewerrc.json

vs Manual Review

| | codereview-ai | Manual PR review | |---|---|---| | When | Every commit, locally | After push, on GitHub | | Latency | Seconds | Hours to days | | API keys | None required | None (uses local CLI) | | Blocks bad commits | Yes (exit 1) | No | | Works offline | Yes (if CLI works offline) | No | | Customizable | Yes, via .ai-reviewerrc.json | Via review guidelines | | CI integration | Optional (run in CI too) | Standard |

Development

See CONTRIBUTING.md for setup instructions, testing, and the PR process.

License

MIT — Copyright (c) 2026 Hassaan Saleem