Python Code Reviewer

A fast CLI tool for code review that uses AI only for actual analysis, not coordination. Replaces the multi-layer AI agent system with native Python orchestration.

Features

• Fast: Native Python coordination, no AI overhead
• Parallel Processing: 4 workers for concurrent file analysis
• Git Integration: Scan by commit, branch, PR, or unstaged changes
• Multi-Language: Support for PHP, JavaScript, and TypeScript
• Resume Support: Continue interrupted reviews
• Multiple Check Types: Abstraction, API, Complexity, Coupling, Security, State

Installation

# Install in editable mode (for development)
pip install -e /path/to/Pyton-Code-Reviewer

# Or install from git
pip install git+https://github.com/user/Pyton-Code-Reviewer.git

Prerequisites

• Python 3.11+
• OpenCode CLI installed and accessible
• Git repository (for git-based scopes)

Usage

# All files, all checks
code-reviewer

# Unstaged files only
code-reviewer unstaged

# Specific commit
code-reviewer commit abc123

# Branch comparison
code-reviewer branch feature-x
code-reviewer branch feature-x --base dev

# PR review
code-reviewer pr 123
code-reviewer pr 123 --base develop

# Specific manager only
code-reviewer --manager api

# Specific language only
code-reviewer --language php

# Markdown output
code-reviewer --format md

# Continue interrupted review
code-reviewer continue ./code-reports/code-review-20260123-143715

Sopes

Scope	Description	Example
all	All supported files	code-reviewer all
unstaged	Unstaged changes	code-reviewer unstaged
commit <hash>	Specific commit	code-reviewer commit abc123
branch <name>	Branch vs base	code-reviewer branch feature-x
pr <number>	Pull/Merge request	code-reviewer pr 123

Managers

• abstraction - Detect abstraction leaks and inappropriate intimacy
• api - Analyze API design and endpoint quality
• complexity - Identify overly complex code
• coupling - Find tight coupling between components
• security - Security vulnerability detection
• state - State management and mutation detection

Supported Specialist Agents

The tool includes 19 specialist agents covering 6 check types across 3 languages:

Abstraction Auditors (3):

• PHP Abstraction Auditor
• JavaScript Abstraction Auditor
• TypeScript Abstraction Auditor

API Designers (3):

• PHP API Designer
• JavaScript API Designer
• TypeScript API Designer

Complexity Checkers (3):

• PHP Complexity Checker
• JavaScript Complexity Checker
• TypeScript Complexity & Type Safety Checker

Coupling Analyzers (3):

• PHP Coupling Analyzer
• JavaScript Coupling Analyzer
• TypeScript Coupling Analyzer

Security Specialists (3):

• PHP Security Specialist
• JavaScript Security Specialist
• TypeScript Type Safety Specialist

State Auditors (4):

• PHP State Auditor
• JavaScript State Auditor
• TypeScript State Auditor

Report Format

Reports are saved to ./code-reports/code-review-YYYYMMDD-HHMMSS/ with:

• progress.json - Progress state (for resume support)
• {manager}-report.json - Aggregated findings per manager
• Console output - Summary with findings by severity

Each finding includes:

• smellName - Type of code smell detected
• severity - Critical, High, Medium, or Low
• filePath - Absolute path to the file
• lineStart / lineEnd - Line numbers of the issue
• description - Description of the issue
• suggestion - Recommended fix

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     code-reviewer.py (CLI)                      │
│  - Parse commands                                               │
│  - Detect project type/version                                  │
│  - Scan files (git/file system)                                 │
│  - Create report directory & progress.json                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  coordinator.py (Orchestration)                 │
│  - Group files by language                                      │
│  - Iterate through check types                                  │
│  - Call specialists via opencode_wrapper                         │
│  - Update progress.json                                         │
│  - Aggregate results                                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                 opencode_wrapper.py (Interface)                 │
│  - Call `opencode run --agent code-review-* --format json`      │
│  - Send file path, language, framework as JSON input            │
│  - Parse JSON response directly from agent stdout               │
│  - Handle errors/retries                                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              Specialist Agents (Direct JSON Output)             │
│  - 19 specialist agents for PHP/JS/TS                          │
│  - Return findings via stdout as JSON                          │
│  - No intermediate file writing                                │
└─────────────────────────────────────────────────────────────────┘

Agent Communication Flow

Input to specialist agent (via stdin):

{
  "file": "/path/to/file.php",
  "language": "php",
  "languageVersion": "8.2",
  "framework": "laravel"
}

Output from specialist agent (via stdout):

{
  "success": true,
  "findings": [
    {
      "smellName": "Long Parameter List",
      "severity": "Medium",
      "filePath": "/path/to/file.php",
      "lineStart": 45,
      "lineEnd": 45,
      "description": "public function createUser($name, $email, ...)",
      "suggestion": "Create a CreateUserRequest value object"
    }
  ],
  "summary": {
    "total": 1,
    "critical": 0,
    "high": 0,
    "medium": 1,
    "low": 0
  }
}

Development

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

# Run tests
pytest

# Format code
ruff check src/
ruff format src/

# Type check
mypy src/

License

MIT