# lens

AI-powered GitHub PR code reviewer for teams. Fetches a pull request, reviews each changed file against your coding guidelines using Claude or GPT-4o, and posts inline comments directly on GitHub.

## Features

- Reviews only added/modified files — skips deleted files and binary assets
- Supports **Anthropic Claude** and **OpenAI GPT-4o** as AI backends
- Bring your own guidelines via a simple YAML config file
- Posts inline review comments on the diff using the GitHub Review API
- Runs as a **CLI tool** locally or as a **GitHub Action** automatically on every PR
- Prevents duplicate comments across repeated runs
- Filters known AI false positives (hallucinated suggestions)

## Installation

```bash
pip install prlens
```

## Quick Start (CLI)

```bash
export GITHUB_TOKEN=ghp_...
export ANTHROPIC_API_KEY=sk-ant-...

prlens --repo owner/repo --pr 42 --model anthropic
```

Omit `--pr` to list open PRs and pick one interactively.

## GitHub Action

Add this workflow to your repository to automatically review every pull request:

```yaml
# .github/workflows/code-review.yml
name: Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: jodohq/prlens/.github/actions/review@main
        with:
          model: anthropic
          github-token: ${{ secrets.GITHUB_TOKEN }}
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
```

## Configuration

Copy `.prlens.example.yml` to `.prlens.yml` in your repository root:

```yaml
# .prlens.yml
model: anthropic          # anthropic | openai
max_chars_per_file: 20000
batch_limit: 60

# Path to your team's coding guidelines (relative to repo root)
# guidelines: ./docs/guidelines.md

# Files/directories to skip — fnmatch globs or directory names
# exclude:
#   - migrations/
#   - "*.min.js"

# Set to true to review draft PRs (skipped by default)
review_draft_prs: false
```

The `--model` and `--guidelines` CLI flags override the config file. The config file overrides built-in defaults.

## Custom Guidelines

Point `guidelines` in `.prlens.yml` to any Markdown file containing your team's coding standards:

```yaml
guidelines: ./docs/guidelines.md
```

When not set, built-in generic guidelines are used as a starting point. Copy them from [`prlens/guidelines/`](prlens/guidelines/) and customize.

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `GITHUB_TOKEN` | Yes | GitHub personal access token with `pull_requests: write` |
| `ANTHROPIC_API_KEY` | When using Claude | Anthropic API key |
| `OPENAI_API_KEY` | When using GPT-4o | OpenAI API key |

## CLI Reference

```
Usage: prlens [OPTIONS]

  AI-powered GitHub PR code reviewer.

Options:
  --repo TEXT                GitHub repository in owner/name format. [required]
  --pr INTEGER               Pull request number. Omit to list open PRs interactively.
  --model [anthropic|openai] AI model provider. Overrides config file.
  --config TEXT              Path to the configuration file. [default: .prlens.yml]
  -y, --yes                  Skip confirmation prompts and post comments automatically.
  --guidelines PATH          Path to a Markdown guidelines file. Overrides config file.
  -s, --shadow               Dry-run mode: print review comments to the terminal without posting to GitHub.
  --help                     Show this message and exit.
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development environment, run tests, and add new AI providers.

## License

[MIT](LICENSE)
