Kode Review CLI

AI-powered code review CLI built on pi. Pi handles provider/model auth — kode-review handles the review.

⚠️ Upgrading from 0.x?

v1.0 is a clean break. The first run on a 0.x install will offer to wipe everything (config, watch state, indexer Docker containers AND volumes) before re-onboarding. There is no backup.

If you don't want this, stay on 0.4.0:

npm install -g @ebernie/[email protected]

The migration prompts for a typed wipe confirmation. To script the upgrade, pass --migrate-yes or set KODE_REVIEW_MIGRATE_YES=1.

Features

• First-pass AI code reviews powered by pi
• Diff, semantic, or agentic review modes: pick a tier based on cost vs. depth
• Multi-reviewer personas: run security, architect, doc-reviewer, test-auditor, general, or custom personas — sequentially or in parallel
• Multi-platform VCS: GitHub PRs and GitLab MRs
• Interactive & CI modes: human-friendly output or quiet/JSON for automation
• Watch mode: continuous monitoring of PRs/MRs assigned to you
• Semantic code indexer: optional Docker-based context retrieval

Requirements

• Node.js 18+
• Bun (recommended) or npm
• Git
• pi (https://pi.dev) — install and configure before kode-review:

  npm install -g @mariozechner/pi-coding-agent
  pi   # then use /login to set up a provider (Anthropic, Google, OpenAI, etc.)

• Optional: GitHub CLI (gh) and/or GitLab CLI (glab)
• Optional: Docker (required for the semantic code indexer)

Installation

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

# Install dependencies and build
bun install
bun run build

# Link globally for CLI access
bun link

Updating

# Check for updates and install the latest version
kode-review --update

This checks for newer versions via git tags, shows what's changed, and (after confirmation) runs git pull, bun install, and bun run build in the installation directory. Only works for git-clone installations.

A daily background check also runs automatically and notifies you when a new version is available.

Quick Start

# First run triggers onboarding wizard
kode-review

# Review local changes
kode-review --scope local

# Review a specific PR/MR
kode-review --scope pr --pr 123

# Review with semantic context (requires indexer setup)
kode-review --with-context

Usage

Interactive Mode (Default)

When run in a terminal, kode-review provides an interactive experience with colored output and progress indicators. First run triggers the onboarding wizard.

Agent/CI Mode

For automation, use non-interactive flags:

kode-review --scope local --quiet              # Minimal output
kode-review --scope pr --pr 123 --format json  # JSON output

Review Options

| Flag | Description | |------|-------------| | -s, --scope <scope> | Review scope: local, pr, both, auto (default: auto) | | -p, --pr <number> | Specific PR/MR number to review | | -q, --quiet | Minimal output (agent-friendly) | | -f, --format <format> | Output format: text, json, markdown (default: text) | | -o, --output-file <path> | Write output to file instead of stdout | | --post-to-pr | Post review as PR/MR comment with inline annotations | | --model <pattern> | Override the pi model for this review (e.g., anthropic/claude-sonnet-4-6). When omitted, pi's default applies. | | --migrate-yes | Skip the typed wipe confirmation during the v1.0 clean-break migration | | -a, --agentic | Agent mode with dynamic codebase exploration (default: on) | | --no-agentic | Diff-only review — disable tool access (faster, cheaper) | | --max-iterations <n> | Max tool call iterations for agent mode (default: 10) | | --agentic-timeout <s> | Timeout in seconds for agent mode (default: 600, max: 600) |

Watch Mode

Monitor for PRs/MRs where you are assigned as a reviewer.

kode-review --watch                      # Default 5-minute polling
kode-review --watch --watch-interval 60  # 1-minute polling
kode-review --watch --watch-interactive  # Prompt to select PR/MR
kode-review --watch --quiet              # Background monitoring

Features:

• Polls both GitHub and GitLab simultaneously (if both CLIs are authenticated)
• Persists reviewed state to avoid duplicates across restarts
• Graceful shutdown on Ctrl+C

| Flag | Description | |------|-------------| | -w, --watch | Enable watch mode | | --watch-interval <sec> | Polling interval in seconds (default: 300) | | --watch-interactive | Prompt to select PR/MR instead of auto-reviewing |

State file: ~/.config/kode-review-watch/config.json

Agent Mode

Agent mode enables dynamic codebase exploration during reviews. Instead of only seeing the diff, the AI can actively read files, search for patterns, and analyze code relationships. Agent mode is the default — pass --no-agentic for a diff-only review.

# Default — agent mode against auto-detected scope (local changes or current PR)
kode-review

# Agent mode with full tool suite (requires indexer)
kode-review --with-context

# With custom limits
kode-review --max-iterations 15 --agentic-timeout 600

# Diff-only review (no tools, fastest, cheapest)
kode-review --no-agentic

Available Tools in Agent Mode

Agent mode now works with or without the indexer. When the indexer is reachable, indexer-backed search tools are used; when it isn't, drop-in ripgrep + git fallbacks take over transparently. get_call_graph and get_impact degrade gracefully when running without the indexer (call graph reports available: false, impact reports isPartial: true — direct importers only).

| Tool | Description | Without indexer | |------|-------------|-----------------| | read_file | Read file content from the repository | ✓ always available | | search_code | Hybrid semantic + keyword search | ripgrep fallback | | find_definitions | Find where symbols are defined | ripgrep fallback | | find_usages | Find all usages of a symbol | ripgrep fallback | | get_call_graph | Get function call relationships | degraded stub | | get_impact | Analyze file dependencies (direct importers) | ripgrep fallback (isPartial) | | get_commits | List commits in a ref range (default merge-base..HEAD) | ✓ always available | | get_file_history | Recent commits that touched a specific file | ✓ always available |

ripgrep is required for the filesystem fallbacks. It's preinstalled on most CI runners; on a dev laptop install via Homebrew (brew install ripgrep), apt (sudo apt-get install ripgrep), or the official instructions.

Agent Mode Options

| Flag | Description | |------|-------------| | -a, --agentic | Agent mode (default: on) — flag kept for explicit intent / backward compat | | --no-agentic | Diff-only review — disable agent tool access | | --max-iterations <n> | Max tool call iterations (default: 10) | | --agentic-timeout <s> | Timeout in seconds (default: 600, max: 600) |

Reviewer Personas

Reviewer personas swap the system prompt the model runs under. Pick one or several, and each runs in its own pi session — in parallel — with its own focus. Default: a single general reviewer.

Built-in personas

| Persona | Focus | |---------|-------| | general | Thorough general-purpose review (security, bugs, quality, conventions). Default if no --reviewer is passed. | | security | Application security: vulnerabilities, authn/authz, secrets, dependencies. | | architect | Architecture compliance, design quality, simplicity (YAGNI). | | doc-reviewer | Public API documentation: presence, accuracy, completeness. | | test-auditor | Test quality and coverage; flags anti-gaming patterns. |

kode-review --list-reviewers              # discover what's available
kode-review --reviewer security           # one persona
kode-review --reviewer security,architect # comma-separated
kode-review --reviewer security --reviewer architect   # repeatable flag (same effect)
kode-review --reviewer all                # every available persona, in parallel

--reviewer composes with every other flag: -a (agent mode), -c (CI), -p <pr>, etc. Each persona reviews the same diff/PR but produces its own output.

Multi-reviewer in CI mode

When --ci is active and multiple reviewers run, the sticky PR comment is posted once as a composite body — one ## <reviewer-name> section per reviewer, with a single trailing usage footer summing tokens and cost across all of them. The CI exit code is the worst (most severe) across reviewers, so a single failing persona still fails the run.

Defining your own persona

A persona is just a markdown file containing the system prompt. Drop one in:

~/.config/kode-review/reviewers/<name>.md

(or set KODE_REVIEW_REVIEWERS_DIR to override the location). A user file with the same name as a built-in overrides the built-in — the --list-reviewers output marks it as [user] or (user override) so you always know which prompt the model is running.

Persona names must match ^[a-z0-9][a-z0-9_-]{0,63}$ (lowercase letters, digits, underscore, hyphen; starts with alphanumeric; ≤64 chars).

Reviewer Options

| Flag | Description | |------|-------------| | --reviewer <name> | Reviewer persona(s) to run. Repeatable; comma-separated; all runs every reviewer. Default: general. | | --list-reviewers | List available reviewers (built-in + user-defined) and exit. |

Review Mode Comparison

Choose the review mode that fits your needs:

| Mode | Command | Description | |------|---------|-------------| | Agent (default) | kode-review | AI dynamically explores codebase via ripgrep + git tools | | Agent + Index | kode-review --with-context | Full agent capabilities, augmented with semantic index lookups | | Diff | kode-review --no-agentic | Diff-only review, no tool calls — fastest | | Diff + Index | kode-review --no-agentic --with-context | Diff plus pre-retrieved semantic context |

Pros and Cons

Pros:

• Fastest execution time
• No additional setup required
• Predictable behavior and cost
• Lowest token usage

Cons:

• Limited context - only sees the diff
• May miss issues requiring broader codebase understanding
• Cannot verify naming conventions or patterns
• No impact analysis

Best for: Quick reviews, simple changes, CI pipelines where speed matters.

Pros:

• Pre-retrieved context reduces AI decision overhead
• Consistent, reproducible context selection
• Better understanding of related code patterns
• Moderate execution time

Cons:

• Requires Docker and indexer setup
• Context is statically selected before review
• May include irrelevant context or miss important context
• Initial indexing takes time for large repos

Best for: Standard reviews where you want better context without longer review times.

Pros:

• AI decides what to explore based on the changes
• Can read specific files for full context
• More thorough analysis for complex changes
• Provides evidence from exploration in findings

Cons:

• Only read_file tool without indexer
• Slower than diff-only mode
• Less predictable execution time and cost
• May not explore optimally without search tools

Best for: Complex changes where file reading is sufficient, no indexer setup desired.

Pros:

• Full tool suite: read, search, definitions, usages, call graph
• Deepest understanding of code impact
• Can verify patterns, find all callers, assess blast radius
• Most thorough reviews possible

Cons:

• Requires Docker and indexer setup
• Slowest execution time
• Highest cost (more tokens used)
• May over-explore for simple changes

Best for: Critical code reviews, security-sensitive changes, unfamiliar codebases, architectural changes.

Quick Reference

| Aspect | Diff | Diff + Index | Agent | Agent + Index | |--------|------|--------------|-------|---------------| | Setup Required | None | Docker + Index | None | Docker + Index | | Speed | Fast | Medium | Medium | Slow | | Context Depth | Shallow | Medium | Medium | Deep | | Cost (Tokens) | Low | Medium | Medium | High | | Impact Analysis | No | Limited | No | Yes | | Pattern Verification | No | Yes | No | Yes | | File Reading | No | No | Yes | Yes | | Search Capability | No | Pre-selected | No | Yes |

Configuration

Configuration is stored in ~/.config/kode-review/config.json.

First-Time Setup

The first run triggers an interactive onboarding wizard, or run manually:

kode-review --setup           # Full wizard (verifies pi + configures GitHub/GitLab)
kode-review --setup-vcs       # GitHub/GitLab only
kode-review --reset           # Reset kode-review's local config
kode-review --update          # Check for and install latest version

Provider Configuration

Pi owns model providers. Set one up with:

pi              # opens interactive UI
# Inside pi, run: /login
# Pick Anthropic, Google (Gemini API key), OpenAI Codex, GitHub Copilot, etc.

pi --list-models shows what is currently usable. Kode-review picks the first available model unless you override with --model <provider>/<id> per invocation.

VCS Integration

GitHub CLI (gh) and GitLab CLI (glab) are detected automatically. This enables reviewing PRs/MRs directly and auto-detecting the platform from git remote.

Semantic Code Indexer

The semantic code indexer is optional. It provides contextual information during reviews by finding related code from your codebase.

Requirements: Docker Desktop (macOS/Windows) or Docker Engine (Linux)

Quick Start

# 1. Set up the indexer (one-time)
kode-review --setup-indexer

# 2. Index your repository
cd /path/to/your/repo
kode-review --index

# 3. Review with context
kode-review --with-context
kode-review --scope pr --pr 123 --with-context

Indexer Options

| Flag | Description | |------|-------------| | --setup-indexer | Interactive setup wizard | | --index | Index/update current repository | | --index-status | Show indexer status | | --index-reset | Drop and rebuild index for current repo | | --index-list-repos | List all indexed repositories | | --indexer-cleanup | Remove containers, volumes, and all data | | --with-context | Include semantic context in review | | --context-top-k <n> | Number of code chunks to include (default: 5) | | --index-branch <branch> | Branch to index (default: current) | | --background-indexer | Background daemon for large repos | | --index-queue | Show pending background jobs | | --index-queue-clear | Clear pending background jobs |

The indexer runs as two Docker containers:

• PostgreSQL with pgvector - Stores code embeddings for semantic search
• FastAPI server - Handles indexing and search requests

When --with-context is enabled:

1. Extracts function names, class names, and imports from the diff
2. Searches the index for semantically similar code
3. Includes the most relevant chunks in the review prompt

The indexer scans: TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, C#

Excludes: node_modules, dist, build, .git, vendor, target

Settings in ~/.config/kode-review/config.json:

| Setting | Default | Description | |---------|---------|-------------| | indexer.enabled | false | Whether indexer is enabled | | indexer.apiPort | 8321 | API server port | | indexer.dbPort | 5436 | PostgreSQL port | | indexer.embeddingModel | sentence-transformers/all-MiniLM-L6-v2 | Embedding model | | indexer.chunkSize | 1000 | Characters per chunk | | indexer.topK | 5 | Default search results | | indexer.maxContextTokens | 4000 | Max tokens for context |

After pulling new versions of kode-review:

Quick Upgrade (preserves data):

kode-review --setup-indexer

Full Reset (when you see schema errors or 500s):

kode-review --indexer-cleanup
kode-review --setup-indexer
kode-review --index

Force fresh Docker build:

docker compose -p kode-review-indexer down
docker compose -p kode-review-indexer build --no-cache
docker compose -p kode-review-indexer up -d

Verify upgrade:

kode-review --index-status
kode-review --index-list-repos

Indexer won't start:

• Ensure Docker is running: docker info
• Check ports 8321/5436 are available
• View logs: docker compose -p kode-review-indexer logs

Context not appearing in reviews:

• Verify indexer is running: kode-review --index-status
• Ensure repository is indexed: kode-review --index

API shows "Unhealthy" or 500 errors:

1. Check logs: docker compose -p kode-review-indexer logs kode-review-api
2. If schema errors, perform full reset (see Upgrading above)
3. Check memory: docker stats

Schema errors ("column does not exist"):

kode-review --indexer-cleanup
kode-review --setup-indexer
kode-review --index

Port conflicts:

1. Find process: fuser 8321/tcp (Linux) or lsof -i :8321 (macOS)
2. Change ports in config:

   { "indexer": { "apiPort": 8322, "dbPort": 5437 } }

3. Re-run: kode-review --setup-indexer

Stop indexer containers:

docker compose -p kode-review-indexer down

Review Output

Reviews include:

• Summary: Overview of changes and quality
• Issues Found: Categorized by severity (CRITICAL, HIGH, MEDIUM, LOW)
  • Security issues, bugs, code quality problems, convention violations
• Positive Observations: Things done well
• Final Verdict: APPROVE, REQUEST_CHANGES, or NEEDS_DISCUSSION with merge recommendation

Git Hooks Integration

Automatically run code reviews before commits or pushes.

Quick Setup

# Generate a pre-commit hook (interactive — prompts for hook type)
kode-review --init-hooks

The --init-hooks command:

• Prompts to select hook type (pre-commit or pre-push)
• Detects Husky and generates compatible hooks
• Creates executable hook scripts in .git/hooks/ or .husky/
• Warns before overwriting existing hooks

Manual Hook Example

#!/bin/bash
# .git/hooks/pre-push

kode-review --scope local --quiet || {
  echo "Code review found issues. Push anyway? (y/N)"
  read response
  [[ "$response" =~ ^[Yy]$ ]] || exit 1
}

CI Usage

Run kode-review against every pull/merge request in CI. The --ci flag bundles agentic mode + quiet output + markdown formatting + sticky PR comment posting + severity-gated exit codes.

kode-review --ci --pr 42 --fail-on critical

The indexer is not required in CI mode — the agentic tools fall back to ripgrep + git transparently.

Ready-to-copy workflow files for GitHub Actions and GitLab CI live in docs/ci-examples/, including notes on:

• Checking out the right ref (PR head, not the merge ref).
• Required permissions (pull-requests: write on GitHub; an api-scoped token on GitLab).
• Sticky-comment behavior — each run posts one comment and deletes prior kode-review comments, leaving human comments untouched.
• Severity gating via --fail-on critical|high|none.
• Suppressing specific findings inline with // kode-review: ignore.

Output Formats

Control how review results are displayed and saved.

# Default text output
kode-review --scope local

# JSON output (for automation/parsing)
kode-review --scope local --format json

# Markdown output (for documentation)
kode-review --scope local --format markdown

# Save to file
kode-review --scope local --format json -o review.json
kode-review --scope local --format markdown -o review.md

Post to PR/MR

Automatically post reviews as comments on GitHub PRs or GitLab MRs:

# Post review as PR comment with inline code annotations
kode-review --scope pr --pr 123 --post-to-pr

# Combined with other options (agent mode is the default)
kode-review --scope pr --pr 123 --post-to-pr

Features:

• Posts main review comment with summary and verdict
• Adds inline comments on specific lines for issues with file locations
• Sets PR approval status based on verdict (APPROVE/REQUEST_CHANGES)
• Works with both GitHub (gh) and GitLab (glab) CLIs

Examples

From a Coding Agent

# JSON output for parsing
kode-review --scope local --quiet --format json

# Save structured output to file
kode-review --scope local --format json -o /tmp/review.json

# Post directly to PR
kode-review --scope pr --pr 123 --post-to-pr --quiet

Environment Variables

| Variable | Description | |----------|-------------| | KODE_REVIEW_MIGRATE_YES | Skip the typed wipe confirmation during the v1.0 clean-break migration | | DEBUG | Set to 1 for verbose logging |

Pi-specific variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, MINIMAX_API_KEY, etc.) are honored by pi directly. For the full provider → env-var mapping, see node_modules/@mariozechner/pi-coding-agent/docs/providers.md (installed alongside pi) or run pi --list-models to see which providers your current setup can reach. Pi homepage: https://pi.dev.

Releasing

Releases are automated with release-it and conventional-changelog. Version bumps, changelog generation, git tags, and pushing are handled in a single command.

Commit Convention

This project follows Conventional Commits. The commit prefix determines the version bump:

| Prefix | Version Bump | Example | |--------|-------------|---------| | feat: | Minor (0.x.0) | feat: add dark mode support | | fix: | Patch (0.0.x) | fix: correct timeout handling | | BREAKING CHANGE in footer | Major (x.0.0) | Body contains BREAKING CHANGE: removed --json flag | | chore:, refactor:, docs:, etc. | No bump | Not included in changelog |

Cutting a Release

# Preview what will happen (no changes made)
bun run release:dry

# Run the release (bumps version, updates CHANGELOG.md, commits, tags, pushes)
bun run release

The release command will:

1. Determine the next version from commits since the last tag
2. Update version in package.json
3. Prepend new entries to CHANGELOG.md
4. Create a git commit (chore: release vX.Y.Z) and tag (vX.Y.Z)
5. Push the commit and tag to the remote

License

MIT