Claude Reviewer

A local PR review system for Claude Code. Create pull requests, review diffs with inline comments, and merge changes—all without leaving your terminal.

Why Claude Reviewer?

When working with AI coding assistants like Claude, you often want to review changes before merging them. Claude Reviewer provides:

• GitHub-like code review - View diffs, add inline comments, approve or request changes
• CLI-first workflow - Perfect for AI agents that work in the terminal
• Local & private - All data stays on your machine
• No external dependencies - Just SQLite for storage

Installation

pip install claude-reviewer

Quick Start

1. Create a PR

# On your feature branch with changes
claude-reviewer create --title "Add new feature"

# Output:
# PR #a1b2c3d4 created successfully
# Review URL: http://localhost:3456/prs/a1b2c3d4

2. Start the Web UI

# Start the review interface
claude-reviewer serve

3. Review & Merge

# Check status
claude-reviewer status a1b2c3d4
# Output: changes_requested

# See comments
claude-reviewer comments a1b2c3d4
# Output: [src/app.py:42] Please add error handling here

# After addressing feedback, update the PR
claude-reviewer update a1b2c3d4

# Once approved, merge
claude-reviewer merge a1b2c3d4 --push

Commands

Command	Description
create	Create a new PR from current branch
list	List all PRs
status	Check PR status
comments	Get inline comments with file:line references
show	Show detailed PR information
update	Update PR diff after making changes
merge	Merge an approved PR
serve	Start the web UI
stop	Stop the web UI

CLI Reference

Create a PR

claude-reviewer create \
  --title "Feature: Add user authentication" \
  --description "Implements OAuth2 login flow" \
  --base main \
  --head feature/auth

List PRs

# All PRs
claude-reviewer list

# Filter by status
claude-reviewer list --status pending
claude-reviewer list --status approved
claude-reviewer list --status changes_requested

Get Comments

# Human-readable format
claude-reviewer comments a1b2c3d4

# JSON format (for automation)
claude-reviewer comments a1b2c3d4 -f json

# Only unresolved comments
claude-reviewer comments a1b2c3d4 --unresolved

Merge

# Merge locally
claude-reviewer merge a1b2c3d4

# Merge and push to remote
claude-reviewer merge a1b2c3d4 --push

# Merge and delete source branch
claude-reviewer merge a1b2c3d4 --delete-branch

Web UI

The web interface provides:

• Diff viewer - Side-by-side or unified view
• Inline comments - Click any line to add a comment
• File tree - Navigate between changed files
• Review actions - Approve or request changes

Start it with:

claude-reviewer serve

This automatically pulls the Docker image from Docker Hub and starts the web UI. Open http://localhost:3456 to view your PRs.

Serve Options

# Use a different port
claude-reviewer serve --port 8080

# Skip pulling latest image (use cached)
claude-reviewer serve --no-pull

# Development mode (uses local docker-compose)
claude-reviewer serve --dev

Configuration

Default Port

The web UI runs on port 3456 by default (chosen to avoid conflicts with common dev servers like React on 3000).

To use a different port:

# Via environment variable
PORT=8080 claude-reviewer serve

# Or via CLI flag
claude-reviewer serve --port 8080

Environment Variables

Variable	Description	Default
PORT	Port for web UI	3456
CLAUDE_REVIEWER_HOST	Host for review URLs	localhost
CLAUDE_REVIEWER_WEB_DIR	Path to web app	(auto-detected)

Database Location

Data is stored in ~/.claude-reviewer/data.db

CLAUDE.md Integration

Add claude-reviewer to your project's CLAUDE.md file so Claude Code knows how to use it:

## Code Review Workflow

When making significant changes, use the local review system:

1. Create a PR for review:
   ```bash
   claude-reviewer create --title "Description of changes"

2. Wait for review:

   claude-reviewer watch <pr-id> --until changes_requested
   

3. Address feedback by replying to comments:

   claude-reviewer comments <pr-id>
   claude-reviewer reply <pr-id> <comment-uuid> "Fixed by doing X"
   

4. Update the PR after fixes:

   claude-reviewer update <pr-id>
   

5. Merge when approved:

   claude-reviewer merge <pr-id>
   

## Docker

The `claude-reviewer serve` command automatically pulls and runs the Docker image.
You don't need to manually manage Docker - just run:

```bash
claude-reviewer serve   # Pulls image and starts container
claude-reviewer stop    # Stops the container

Manual Docker Usage

If you prefer to run Docker manually:

# Pull and run (using host user for proper file permissions)
docker run -d \
  --name claude-reviewer-web \
  --user "$(id -u):$(id -g)" \
  -p 3456:3000 \
  -v ~/.claude-reviewer:/data \
  -v ~:/host-home:ro \
  bowles/claude-reviewer:latest

Development with Docker Compose

For local development:

git clone https://github.com/bowlesb/claude-reviewer
cd claude-reviewer
pip install -e claude-reviewer-cli
claude-reviewer serve --dev

Integration with Claude Code

Claude Reviewer is designed to work seamlessly with Claude Code:

# Claude makes changes
git checkout -b feature/new-thing
# ... Claude writes code ...
git commit -m "Add new feature"

# Claude creates PR
claude-reviewer create --title "Add new feature"
# Output: Review URL: http://localhost:3456/prs/abc123

# User reviews in browser, requests changes

# Claude checks for feedback
claude-reviewer status abc123  # "changes_requested"
claude-reviewer comments abc123
# [src/api.py:45] Add input validation

# Claude addresses feedback
# ... makes fixes ...
git commit -m "Add input validation"
claude-reviewer update abc123

# User approves

# Claude merges
claude-reviewer merge abc123 --push

Development

# Clone the repo
git clone https://github.com/benbowles/claude-reviewer
cd claude-reviewer/claude-reviewer-cli

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
make test

# Type checking
make typecheck

# Format code
make format

License

MIT