What is this? A CLI tool that runs multiple AI agents to review your code changes. Each agent specializes in different aspects: bugs, security, performance, code style. Works with Claude Code, Cursor Agent, OpenCode, or Codex CLI.

How is it different from diffray.ai? The cloud platform automatically learns from your team's review feedback and generates rules. This CLI version requires manual rule configuration but gives you full control and runs locally.

Table of Contents

• Quick Start
• Prerequisites
• How It Works
• Configuration
• Creating Custom Agents
• Creating Custom Rules
• Overriding Agents and Rules
• FAQ
• Development

Quick Start

1. Install diffray

# Install globally from npm
npm install -g diffray

2. Run your first review

# Go to your project
cd your-project

# Review your uncommitted changes (or last commit if working tree is clean)
diffray review

# Or review changes between branches
diffray review --base main

That's it! diffray will analyze your changes and show any issues found.

Common Commands

# Review uncommitted changes, or last commit if clean
diffray review

# Review changes compared to main branch
diffray review --base main

# Review last 3 commits
diffray review --base HEAD~3

# Review specific file(s) - only git changes in these files
diffray review --files src/auth.ts
diffray review --files src/auth.ts,src/user.ts

# Review entire file content (without git diff)
diffray review --files src/auth.ts --full

# Show only critical and high severity issues
diffray review --severity critical,high

# Run only specific agent
diffray review --agent bug-hunter

# Output as JSON (for CI/CD pipelines)
diffray review --json

# Show detailed progress
diffray review --stream

# List available agents and rules
diffray agents
diffray rules

Prerequisites

• Git - your project must be a git repository
• AI CLI Tool - diffray uses external AI tools to analyze code. You need to install and authorize one of them:

Claude Code CLI (default)

Claude Code is an official Anthropic CLI tool with agentic capabilities.

# Install
npm install -g @anthropic-ai/claude-code

# Authorize (opens browser for OAuth)
claude auth login

Cursor Agent CLI (alternative)

If you use Cursor IDE, you can use its agent CLI instead:

# Install
curl https://cursor.com/install -fsS | bash

# Authorize (opens browser)
cursor-agent

Then switch diffray to use it:

# Via config
diffray config init
# Edit .diffray.json and add: "executor": "cursor-agent-cli"

# Or per-run
diffray review --executor cursor-agent-cli

OpenCode CLI (alternative)

Modern AI CLI with support for multiple model providers:

# Install
curl https://opencode.ai/install -fsS | bash

# Authorize (opens browser)
opencode auth login

Then switch diffray to use it:

# Via config
diffray config init
# Edit .diffray.json and add: "executor": "opencode-cli"

# Or per-run
diffray review --executor opencode-cli

Costs depend on your AI provider's pricing. Claude Code uses your Anthropic account or Claude Pro subscription. Cursor Agent uses your Cursor subscription. Codex CLI uses your OpenAI account.

Codex CLI (alternative)

OpenAI Codex CLI for local code review:

# Install
npm install -g @openai/codex

Then switch diffray to use it:

# Via config
diffray config init
# Edit .diffray.json and add: "executor": "codex-cli"

# Or per-run
diffray review --executor codex-cli

Tips to reduce costs:

• Review smaller changesets more frequently
• Use --agent flag to run only specific agents
• Use --skip-validation to skip the validation stage (faster but more false positives)

How It Works

Pipeline

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Git Diffs  │───▶│ Match Rules │───▶│ Run Agents  │───▶│  Deduplicate│
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
                                            │                   │
                                            ▼                   ▼
                                      ┌─────────────┐    ┌─────────────┐
                                      │  Agent 1    │    │  Validate   │
                                      │  Agent 2    │    │  (filter    │
                                      │  Agent 3    │    │   false +)  │
                                      │  ...        │    └─────────────┘
                                      └─────────────┘           │
                                                                ▼
                                                         ┌─────────────┐
                                                         │   Report    │
                                                         └─────────────┘

Agents

diffray uses multiple specialized AI "agents" that each focus on one type of problem:

| Agent | What it finds | |-------|---------------| | general | Code quality, readability, simplicity issues | | bug-hunter | Logic errors, null checks, edge cases | | security-scan | Vulnerabilities, exposed secrets | | performance-check | Memory leaks, slow code | | consistency-check | Inconsistent patterns, naming conventions |

Each agent analyzes your code independently, then results are:

1. Deduplicated - remove duplicates if multiple agents found the same issue
2. Validated - AI double-checks each issue to filter out false alarms

Only verified issues are shown in the final report.

Want to understand the architecture? See docs/ARCHITECTURE.md for details on agents, executors, and the stage pipeline.

Configuration (Optional)

diffray works out of the box with sensible defaults. Create .diffray.json in your project to customize:

Example configuration

{
  "excludePatterns": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/__tests__/**",
    "dist/**"
  ],
  "concurrency": 6,
  "executor": "claude-cli",
  "agents": {
    "performance-check": { "enabled": false },
    "bug-hunter": { "model": "haiku", "timeout": 60 }
  },
  "rules": {
    "code-security": { "enabled": false }
  },
  "executors": {
    "claude-cli": {
      "review": { "model": "sonnet", "timeout": 120, "concurrency": 6 },
      "validation": { "model": "opus", "timeout": 180, "batchSize": 10 }
    }
  }
}

Options reference

| Option | Description | |--------|-------------| | extends | Load agents/rules from git repos (e.g., ["https://github.com/owner/repo#v1.0"]) | | excludePatterns | Glob patterns for files to skip | | concurrency | Max parallel agents (1-10, default: 6). Stage-specific settings override this. | | executor | Which executor to use (claude-cli, cursor-agent-cli, opencode-cli) | | agents.<name> | Override agent settings (enabled, model, timeout) | | rules.<name> | Override rule settings (enabled, agent) | | executors.<name>.<stage> | Per-executor, per-stage settings (model, timeout, concurrency, batchSize) |

Model Override Options

Available Models by Executor

| Executor | Available Models | Examples | |----------|------------------|----------| | claude-cli | haiku, sonnet, opus (aliases) | sonnet, claude-sonnet-4-5-20250929 | | cursor-agent-cli | auto, gpt-5.2, opus-4.5, sonnet-4.5, gemini-3-pro, grok | cursor-agent --model opus-4.5 | | opencode-cli | opencode/gpt-5-nano, opencode/grok-code, opencode/glm-4.7-free | opencode --model opencode/gpt-5-nano |

Override Hierarchy (highest to lowest priority)

1. CLI flags - diffray review --model sonnet
2. Project config - .diffray.json
3. Global config - ~/.diffray/config.json
4. Defaults - Built-in defaults

Configuration Examples

Global config (~/.diffray/config.json):

{
  "executor": "claude-cli",
  "executors": {
    "claude-cli": {
      "review": { "model": "sonnet", "concurrency": 6 },
      "validation": { "model": "opus", "timeout": 180 }  // Use most powerful model for validation
    },
    "cursor-agent-cli": {
      "review": { "model": "opus-4.5" },
      "validation": { "model": "opus-4.5" }  // Use same powerful model for validation
    },
    "opencode-cli": {
      "review": { "model": "opencode/gpt-5-nano" },
      "validation": { "model": "opencode/grok-code" }
    }
  },
  "agents": {
    "security-scan": { "model": "sonnet" },
    "bug-hunter": { "model": "opus" },
    "performance-check": { "model": "haiku" }
  }
}

Project config (.diffray.json):

{
  "executors": {
    "claude-cli": {
      "review": { "model": "haiku" },
      "validation": { "model": "sonnet" }
    }
  },
  "agents": {
    "security-scan": { "model": "sonnet", "timeout": 180 },
    "consistency-check": { "enabled": false }
  }
}

CLI Override Examples

# Override model for all agents
diffray review --model sonnet

# Use different executor with specific model
diffray review --executor cursor-agent-cli --model opus-4.5

# Fast review with Haiku for all agents
diffray review --model haiku --skip-validation

# Security scan with Opus (most thorough)
diffray review --agent security-scan --model opus

# Mixed: use OpenCode with specific model
diffray review --executor opencode-cli --model opencode/gpt-5-nano

# Override for validation stage only (via config)
# See configuration examples above

Practical Use Cases

| Scenario | Recommended Configuration | Reason | |----------|-------------------------|--------| | Everyday development | haiku for review, sonnet for validation | Fast feedback, reasonable quality | | Security review | opus for security-scan agent | Most thorough analysis for vulnerabilities | | Performance testing | sonnet for performance-check agent | Good balance of speed and accuracy | | Large PR review | haiku + --skip-validation | Process large changesets quickly | | Critical production | opus for all agents | Maximum thoroughness for critical code | | Validation phase | Always use most powerful model | Prevents false positives, ensures quality | | Cost optimization | cursor-agent-cli with gpt-5.2 | Often more cost-effective than Claude | | Multi-model strategy | Mix models per agent type | Optimize quality/speed per use case |

Performance vs Quality Trade-offs

| Model | Speed | Quality | Cost | Best For | |-------|-------|---------|------|----------| | haiku | ⚡ Fast | Good | 💰 Low | Daily development, large PRs | | sonnet | 🚀 Moderate | Excellent | 💸💰 Medium | Most use cases, balanced approach | | opus | 🚀 Fast | Outstanding | 💸💸💸 High | Optimal balance of speed and quality, security, critical bugs | | gpt-5.2 | 🚀 Fast | Very Good | 💸 Medium | General purpose, cost-effective | | opencode/gpt-5-nano | ⚡ Fast | Good | 💰 Low | Quick reviews, prototyping |

💡 Pro Tip: For the validation phase, always use the most powerful model available (e.g., opus or gpt-5.2). Validation filters false positives and ensures only real issues are reported, making it worth the extra cost.

Extends

Share agents and rules across projects by loading them from any git repository:

{
  "extends": [
    "https://github.com/diffray/diffray-rules"
  ]
}

Supports any git URL:

• https://github.com/owner/repo — HTTPS, default branch
• https://github.com/owner/repo#v1.0 — specific tag/branch
• [email protected]:owner/repo.git — SSH format

Extends commands:

# Install extends from config
diffray extends install

# Install specific URL (auto-adds to config)
diffray extends install https://github.com/owner/repo

# Force re-clone all extends
diffray extends install --force

# List installed extends
diffray extends list

# Remove an extend
diffray extends remove https://github.com/owner/repo

Agents/rules from extends have lower priority than local ones.

Config commands

# Create config file
diffray config init

# Edit config in your editor
diffray config edit

# Show current config
diffray config show

Creating Custom Agents

You can create your own agents to check for anything you want! Agents are simple Markdown files.

Where to put agent files

| Location | When to use | |----------|-------------| | ~/.diffray/agents/ | Your personal agents (work in all projects) | | .diffray/agents/ | Project-specific agents (share with team via git) |

Agent file format

Each agent is a .md file with two parts:

1. Header (between --- lines) - settings in YAML format
2. Body - instructions for the AI (what to look for)

Step-by-step: Create your first agent

Step 1. Create the folder (if it doesn't exist):

mkdir -p ~/.diffray/agents

Step 2. Create a new file ~/.diffray/agents/my-rules.md:

---
name: my-rules
description: Checks for my team's coding standards
enabled: true
---

You are a code reviewer checking for our team's coding standards.

## What to check:

1. **No console.log** - All console.log statements should be removed before commit
2. **Function comments** - All exported functions must have a description comment
3. **Error handling** - All async functions must have try/catch blocks
4. **Naming** - Variables should have meaningful names (no single letters except in loops)

## How to report:

- Only report clear violations
- Be specific about what line and what's wrong
- Suggest how to fix it

Step 3. Verify your agent is loaded:

diffray agents

You should see my-rules in the list.

Step 4. Run a review - your agent will now analyze your code!

diffray review

Header fields explained

---
name: my-rules              # Unique ID (lowercase, use dashes)
description: What it does   # Short description
enabled: true               # Set to false to disable temporarily
order: 10                   # Lower = runs first (optional, default: 0)
---

Example agents

React best practices checker

---
name: react-checker
description: Checks React code for common mistakes
enabled: true
---

You are a React expert reviewing code for common mistakes.

## Check for:

1. **Missing keys in lists** - All .map() rendering elements need unique key props
2. **useEffect dependencies** - Missing dependencies in useEffect arrays
3. **State mutations** - Direct state mutations instead of setState
4. **Memory leaks** - Missing cleanup in useEffect (event listeners, subscriptions)

## Ignore:
- Styling preferences
- Minor formatting issues

API security checker

---
name: api-security
description: Checks API endpoints for security issues
enabled: true
---

You are a security engineer reviewing API code.

## Check for:

1. **Missing authentication** - Endpoints without auth checks
2. **SQL injection** - User input in SQL queries without parameterization
3. **Missing rate limiting** - Public endpoints without rate limits
4. **Exposed secrets** - API keys, passwords, tokens in code

## Report format:
- Severity: CRITICAL for exploitable issues, HIGH for potential issues
- Include the specific line and code snippet
- Explain the attack vector
- Provide a fix

TypeScript strict checker

---
name: typescript-strict
description: Enforces strict TypeScript practices
enabled: true
---

You are a TypeScript expert checking for type safety.

## Check for:

1. **any type** - Usage of 'any' type (should be specific type or 'unknown')
2. **Type assertions** - Unnecessary 'as' casts that could hide errors
3. **Missing null checks** - Accessing properties that could be null/undefined
4. **Implicit any** - Function parameters without type annotations

## Ignore:
- Third-party library types
- Test files

Tips for writing good agents

1. Be specific - "Check for console.log" is better than "check for debug code"
2. Give examples - Show what bad code looks like
3. Set priorities - Tell the AI what's important vs minor
4. Define what to ignore - Reduce false positives

Managing agents

# List all agents (shows name, description, enabled status)
diffray agents

# Show full details of an agent
diffray agents bug-hunter

# Disable an agent via config (without deleting the file)
# Add to .diffray.json:
{
  "agents": {
    "my-rules": { "enabled": false }
  }
}

Troubleshooting

Agent not showing up?

• Check file has .md extension
• Check file is in correct folder (~/.diffray/agents/ or .diffray/agents/)
• Check YAML header syntax (must be between --- lines)

Agent not finding issues?

• Make instructions more specific
• Add examples of what to look for
• Check enabled: true in header

Creating Custom Rules

Rules connect agents to files. They tell diffray: "Run this agent on these files".

What are rules?

By default, diffray runs ALL agents on ALL changed files. But with rules you can:

• Run security-scan agent only on *.ts files
• Run python-checker agent only on *.py files
• Add extra instructions for specific file types

Where to put rule files

| Location | When to use | |----------|-------------| | ~/.diffray/rules/ | Your personal rules (work in all projects) | | .diffray/rules/ | Project-specific rules (share with team via git) |

Rule file format

Rules are also Markdown files with a header:

---
name: frontend-bugs
description: Bug detection for React frontend
patterns:
  - "src/components/**/*.tsx"
  - "src/hooks/**/*.ts"
agent: bug-hunter
---

Extra instructions for this rule (optional).

Focus on React-specific issues like:
- Missing useCallback/useMemo
- Incorrect dependency arrays

Step-by-step: Create your first rule

Step 1. Create the folder:

mkdir -p ~/.diffray/rules

Step 2. Create ~/.diffray/rules/python-security.md:

---
name: python-security
description: Security checks for Python files
patterns:
  - "**/*.py"
agent: security-scan
---

Focus on Python-specific security issues:

1. **eval() and exec()** - Dynamic code execution
2. **pickle** - Insecure deserialization
3. **subprocess** - Command injection via shell=True
4. **SQL** - String formatting in SQL queries
5. **YAML** - yaml.load() without safe_load

Step 3. Verify your rule is loaded:

diffray rules

You'll see your rule with a badge indicating its source:

• ◆ defaults — Built-in rules
• ◉ extends — Rules from extended repositories
• ◇ user — Your personal rules (~/.diffray/rules/)
• ● project — Project rules (.diffray/rules/)

Step 4. Test which files match your rule:

diffray rules python-security --test src/

Header fields explained

---
name: python-security       # Unique ID (lowercase, use dashes)
description: What it does   # Short description
patterns:                   # Which files to match (glob patterns)
  - "**/*.py"               # All Python files
  - "scripts/*.sh"          # Shell scripts in scripts/ folder
agent: security-scan        # Which agent to run on matched files
---

Understanding patterns (glob syntax)

Patterns use "glob" syntax to match files:

| Pattern | What it matches | |---------|-----------------| | *.ts | All .ts files in root folder only | | **/*.ts | All .ts files in any folder | | src/**/*.ts | All .ts files inside src/ folder | | src/*.ts | Only .ts files directly in src/ (not subfolders) | | **/*.{ts,tsx} | All .ts and .tsx files | | !**/*.test.ts | Exclude test files (prefix with !) |

Example rules

Backend API security

---
name: api-security
description: Security review for API endpoints
patterns:
  - "src/api/**/*.ts"
  - "src/routes/**/*.ts"
  - "src/controllers/**/*.ts"
agent: security-scan
---

Focus on API security:

1. Check authentication on all endpoints
2. Validate all user input
3. Check for SQL/NoSQL injection
4. Verify rate limiting
5. Check CORS configuration

React components quality

---
name: react-quality
description: Quality checks for React components
patterns:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
agent: bug-hunter
---

Focus on React best practices:

1. Missing key props in lists
2. useEffect dependency arrays
3. Memory leaks (missing cleanup)
4. Prop types validation
5. Conditional rendering bugs

Config files security

---
name: config-security
description: Check config files for exposed secrets
patterns:
  - "**/*.json"
  - "**/*.yaml"
  - "**/*.yml"
  - "**/*.env.example"
agent: security-scan
---

Check for:

1. Hardcoded API keys or tokens
2. Database credentials
3. Private keys
4. Sensitive URLs

Input validation with Zod

---
name: input-validation
description: Ensure all input validation uses Zod schemas
patterns:
  - "src/**/*.ts"
  - "bin/**/*.ts"
agent: general
---

# Input Validation with Zod

All input validation must use Zod schemas for type safety and consistency.

## ❌ Avoid manual validation:
- Manual `parseInt`, `parseFloat`, `isNaN` checks
- String splitting with manual array validation
- Custom error throwing for validation
- Inline boundary checks (e.g., `if (val < 0 || val > 100)`)

## ✅ Use Zod schemas instead:
- `.coerce.number()` for automatic number parsing
- `.transform()` for custom transformations
- `.refine()` for validation with clear error messages
- Centralized schemas in separate files (e.g., `*-schema.ts`)

## Example

See `src/cli-schema.ts` for proper Zod validation patterns.

## When to flag

Flag code with manual validation of user input (CLI args, API inputs, config).

Note: This is a real example from the diffray codebase. See .diffray/rules/validation.md for the full version.

Documentation checker

---
name: docs-quality
description: Check documentation for issues
patterns:
  - "**/*.md"
  - "docs/**/*"
agent: general
---

Check documentation for:

1. Broken links
2. Outdated code examples
3. Missing sections
4. Typos in commands

Default rules (built-in)

diffray comes with these rules out of the box:

| Rule | Files | Agent | |------|-------|-------| | code-general | *.ts, *.js, *.py, *.go, *.rs, *.java, *.rb, *.php, ... | general | | code-bugs | Same as above | bug-hunter | | code-security | Same as above | security-scan | | code-performance | Same as above | performance-check | | code-consistency | Same as above + *.md, *.json, *.yaml | consistency-check | | config-security | *.json, *.yaml, *.yml, *.toml | security-scan |

Managing rules

# List all rules
diffray rules

# Show rule details
diffray rules code-bugs

# Test which files a rule matches
diffray rules code-bugs --test src/

# Disable a rule via config
# Add to .diffray.json:
{
  "rules": {
    "code-performance": { "enabled": false }
  }
}

Rules vs Agents: What's the difference?

| | Agent | Rule | |---|-------|------| | What | The AI reviewer (what to check) | The file filter (where to check) | | Contains | Instructions for AI | File patterns + which agent to use | | Example | "Check for SQL injection" | "Run security-scan on *.py files" |

Think of it this way:

• Agent = The inspector (knows what problems to look for)
• Rule = The assignment (tells inspector which rooms to check)

Troubleshooting

Rule not matching files?

• Check pattern syntax (use **/*.ts not *.ts for recursive)
• Test with diffray rules your-rule --test path/
• Remember patterns are relative to project root

Agent not running on expected files?

• Make sure rule's agent field matches an existing agent name
• Check that both rule and agent have enabled: true

Overriding Agents and Rules

Besides config file overrides (see Configuration), you can completely replace built-in agents/rules by creating files with the same name.

Priority order (highest to lowest):

1. .diffray/agents/ or .diffray/rules/ (project folder)
2. ~/.diffray/agents/ or ~/.diffray/rules/ (home folder)
3. Built-in defaults

Example: To replace the built-in bug-hunter agent:

mkdir -p .diffray/agents

Create .diffray/agents/bug-hunter.md:

---
name: bug-hunter
description: My custom bug hunter
enabled: true
---

Your completely custom instructions here...

FAQ

Why is it slow?

diffray uses Claude AI which takes time to analyze code properly. Typical review takes 10-30 seconds. For faster (but less accurate) reviews, use:

diffray review --skip-validation

Why didn't it find an obvious bug?

AI isn't perfect. diffray is tuned for low false positives (fewer wrong alerts) rather than finding every possible issue. If you think it missed something, please open an issue.

Can I use it in CI/CD?

Yes! Use --json flag for machine-readable output:

diffray review --json --severity critical,high

Exit code is non-zero if issues are found.

GitHub Actions example:

⚠️ Security Warning:

• Never commit ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN to git
• Always use GitHub Secrets for API keys in CI/CD
• For local development: use claude setup-token to generate CLAUDE_CODE_OAUTH_TOKEN

name: Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm install -g diffray @anthropic-ai/claude-code

      # Option 1: Use ANTHROPIC_API_KEY (recommended for CI/CD)
      - run: diffray review --base origin/${{ github.base_ref }} --json --severity critical,high
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      # Option 2: Use CLAUDE_CODE_OAUTH_TOKEN (get via: claude setup-token)
      # - run: diffray review --base origin/${{ github.base_ref }} --json --severity critical,high
      #   env:
      #     CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

How much does it cost?

The CLI is free, but uses Claude AI which has API costs. With Claude Code CLI, costs are typically $0.01-0.05 per review.

Get Results in Your PRs

Want automated reviews directly in GitHub Pull Requests?

Sign up at diffray.ai - connect your repo and get AI review comments on every PR automatically.

Development

# Clone the repo
git clone https://github.com/diffray/diffray.git
cd diffray

# Install dependencies
npm install

# Run in dev mode
npm run dev

# Run tests
npm test

# Build
npm run build

See CONTRIBUTING.md for detailed development guidelines.

License

MIT

Changelog · Contributing · Architecture