ghreview

GitHub PR-based code review workflow for AI-assisted development.

Overview

ghreview bridges the gap between AI-assisted coding and GitHub's superior code review interface. It allows you to review AI-generated code changes using GitHub's familiar PR review tools while keeping your local repository pristine.

Why?

• Clean local state: Your working directory remains exactly as it was - no commits, no branch switches, no git operations visible in your project
• Familiar workflow: Use GitHub's excellent PR review interface with inline comments, suggestions, and discussions
• Private reviews: Use a dedicated private repository for reviews, keeping your AI interactions separate from your main project
• Zero footprint: Creates temporary branches and commits in a separate review repository, immediately cleaning up after pushing
• AI-friendly output: Collects all feedback in a structured format that's easy to paste back to your AI assistant

How?

1. You work with your AI assistant and have uncommitted changes in your project
2. ghreview init pushes your current state to a dedicated review repository without affecting your local git state
3. You review the changes on GitHub using all the familiar tools
4. ghreview collect gathers your feedback in a format optimized for AI consumption
5. Your local repository remains untouched throughout - as if git was never involved

Quick Start

Without Installation (Recommended)

# Create review PR
npx ghreview init

# Collect feedback after reviewing on GitHub
npx ghreview collect <PR-number>

With Global Installation

# Install globally
npm install -g ghreview

# Use commands
ghreview init
ghreview collect <PR-number>

Setup

1. Create a GitHub Personal Access Token

1. Go to https://github.com/settings/tokens/new (or navigate to Settings → Developer settings → Personal access tokens → Tokens (classic))
2. Give your token a descriptive name (e.g., "ghreview")
3. Set an expiration (or select "No expiration" for permanent access)
4. Select the repo scope - this grants full control of private repositories
   • ✓ repo (Full control of private repositories)
     • ✓ repo:status
     • ✓ repo_deployment
     • ✓ public_repo
     • ✓ repo:invite
     • ✓ security_events
5. Click "Generate token"
6. Important: Copy the token immediately - you won't be able to see it again!

2. Configure ghreview

Create a configuration file at ~/.ghreview/config.json:

{
  "reviewRepo": "yourusername/ai-code-reviews",
  "githubToken": "ghp_xxxxxxxxxxxxxxxxxxxx"
}

Replace yourusername with your GitHub username and paste your token in place of ghp_xxxxxxxxxxxxxxxxxxxx.

Security Note: Keep your token secure! The config file contains sensitive credentials. You may want to:

• Set appropriate file permissions: chmod 600 ~/.ghreview/config.json
• Never commit this file to version control
• Consider using a token with an expiration date

The review repository will be created automatically as a private repo if it doesn't exist.

Configuration Options

Basic Configuration

{
  "reviewRepo": "yourusername/ai-code-reviews",
  "githubToken": "ghp_xxxxxxxxxxxxxxxxxxxx"
}

With Custom Author

{
  "reviewRepo": "yourusername/ai-code-reviews",
  "githubToken": "ghp_xxxxxxxxxxxxxxxxxxxx",
  "author": {
    "name": "AI Assistant",
    "email": "ai@example.com"
  }
}

The author configuration makes commits appear as if they were created by the AI, making it clearer that you're reviewing the AI's proposed changes.

Workflow

1. Make changes to your code (but don't commit them)

2. Create a review PR:

   npx ghreview init
   

   This will:

   • Push your current commit as a base branch
   • Push your uncommitted changes as a review branch
   • Create a PR comparing the two
   • Output a URL to review the changes

3. Review on GitHub:

   • Click the provided URL
   • Review the changes using GitHub's PR interface
   • Leave inline comments on specific lines
   • Add general comments about architecture or approach

4. Collect feedback:

   # Using PR number (defaults to review repo)
   npx ghreview collect 42
   
   # Using full PR URL (works with any GitHub repo)
   npx ghreview collect https://github.com/owner/repo/pull/123
   

   This outputs formatted feedback that you can copy and paste into your AI assistant.

5. Iterate: Your local changes remain uncommitted, so you can continue working and create new review PRs as needed.

Example Output

## Code Review Feedback

### File: src/auth/login.js

#### Line 45
Variable 'username' could be undefined here. Add null check.

#### Lines 67-70
Use consistent async/await instead of mixing with .then()

### File: src/utils/validation.js

#### Line 12
Regex for email validation is too permissive

#### Lines 23-28
**Comment 1:** This validation logic is duplicated in register.js
**Comment 2:** Consider extracting to a shared validation utility

### General Comments

---

Consider adding rate limiting to login attempts

---

The session token storage in localStorage is insecure

Development

# Install dependencies
npm install

# Run linter
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Run tests
npm test

Requirements

• Node.js >= 22
• Git
• GitHub personal access token (configured in ~/.ghreview/config.json)
• SSH access to GitHub (the tool uses git@github.com: URLs for pushing)

License

Apache-2.0