# Install globally from GitHub
npm install -g github:asheshv/llm-reviewer

# Or use without installing:
npx --yes github:asheshv/llm-reviewer --help

# Review uncommitted local changes (uses Copilot by default)
llm-reviewer

# Review changes in a feature branch vs main
llm-reviewer branch main

# Review a pull request
llm-reviewer pr 123

# Review with a local Ollama model
llm-reviewer local --provider ollama --model qwen2.5-coder:14b

# Review with any OpenAI-compatible endpoint
LLM_REVIEWER_API_KEY="sk-..." llm-reviewer local \
  --provider custom --base-url https://openrouter.ai/api/v1 \
  --model google/gemini-2.5-flash

llm-reviewer [mode] [options]

Modes (default: local):
  unstaged              Working tree vs index
  staged                Index vs HEAD
  local                 Working tree vs HEAD (default)
  branch [base]         Current branch vs base (default: main)
  pr <number>           Pull request diff
  commits <n>           Last N commits
  range <ref1>..<ref2>  Arbitrary ref range

Options:
  --model <id>          Model to use (default: auto)
  --format <fmt>        text | markdown | json (default: markdown)
  --stream              Force streaming output
  --no-stream           Force buffered output
  --prompt <text>       Override review prompt
  --config <path>       Override config file path
  --provider <name>     Review provider: copilot, ollama, custom, custom:<name>
  --chunking <mode>     auto | always | never (default: auto)
  --timeout <seconds>   Request timeout (default: 30 for copilot/custom, 120 for ollama)
  --ollama-url <url>    Ollama base URL (default: http://localhost:11434)
  --base-url <url>      Base URL for custom provider (OpenAI-compatible endpoint)
  --verbose             Enable debug logging to stderr
  --help                Show help
  --version             Show version

Subcommands:
  llm-reviewer models          List available models
  llm-reviewer chat "<msg>"    Free-form LLM chat
  llm-reviewer status          Show provider connectivity and configuration

# Review staged changes before committing
llm-reviewer staged

# Review the last 3 commits
llm-reviewer commits 3

# Review a ref range
llm-reviewer range v1.0.0..HEAD

# Use a specific model with JSON output
llm-reviewer branch main --model gpt-4.1 --format json

# Custom review instructions
llm-reviewer --prompt "Focus on security and error handling"

# Review with Ollama (local LLM)
llm-reviewer local --provider ollama --model qwen2.5-coder:14b

# List Ollama models
llm-reviewer models --provider ollama

# Check provider status
llm-reviewer status --provider ollama

# Force chunking for large diffs
llm-reviewer branch main --chunking always

# Longer timeout for large models
llm-reviewer commits 1 --provider ollama --model qwen2.5-coder:32b --timeout 300

llm-reviewer local                          # auto-selects model
llm-reviewer local --model gpt-4.1          # specific model
llm-reviewer models                         # list available models

# Start Ollama (if not running)
ollama serve

# List available models
llm-reviewer models --provider ollama

# Review with a specific model (model is required for Ollama)
llm-reviewer local --provider ollama --model qwen2.5-coder:14b

# Custom Ollama URL
llm-reviewer local --provider ollama --ollama-url http://remote:11434 --model codellama

# Non-streaming for cleaner output
llm-reviewer commits 1 --provider ollama --model qwen2.5-coder:14b --no-stream

# Quick start: API key via env var, endpoint via --base-url
LLM_REVIEWER_API_KEY="sk-or-..." llm-reviewer local \
  --provider custom --base-url https://openrouter.ai/api/v1 \
  --model google/gemini-2.5-flash

# Named provider from config file (see config example below)
llm-reviewer local --provider custom:groq --model llama-3.3-70b-versatile

# List models from a custom endpoint
llm-reviewer models --provider custom --base-url https://api.groq.com/openai/v1

# Dynamic auth with a shell command
# Config: { "providerOptions": { "gcp": { "baseUrl": "https://...", "apiKeyCommand": "gcloud auth print-access-token" } } }
llm-reviewer local --provider custom:gcp --model gemini-2.5-flash

# Bare "custom" picks from providerOptions if --base-url is not set (see Named Configurations)
llm-reviewer local --provider custom --model google/gemini-2.5-flash

# Local endpoint (no auth required)
llm-reviewer local --provider custom --base-url http://localhost:1234/v1 --model local-model

{
  "providerOptions": {
    "groq": {
      "baseUrl": "https://api.groq.com/openai/v1",
      "apiKeyCommand": "op read 'op://Dev/Groq/api-key'"
    },
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKeyCommand": "cat ~/.config/openrouter/key"
    }
  }
}

llm-reviewer local --provider custom:groq --model llama-3.3-70b-versatile
llm-reviewer local --provider custom:openrouter --model anthropic/claude-sonnet-4

llm-reviewer status                         # default provider (copilot)
llm-reviewer status --provider ollama       # check Ollama
llm-reviewer status --provider custom:groq  # check custom endpoint
llm-reviewer status --json                  # machine-readable output

llm-reviewer branch main --chunking always   # force chunking
llm-reviewer branch main --chunking never    # disable chunking

# Kill switch via environment variable
LLM_REVIEWER_CHUNKING=never llm-reviewer local

Reviewing chunk 1/3 (src/auth.ts, src/config.ts)... done (3,200 tokens)
Reviewing chunk 2/3 (src/review.ts, src/prompt.ts)... done (2,800 tokens)
Reviewing chunk 3/3 (src/cli.ts)... done (1,950 tokens)
Aggregating findings... done (4,500 tokens)

{
  "mcpServers": {
    "llm-reviewer": {
      "command": "llm-reviewer",
      "args": ["--mcp"]
    }
  }
}

{
  "llm-reviewer": {
    "type": "stdio",
    "command": "llm-reviewer",
    "args": ["--mcp"]
  }
}

{
  "llm-reviewer": {
    "type": "stdio",
    "command": "node",
    "args": ["/absolute/path/to/llm-reviewer/dist/cli.js", "--mcp"]
  }
}

# Copy the skill into your Claude skills directory
mkdir -p ~/.claude/skills/llm-reviewer
cp skills/SKILL.md ~/.claude/skills/llm-reviewer/SKILL.md

/llm-reviewer

{
  "model": "auto",
  "format": "markdown",
  "stream": true,
  "mode": "extend",
  "prompt": "path/to/custom-prompt.md",
  "defaultBase": "main",
  "ignorePaths": ["*.lock", "dist/**"],
  "provider": "copilot",
  "providerOptions": {
    "ollama": {
      "baseUrl": "http://localhost:11434"
    },
    "groq": {
      "baseUrl": "https://api.groq.com/openai/v1",
      "apiKeyCommand": "op read 'op://Dev/Groq/api-key'"
    },
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKeyCommand": "cat ~/.config/openrouter/key"
    }
  },
  "chunking": "auto",
  "timeout": 30
}

[Default prompt from prompts/default-review.md]

## Additional Instructions (Global)
[Global ~/.llm-reviewer/config.md]

## Project Instructions
[Project .llm-reviewer/config.md]

llm-reviewer --prompt "Only check for SQL injection"

### HIGH SQL Injection in query builder
**File:** `src/db.ts` **Line:** 42
**Category:** Security

User input is concatenated directly into SQL query.

**Suggestion:**
Use parameterized queries instead...

{
  "review": {
    "content": "### HIGH SQL Injection...",
    "model": "gpt-4.1",
    "usage": { "totalTokens": 1234 }
  },
  "diff": {
    "filesChanged": 5,
    "insertions": 120,
    "deletions": 45,
    "files": [
      { "path": "src/db.ts", "status": "modified" }
    ]
  },
  "warnings": [],
  "exitCode": 1
}

"usage": {
  "totalTokens": 12450,
  "chunkedBreakdown": { "mapTokens": 7950, "reduceTokens": 4500, "chunks": 3 }
}

llm-reviewer --stream --format json | while read line; do
  echo "$line" | jq -r '.text // empty'
done

# Fail the build if high-severity issues are found
llm-reviewer branch main || exit 1

# Or capture the exit code
llm-reviewer branch main
if [ $? -eq 1 ]; then
  echo "High-severity issues found. Please review."
  exit 1
fi

gh auth login

# Get a token from https://github.com/settings/tokens
# Scopes required: read:user, copilot
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# Clone the repository
git clone https://github.com/asheshv/llm-reviewer.git
cd llm-reviewer

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Run the CLI locally
node dist/cli.js --help

# Or link globally for testing
npm link
llm-reviewer --help

llm-reviewer/
├── src/
│   ├── cli.ts                     # CLI entry point
│   ├── mcp-server.ts              # MCP server entry point
│   └── lib/
│       ├── providers/             # Provider abstraction layer
│       │   ├── types.ts           # ReviewProvider interface
│       │   ├── openai-chat-provider.ts  # Shared OpenAI-compatible base
│       │   ├── copilot-provider.ts      # GitHub Copilot provider
│       │   ├── ollama-provider.ts       # Ollama local provider
│       │   ├── custom-provider.ts       # OpenAI-compatible custom provider
│       │   └── index.ts           # Provider factory
│       ├── auth.ts                # Token resolution + session exchange
│       ├── chunking.ts            # Diff splitting + bin-packing
│       ├── config.ts              # Multi-layer config loading
│       ├── diff.ts                # Git diff collection (7 modes)
│       ├── formatter.ts           # Output formatting (text/markdown/json)
│       ├── prompt.ts              # Prompt assembly + file manifests
│       ├── review.ts              # Review orchestration + map-reduce chunking
│       ├── streaming.ts           # SSE parser
│       ├── truncation.ts          # Severity-aware truncation for reduce pass
│       ├── types.ts               # Shared type definitions
│       └── index.ts               # Public API exports
├── test/                          # Tests (vitest + msw)
├── prompts/
│   └── default-review.md          # Built-in review prompt
├── skills/
│   └── SKILL.md                   # Claude Code skill definition
├── docs/
│   ├── spec/                      # Design specifications
│   ├── adr/                       # Architecture decision records
│   ├── plans/                     # Implementation plans
│   └── reference/                 # API documentation
└── .llm-reviewer/                 # Project-level config (dogfooding)
    ├── config.json
    └── config.md