Kode Review CLI

AI-powered code review CLI using OpenCode SDK. Multiple models supported.

Features

First Pass Code Reviews using AI: Uses OpenCode SDK to run comprehensive code reviews
Diff, semantic or entire code base review modes: Optimize for cost or correctness using simpler diff mode, or go all in using agent mode
Antigravity Integration: Free access to Claude and Gemini models via Google OAuth
Multi-Platform VCS: Supports GitHub PRs and GitLab MRs
Interactive & Agent Modes: Works interactively or in CI/automation pipelines
Watch Mode: Continuous monitoring for PRs/MRs where you're a reviewer
Semantic Code Indexer: Optional Docker-based code indexing for contextual reviews

Requirements

Node.js 18+
Bun (recommended) or npm
Git

OpenCode CLI - Install with:

curl -fsSL https://opencode.ai/install | bash
# or
bun install -g opencode-ai

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

Installation

# Clone the repository
git clone https://github.com/kofikode/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 --json   # JSON error 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
`--provider <id>`	Override provider (e.g., `anthropic`, `google`)
`--model <id>`	Override model
`--variant <name>`	Override variant (e.g., `max`, `low`)
`--attach <url>`	Connect to running OpenCode server
`--agentic`	Enable agent mode with dynamic codebase exploration
`--max-iterations <n>`	Max tool call iterations for agent mode (default: 10)
`--agentic-timeout <s>`	Timeout in seconds for agent mode (default: 120)

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.

# Basic agent mode (read_file tool only)
kode-review --agentic

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

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

Available Tools in Agent Mode

Tool	Description	Requires Indexer
`read_file`	Read file content from the repository	No
`search_code`	Hybrid semantic + keyword search	Yes
`find_definitions`	Find where symbols are defined	Yes
`find_usages`	Find all usages of a symbol	Yes
`get_call_graph`	Get function call relationships	Yes
`get_impact`	Analyze file dependencies	Yes

Agent Mode Options

Flag	Description
`--agentic`	Enable agent mode
`--max-iterations <n>`	Max tool call iterations (default: 10)
`--agentic-timeout <s>`	Timeout in seconds (default: 120, max: 600)

Review Mode Comparison

Choose the review mode that fits your needs:

Mode	Command	Description
Diff	`kode-review`	Reviews the diff only
Diff + Index	`kode-review --with-context`	Reviews diff with pre-retrieved semantic context
Agent	`kode-review --agentic`	AI dynamically explores codebase
Agent + Index	`kode-review --agentic --with-context`	Full agent capabilities with all tools

Pros and Cons

Diff Review (Default)

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.

Diff + Indexed Codebase

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.

Agent Mode

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.

Agent Mode + Index

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
kode-review --setup-provider  # Provider/model only
kode-review --setup-vcs       # GitHub/GitLab only
kode-review --reset           # Reset all configuration
kode-review --update          # Check for and install latest version

Provider Configuration

Antigravity (Recommended) - Free access to premium models via Google OAuth:

Claude Sonnet 4.5 / Opus 4.5 (thinking variants: low, max)
Gemini 3 Pro (thinking variants: low, high)
Gemini 3 Flash (thinking variants: minimal, low, medium, high)

Standard Providers - Anthropic, Google, OpenAI, or OpenCode Zen (requires direct authentication)

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)
`--index-watch`	Continuous indexing (watch mode)
`--background-indexer`	Background daemon for large repos
`--index-queue`	Show pending background jobs
`--index-queue-clear`	Clear pending background jobs

How It Works

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:

Extracts function names, class names, and imports from the diff
Searches the index for semantically similar code
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

Configuration Reference

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

Upgrading the Indexer

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

Troubleshooting

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:

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

Schema errors ("column does not exist"):

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

Port conflicts:

Find process: fuser 8321/tcp (Linux) or lsof -i :8321 (macOS)

Change ports in config:

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

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
}

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
kode-review --scope pr --pr 123 --agentic --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
`OPENCODE_SERVER_URL`	Attach to running OpenCode server
`OPENCODE_MODEL`	Default model override

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:

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

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
.claude		.claude
bin		bin
docs		docs
src		src
tasks		tasks
.gitignore		.gitignore
.release-it.json		.release-it.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
eslint.config.js		eslint.config.js
package.json		package.json
roadmap.md		roadmap.md
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Kode Review CLI

Features

Requirements

Installation

Updating

Quick Start

Usage

Interactive Mode (Default)

Agent/CI Mode

Review Options

Watch Mode

Agent Mode

Available Tools in Agent Mode

Agent Mode Options

Review Mode Comparison

Pros and Cons

Quick Reference

Configuration

First-Time Setup

Provider Configuration

VCS Integration

Semantic Code Indexer

Quick Start

Indexer Options

Review Output

Git Hooks Integration

Quick Setup

Manual Hook Example

Output Formats

Post to PR/MR

Examples

From a Coding Agent

Environment Variables

Releasing

Commit Convention

Cutting a Release

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages