commit-sage

AI-powered code reviewer for your staged Git changes. Runs as a CLI or pre-commit hook — catches bugs, security issues, and performance problems before they get committed.

Unlike platform-based reviewers (CodeRabbit, Copilot), commit-sage reviews before the commit — the earliest possible point in your workflow. No GitHub App, no PR required. Just stage your files and run it.

Quick Start

# Install and run — works immediately, no API key needed
npm install -g commit-sage
git add .
commit-sage

That's it. Out of the box, commit-sage uses a free Cloudflare-hosted backend — zero configuration required.

Want to use your own API key for a different provider? Just set it:

export GEMINI_API_KEY=your-key-here
commit-sage   # auto-detects Gemini

Or run the interactive setup wizard:

commit-sage init

You'll see something like:

🤖 AI review (cloudflare worker)

✔ Review complete.

src/auth.ts:45 — [Security] JWT secret is hardcoded. Fix: move to environment variable.
src/users.ts:23 — [Bug] Missing null check on req.params.id. Fix: validate before DB query.

If everything looks good, it just says LGTM.

Providers

commit-sage supports multiple providers. The free Cloudflare backend is the default — no key needed.

| Provider | API Key | Priority | |----------|---------|:--------:| | Cloudflare | none needed | default | | Gemini | GEMINI_API_KEY | 1st auto-detect | | OpenAI | OPENAI_API_KEY | 2nd auto-detect | | Anthropic | ANTHROPIC_API_KEY | 3rd auto-detect | | Moonshot (Kimi) | MOONSHOT_API_KEY | 4th auto-detect |

Resolution order: .commitsagerc config → env var auto-detect → Cloudflare default.

To override on the fly:

commit-sage --provider gemini --key AIza...

Or create a .commitsagerc for permanent config:

{ "ai": { "provider": "openai" } }

Setup Wizard

The init command walks you through everything:

commit-sage init

It will:

• Let you pick a provider
• Help you configure your API key
• Write .commitsagerc for you
• Optionally install a pre-commit hook

Use as Git Hook

Block bad commits automatically:

# With Husky
npm install husky --save-dev
npx husky init
echo 'npx commit-sage --hook' > .husky/pre-commit

# Or manually
echo '#!/bin/sh
npx commit-sage --hook' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

When --hook is used and the AI finds real bugs, the commit is blocked (exit code 1).

CLI Flags

commit-sage [command] [options]

Commands:
  init                  Interactive setup wizard

Options:
  -h, --help            Show help
  --hook                Git hook mode (exit 1 on issues)
  --provider <name>     Override provider for this run
  --key <api-key>       Pass API key directly (one-time, not stored)

Supported Languages

Works with any language. Gives extra-specific hints for:

TypeScript / JavaScript / Python / Go / Rust / Java / C# / Ruby / PHP / Swift / Kotlin

The language is auto-detected from file extensions.

Advanced Config

All fields are optional:

{
  "ai": {
    "provider": "gemini",
    "model": "gemini-2.0-flash",
    "fullContext": true,
    "diffContext": 10,
    "strictness": "block"
  }
}

| Field | Default | What it does | |-------|---------|-------------| | provider | cloudflare | AI provider to use | | model | auto | Override the AI model | | fullContext | true | Send full file contents for better reviews | | diffContext | 10 | Lines of context around each change | | strictness | "block" | "block" = block commits on issues, "warn" = always allow |

Self-Hosted Cloudflare Worker

If you prefer to run your own backend instead of using the default free one:

cd worker/
npm install -g wrangler
wrangler login
wrangler deploy

Then point your config to it:

{
  "ai": {
    "provider": "cloudflare",
    "proxyUrl": "https://your-worker.your-subdomain.workers.dev"
  }
}

The worker includes IP-based rate limiting (20 requests/hour per IP).

How It Works

1. Reads your staged files and their full contents
2. Detects the dominant language and builds a tailored prompt
3. Sends the diff + full file context to the AI
4. Prints real bugs only — no style nitpicks, no false positives

License

MIT