Code Review

Japanese ver.

AI-powered code review CLI tool that helps developers get comprehensive code reviews by combining:

• Your task description (what you're trying to achieve)
• Your code changes (Git diff)
• Project context (file structure and related files)

What is this tool?

Code Review uses AI to review your code changes in the context of what you're trying to accomplish. Unlike simple linting tools, it understands your intent from a "ticket" (task description) and reviews whether your implementation correctly addresses that goal.

Key Features

• Context-aware reviews: Reviews code based on your task description, not just syntax
• Two-phase analysis: First identifies relevant files, then performs detailed review
• Security & performance focus: Catches potential vulnerabilities and performance issues
• Multilingual support: Reviews in your preferred language

Installation

# Install via npm
npm install -g @bloom-and-co/code-review

# Or install development version locally
git clone <repository-url>
cd code-review
npm install
npm run build
npm link

Setup

1. Get an API key from one of the supported providers:

   • Google AI (Gemini): Google AI Studio
   • OpenAI (GPT-4o): OpenAI Platform
   • Anthropic (Claude): Anthropic Console

2. Set environment variables

   Set the API key for your chosen provider:

   • GOOGLE_GENERATIVE_AI_API_KEY - For Google AI (Gemini)
   • OPENAI_API_KEY - For OpenAI (GPT-4o)
   • ANTHROPIC_API_KEY - For Anthropic (Claude)

   You have two options:

   Option 1: Export directly

   # For Google AI
   export GOOGLE_GENERATIVE_AI_API_KEY="your-api-key-here"
      
   # For OpenAI
   export OPENAI_API_KEY="your-api-key-here"
      
   # For Anthropic
   export ANTHROPIC_API_KEY="your-api-key-here"

   Option 2: Use .env file

   cp .env.sample .env
   # Edit .env file to set API key
   # Then use --dotenv option when running the tool

Configuration

You can override default settings with a JSON or YAML configuration file. The tool automatically looks for:

• code-review.config.yaml (or .yml)
• code-review.config.json
• .code-review.yaml (or .yml)
• .code-review.json

# Copy sample configuration file
cp code-review.config.example.yaml code-review.config.yaml

Configuration Priority

1. Command line options (highest priority)
2. Configuration file
3. Default values

Configuration File Example (YAML)

git:
  defaultDiffRange: ""  # Empty string = working directory changes (pre-commit)

models:
  # You can use models from any supported provider:
  # Google AI: gemini-2.5-flash, gemini-2.5-pro
  # OpenAI: gpt-4o
  # Anthropic: claude-3-7-sonnet-latest, claude-3-7-haiku-latest
  analyze: gemini-2.5-flash
  review: gemini-2.5-pro

prompts:
  analyzeMaxChars: 500000
  reviewMaxChars: 500000
  analyze: |
    Focus on security and performance-related files when listing additional files needed for review.
  review: |
    Focus on:
    1. Security vulnerabilities
    2. Performance issues
    3. Code readability
    4. Maintainability
    
    Mark issues with severity levels.

How it works

1. You provide a ticket file - A text file describing what you're implementing or fixing
2. The tool analyzes your Git changes - Compares your code changes against your stated goal
3. AI performs a two-phase review:
   • Phase 1: Identifies additional files needed for context
   • Phase 2: Provides detailed review with specific suggestions

Usage

Basic Usage

First, create a "ticket" file describing your task:

# Create a ticket file
echo "Add user authentication with JWT tokens" > ticket.md

# Run the review on your staged changes
npx @bloom-and-co/code-review --ticket ticket.md

What is a "ticket"?

A ticket is a text file containing your task description. It can be:

• A copy of your Jira/GitHub issue
• A simple description of what you're implementing
• Technical requirements or specifications
• Bug report you're fixing

Example ticket.md:

## Task: Add User Authentication

Implement JWT-based authentication with the following requirements:
- User login with email/password
- Token expiration after 24 hours
- Refresh token mechanism
- Secure password hashing with bcrypt

Common Use Cases

# Review changes before committing (default)
npx @bloom-and-co/code-review --ticket ticket.md

# Using .env file for API key
npx @bloom-and-co/code-review --ticket ticket.md --dotenv

# Review a specific commit
npx @bloom-and-co/code-review --ticket ticket.md --git-diff HEAD~1

# Review changes between branches
npx @bloom-and-co/code-review --ticket ticket.md --git-diff main..feature-branch

# Include specific files for context
npx @bloom-and-co/code-review --ticket ticket.md --add-files "src/config.ts,src/types.ts"

# Include files using wildcards
npx @bloom-and-co/code-review --ticket ticket.md --add-files "src/**/*.ts,docs/**/*.md"

# Review with custom language output
npx @bloom-and-co/code-review --ticket ticket.md --language "日本語"

# Use different AI providers
# OpenAI GPT-4o
npx @bloom-and-co/code-review --ticket ticket.md --analyze-model gpt-4o --review-model gpt-4o

# Anthropic Claude 3.7 Sonnet
npx @bloom-and-co/code-review --ticket ticket.md --analyze-model claude-3-7-sonnet-latest --review-model claude-3-7-sonnet-latest

# Google Gemini (default)
npx @bloom-and-co/code-review --ticket ticket.md --analyze-model gemini-2.5-flash --review-model gemini-2.5-pro

# Exclude specific files from diff (e.g., exclude generated files)
npx @bloom-and-co/code-review --ticket ticket.md --ignorefiles "*.generated.ts,build/*"

# Disable default ignore patterns to review all files
npx @bloom-and-co/code-review --ticket ticket.md --ignorefiles ""

Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --ticket | -t | Path to ticket/task description file (required) | - | | --config | -c | Path to configuration file (JSON/YAML) | - | | --git-diff | -g | Git diff range to review | "" (working directory) | | --no-diff | - | Skip git diff | - | | --all-files | - | Include all changed files and skip analyze phase | - | | --add-files | - | Additional files to include in review (comma-separated, supports wildcards) | - | | --dotenv | - | Load environment variables from .env file | - | | --debug | - | Debug mode (show prompts and responses to LLM) | - | | --language | - | Specify language for review output | - | | --analyze-model | - | Model for analyze phase | gemini-2.5-flash | | --review-model | - | Model for review phase | gemini-2.5-pro | | --analyze-prompt | - | Custom prompt for analyze phase | - | | --review-prompt | - | Custom prompt for review phase | - | | --analyze-max-chars | - | Max characters for analyze prompt | 500000 | | --review-max-chars | - | Max characters for review prompt | 500000 | | --ignorefiles | - | File patterns to exclude from diff (comma-separated) | Excludes many lock files and build artifacts by default |

Why Git Diff?

The tool uses Git diff to:

• Focus on what you actually changed
• Understand the context of your modifications
• Provide line-specific feedback
• Ensure reviews are relevant to your current work

By default, it reviews your working directory changes (staged + unstaged), perfect for pre-commit reviews.

Examples

Pre-commit review (most common)

# Review your changes before committing
npx @bloom-and-co/code-review --ticket ticket.md

Run with specific models

# Google Gemini models
npx @bloom-and-co/code-review \
  --ticket ticket.txt \
  --analyze-model "gemini-2.5-flash" \
  --review-model "gemini-2.5-pro"

# OpenAI GPT-4o
export OPENAI_API_KEY="your-openai-key"
npx @bloom-and-co/code-review \
  --ticket ticket.txt \
  --analyze-model "gpt-4o" \
  --review-model "gpt-4o"

# Anthropic Claude
export ANTHROPIC_API_KEY="your-anthropic-key"
npx @bloom-and-co/code-review \
  --ticket ticket.txt \
  --analyze-model "claude-3-7-sonnet-latest" \
  --review-model "claude-3-7-sonnet-latest"

Use custom prompts

npx @bloom-and-co/code-review \
  --ticket ticket.txt \
  --analyze-prompt "Focus on security issues" \
  --review-prompt "Emphasize performance problems"

Review specific commit range

# Diff with latest commit
npx @bloom-and-co/code-review --ticket ticket.txt --git-diff HEAD~1

# Diff between branches
npx @bloom-and-co/code-review --ticket ticket.txt --git-diff main..feature-branch

# Review only staging area
npx @bloom-and-co/code-review --ticket ticket.txt --git-diff --cached

Specify configuration file

npx @bloom-and-co/code-review --ticket ticket.txt --config my-config.yaml

Review all files without diff

npx @bloom-and-co/code-review --ticket ticket.txt --no-diff --all-files

Run in debug mode

npx @bloom-and-co/code-review --ticket ticket.txt --debug

Output review in Japanese

npx @bloom-and-co/code-review --ticket ticket.txt --language "日本語"

How the Review Process Works

Phase 1: Context Analysis

The AI first understands:

• What you're trying to achieve (from ticket)
• What files you've changed (from Git diff)
• Your project structure
• What additional files it needs to see (e.g., interfaces, configs)

Phase 2: Detailed Review

With full context, the AI:

• Reviews if your changes achieve the stated goal
• Checks for bugs, security issues, and performance problems
• Suggests improvements and best practices
• Highlights any missing implementations

Output Format

The output format depends on the prompts configured in your settings. By default, the tool provides a structured review in Markdown format, but the exact structure and content will vary based on:

• Your language settings
• Custom prompts in configuration
• The AI model's interpretation

Typical output structure:

# Code Review Results

## Summary
[Overall assessment based on your ticket requirements]

## Issues Found
[Categorized by severity: Critical/High/Medium/Low]

## Suggestions for Improvement
[Recommendations for better implementation]

Note: The actual format and categories may differ based on your prompts and language settings.

In debug mode (--debug), additional information is displayed:

• Full input prompts sent to LLM
• Analyze phase response (JSON format with required files)
• Input/output token counts for both phases
• Any errors or truncation warnings

Development

# Development mode (run TypeScript directly)
npm run dev -- --ticket ticket.txt

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

Best Practices

Writing Good Tickets

The quality of the review depends on your ticket clarity:

✅ Good ticket:

Implement user authentication with:
- JWT tokens for stateless auth
- Email/password login
- Password reset functionality
- Rate limiting on login attempts

❌ Poor ticket:

Add login feature

When to Use This Tool

• Before commits: Catch issues early
• Before pull requests: Ensure code quality
• During development: Get feedback on approach
• Code refactoring: Verify improvements
• Bug fixes: Confirm the fix addresses the issue

Notes

• Must be run within a Git repository
• Binary files are automatically skipped
• Files listed in .gitignore are excluded
• Large files are automatically truncated
• The AI reviews based on task context, not arbitrary instructions

Troubleshooting

API Key Error

Error: GOOGLE_GENERATIVE_AI_API_KEY environment variable is not set

→ Either:

• Export the environment variable: export GOOGLE_GENERATIVE_AI_API_KEY="your-key"
• Or use .env file with --dotenv option: npx @bloom-and-co/code-review --ticket ticket.md --dotenv

Git Repository Error

Error: Current directory is not a git repository

→ Run within a Git repository

JSON Parse Error

Error: Expected object, received array

→ LLM response is not in expected format. Check details with --debug option

Debug Mode

For detailed error information:

npx @bloom-and-co/code-review --ticket ticket.txt --debug

IMPORTANT: When updating this file, please also update corresponding content in other language versions (e.g., README.ja.md) to maintain consistency across all documentation.