Code Review Agent

A sophisticated AI-powered code review system using Claude with specialized sub-agents for comprehensive analysis.

Features

Code Review Agent (code_review_agent.py)

• 9 Specialized Sub-Agents analyzing different aspects:
  • CorrectnessAgent - Logical errors and bugs
  • SecurityAgent - Security vulnerabilities
  • PerformanceAgent - Performance bottlenecks
  • StyleAgent - Code readability and style
  • RobustnessAgent - Error handling and resilience
  • StructureAgent - Architecture and design patterns
  • TestingAgent - Test quality and completeness
  • CoverageAgent - Test coverage analysis
  • DocumentationAgent - Documentation quality

Test Fixer Agent (test_fixer.py)

• Automatically fixes failing tests through iterative analysis
• Intelligent stopping conditions to prevent infinite loops
• Service pattern architecture for testability

Refactoring Agent (refactoring_agent.py)

• Automatically refactors Python classes by extracting functions into service classes
• Identifies primary business logic function in each class
• Validation hooks ensure:
  • Service classes are created properly
  • No environment variable access in services
  • External clients use interfaces, not concrete implementations
• Intelligent retry mechanism learns from past failures
• Iterative refactoring until all functions are properly extracted

Architecture

Service Pattern for Testability

The project uses dependency injection to make the code testable:

IClaudeService (interface)
    ├── ClaudeServiceImpl (production)
    └── FakeClaudeService (testing)

This allows:

• Easy unit testing without API calls
• Mocking Claude responses
• Faster test execution
• Predictable test behavior

Installation

Using Virtual Environment (Recommended)

# Create venv and install all dependencies
make setup-venv

# Activate the virtual environment
source venv/bin/activate

# Run tests
make test

Using Make (System-wide)

# Install production dependencies
make install

# Install all dependencies (including test dependencies)
make install-dev

# Install and run tests
make all

Manual Installation

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-test.txt

Running from Any Directory

There are several ways to run these scripts from any location on your system:

Option 1: Using Full Paths (No Setup Required)

# Code review from anywhere
/path/to/code-review-agent/venv/bin/python /path/to/code-review-agent/src/code_review_agent.py --file myfile.py

# Test fixer from anywhere
/path/to/code-review-agent/venv/bin/python /path/to/code-review-agent/src/test_fixer.py

Option 2: Add to PATH (Recommended)

Add the project directory to your PATH in ~/.bashrc or ~/.zshrc:

# Add these lines to ~/.bashrc or ~/.zshrc
export CODE_REVIEW_AGENT="/path/to/code-review-agent"
export PATH="$PATH:$CODE_REVIEW_AGENT"
export PYTHONPATH="$PYTHONPATH:$CODE_REVIEW_AGENT"

# Create wrapper scripts in the project directory
# Then you can run: code-review --file myfile.py

Option 3: Create Shell Aliases

Add to ~/.bashrc or ~/.zshrc:

# Add these aliases
alias code-review='cd /path/to/code-review-agent && venv/bin/python src/code_review_agent.py'
alias test-fixer='cd /path/to/code-review-agent && venv/bin/python src/test_fixer.py'

# Usage:
# code-review --file ~/projects/myapp/src/main.py
# test-fixer ~/projects/myapp/tests/

Option 4: Create Wrapper Scripts in ~/bin

Create executable wrapper scripts that can be called from anywhere:

# Create ~/bin directory if it doesn't exist
mkdir -p ~/bin

# Create ~/bin/code-review
cat > ~/bin/code-review << 'EOF'
#!/bin/bash
SCRIPT_DIR="/path/to/code-review-agent"
cd "$SCRIPT_DIR" && venv/bin/python src/code_review_agent.py "$@"
EOF

# Create ~/bin/test-fixer
cat > ~/bin/test-fixer << 'EOF'
#!/bin/bash
SCRIPT_DIR="/path/to/code-review-agent"
cd "$SCRIPT_DIR" && venv/bin/python src/test_fixer.py "$@"
EOF

# Make scripts executable
chmod +x ~/bin/code-review
chmod +x ~/bin/test-fixer

# Add ~/bin to PATH if not already (in ~/.bashrc or ~/.zshrc)
export PATH="$HOME/bin:$PATH"

# Now you can run from anywhere:
# code-review --file ~/projects/myapp/main.py
# test-fixer ~/projects/myapp/tests/

Option 5: Using Make from Any Directory

# Run make targets from anywhere
make -C /path/to/code-review-agent test
make -C /path/to/code-review-agent run-review-file FILE=/absolute/path/to/file.py
make -C /path/to/code-review-agent run-fixer-path PATH=/absolute/path/to/tests/

# Create a shell alias for convenience
alias code-review-make='make -C /path/to/code-review-agent'

# Then use: code-review-make test

Quick Start with Make

# Show all available commands
make help

# Install dependencies and run tests
make all

# Run tests
make test

# Run code review on a file
make run-review-file FILE=test_fixer.py

# Run test fixer
make run-fixer

Usage

Code Review Agent

# Using Make (recommended)
make run-review                              # Interactive mode
make run-review-file FILE=path/to/file.py   # Review specific file

# Using Python directly from project root
python src/code_review_agent.py --model sonnet
python src/code_review_agent.py --file path/to/file.py
python src/code_review_agent.py --file test_fixer.py --stats true

# Or with venv
venv/bin/python src/code_review_agent.py --model sonnet

Test Fixer Agent

# Using Make (recommended)
make run-fixer                          # Fix tests in current directory
make run-fixer-path PATH=test_main.py  # Fix specific test file

# Using Python directly from project root
python src/test_fixer.py                    # Fix tests in current directory
python src/test_fixer.py test_main.py      # Fix specific test file
python src/test_fixer.py --max-iterations 10  # Custom safety limit
python src/test_fixer.py --model opus        # Use different model

# Or with venv
venv/bin/python src/test_fixer.py

Refactoring Agent

# Refactor a Python class file
python src/refactoring_agent.py path/to/file.py

# With options
python src/refactoring_agent.py file.py --model opus        # Use Claude Opus
python src/refactoring_agent.py file.py --max-iterations 30 # Limit iterations
python src/refactoring_agent.py file.py --verbose           # Verbose output
python src/refactoring_agent.py file.py --dry-run           # Preview changes

# Example: Refactor the sample file
python src/refactoring_agent.py examples/sample_class_to_refactor.py

# Or with venv
venv/bin/python src/refactoring_agent.py file.py

How Refactoring Works

1. Analysis: The agent analyzes your class to understand its structure
2. Primary Function: Identifies the main business logic function (not constructor)
3. Extraction: Iteratively extracts other functions into service classes
4. Validation: Each extraction is validated with hooks:
   • Service class creation check
   • No environment variables in services
   • External clients use interfaces
5. Retry Logic: Failed extractions are retried with knowledge of past failures
6. Completion: Continues until all functions are properly refactored

Test Fixer: Agent-Driven Stopping

The test fixer uses an intelligent, agent-driven approach instead of arbitrary limits.

How It Works

After each fix attempt, Claude analyzes:

• Progress tracking: Are failures decreasing?
• Pattern detection: Are we repeating the same failed approaches?
• Strategy assessment: Do we have alternative strategies to try?
• Solvability analysis: Is this problem fixable with available information?

Based on this analysis, Claude decides whether to continue or stop.

Example Agent Decision

CONTINUE: I'll try a different approach - using mock objects instead of
real dependencies, which should resolve the initialization errors.

or

STOP: We've attempted 3 different mocking strategies and the same
import error persists. This appears to be a dependency issue that
requires manual investigation of the project setup.

Safety Stopping Conditions

While the agent makes primary decisions, these safety conditions override:

1. Success: All tests pass ✅
2. Safety limit: 20 iterations (rarely hit, agent stops before this)
3. Breaking changes: Test count drops significantly
4. User interruption: Ctrl+C

Benefits Over Fixed Iteration Limits

✅ Intelligent decisions: Agent recognizes when it's stuck vs. when it has new ideas ✅ Learns from history: Previous attempts inform future strategies ✅ Avoids repetition: Won't try the same failed approach twice ✅ Natural stopping: Stops when truly stuck, not at arbitrary limits ✅ Better success rate: Can try more approaches when making progress

Running Tests

Using Make (Recommended)

# Run all tests
make test

# Run with verbose output
make test-verbose

# Run with coverage report
make test-coverage

# Run specific test file
make test-specific FILE=test_main.py

# Run only code review agent tests
make test-main

# Run only test fixer tests
make test-fixer

# Show all available targets
make help

Using pytest directly

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest test_main.py

# Run with coverage
pytest --cov=. --cov-report=html

Using Docker

Run tests in an isolated Docker container:

# Build and run tests in one command
make docker-test

# Or build and run separately
make docker-build-test
docker run --rm code-review-agent-test

# Clean up Docker image
make docker-clean

This ensures tests run in a clean, reproducible environment with all dependencies properly installed.

Project Structure

code-review-agent/
├── src/                           # Source code
│   ├── __init__.py
│   ├── code_review_agent.py      # Code review orchestrator
│   ├── test_fixer.py             # Automatic test fixer
│   ├── refactoring_agent.py      # Automatic code refactoring
│   ├── claude_service.py         # Service interface & implementations
│   └── cli_tools.py              # Rich console utilities
├── tests/                         # Test files
│   ├── __init__.py
│   ├── test_main.py              # Unit tests for code_review_agent
│   ├── test_test_fixer.py        # Unit tests for test_fixer
│   └── test_refactoring_agent.py # Unit tests for refactoring_agent
├── examples/                      # Example files
│   └── sample_class_to_refactor.py # Sample for refactoring demo
├── requirements.txt               # Production dependencies
├── requirements-test.txt          # Test dependencies
├── projects.db                    # Project tracking database
├── Makefile                       # Build automation
├── Dockerfile.test                # Docker image for running tests
├── .dockerignore                  # Docker ignore patterns
├── .gitignore                     # Git ignore patterns
└── README.md                      # This file

Makefile Reference

The Makefile provides convenient shortcuts for common tasks:

Testing

• make test - Run all tests
• make test-verbose - Run tests with detailed output
• make test-coverage - Generate coverage report
• make test-main - Test code_review_agent only
• make test-fixer - Test test_fixer only
• make test-specific FILE=tests/<file> - Test specific file

Installation

• make install - Install production dependencies
• make install-dev - Install all dependencies (including dev)
• make all - Clean, install, and test

Running Agents

• make run-review - Start code review agent (interactive)
• make run-review-file FILE=<file> - Review specific file
• make run-fixer - Run test fixer on current directory
• make run-fixer-path PATH=<path> - Fix specific test path

Maintenance

• make clean - Remove generated files (cache, coverage, etc.)
• make db-reset - Reset projects database
• make format - Format code with black (if installed)
• make lint - Lint code with flake8 (if installed)
• make check - Run lint + tests

Docker

• make docker-build-test - Build Docker test image
• make docker-test - Build and run tests in Docker
• make docker-clean - Remove Docker test image

Help

• make help - Show all available targets

Example: Testing with FakeClaudeService

import asyncio
from src.claude_service import FakeClaudeService
from src.code_review_agent import main

async def test_code_review():
    # Create fake service with mock responses
    mock_responses = [
        {"type": "text", "content": "Analysis complete"}
    ]
    fake_service = FakeClaudeService(mock_responses=mock_responses)

    # Test main() with dependency injection
    await main(claude_service=fake_service)

    # Verify queries sent
    queries = fake_service.get_queries()
    assert len(queries) == 1
    assert "review" in queries[0]

asyncio.run(test_code_review())

Design Principles

Dependency Injection

• Main functions accept optional service parameters
• Enables testing without external dependencies
• Follows SOLID principles

Interface Segregation

• IClaudeService defines clean contract
• Multiple implementations for different use cases
• Easy to extend with new implementations

Single Responsibility

• Each agent has one specific focus area
• Service layer handles only Claude communication
• Clear separation of concerns

Benefits of This Architecture

1. Testability: Full unit test coverage without API calls
2. Flexibility: Easy to swap implementations
3. Maintainability: Clear interfaces and separation
4. Reliability: Tests run fast and deterministically
5. Extensibility: Simple to add new agent types

Contributing

When adding new features:

1. Define interfaces for external dependencies
2. Create both real and fake implementations
3. Write unit tests using fake implementations
4. Document stopping conditions for loops
5. Follow existing patterns for consistency

License

MIT License - feel free to use and modify as needed.