AI-powered code review CLI for git changes
npm install diffraydiffrayFree open-source multi-agent code review |
> 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.

---
- Quick Start
- Prerequisites
- How It Works
- Configuration
- Creating Custom Agents
- Creating Custom Rules
- Overriding Agents and Rules
- FAQ
- Development
---
``bash`Install globally from npm
npm install -g diffray
`bashGo to your project
cd your-project
That's it! diffray will analyze your changes and show any issues found.
$3
`bash
Review uncommitted changes, or last commit if clean
diffray reviewReview changes compared to main branch
diffray review --base mainReview last 3 commits
diffray review --base HEAD~3Review specific file(s) - only git changes in these files
diffray review --files src/auth.ts
diffray review --files src/auth.ts,src/user.tsReview entire file content (without git diff)
diffray review --files src/auth.ts --fullShow only critical and high severity issues
diffray review --severity critical,highRun only specific agent
diffray review --agent bug-hunterOutput as JSON (for CI/CD pipelines)
diffray review --jsonShow detailed progress
diffray review --streamList 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:
$3
Claude Code is an official Anthropic CLI tool with agentic capabilities.
`bash
Install
npm install -g @anthropic-ai/claude-codeAuthorize (opens browser for OAuth)
claude auth login
`$3
If you use Cursor IDE, you can use its agent CLI instead:
`bash
Install
curl https://cursor.com/install -fsS | bashAuthorize (opens browser)
cursor-agent
`Then switch diffray to use it:
`bash
Via config
diffray config init
Edit .diffray.json and add: "executor": "cursor-agent-cli"
Or per-run
diffray review --executor cursor-agent-cli
`$3
Modern AI CLI with support for multiple model providers:
`bash
Install
curl https://opencode.ai/install -fsS | bashAuthorize (opens browser)
opencode auth login
`Then switch diffray to use it:
`bash
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.
$3
OpenAI Codex CLI for local code review:
`bash
Install
npm install -g @openai/codex
`Then switch diffray to use it:
`bash
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
$3
`
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Git Diffs │───▶│ Match Rules │───▶│ Run Agents │───▶│ Deduplicate│
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Agent 1 │ │ Validate │
│ Agent 2 │ │ (filter │
│ Agent 3 │ │ false +) │
│ ... │ └─────────────┘
└─────────────┘ │
▼
┌─────────────┐
│ Report │
└─────────────┘
`$3
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:$3
`json
{
"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 }
}
}
}
`$3
| 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. | Override agent settings (enabled, model, timeout) |
| rules. | Override rule settings (enabled, agent) |
| executors. | Per-executor, per-stage settings (model, timeout, concurrency, batchSize) |$3
#### 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):
`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):
`json
{
"executors": {
"claude-cli": {
"review": { "model": "haiku" },
"validation": { "model": "sonnet" }
}
},
"agents": {
"security-scan": { "model": "sonnet", "timeout": 180 },
"consistency-check": { "enabled": false }
}
}
`#### CLI Override Examples
`bash
Override model for all agents
diffray review --model sonnetUse different executor with specific model
diffray review --executor cursor-agent-cli --model opus-4.5Fast review with Haiku for all agents
diffray review --model haiku --skip-validationSecurity scan with Opus (most thorough)
diffray review --agent security-scan --model opusMixed: use OpenCode with specific model
diffray review --executor opencode-cli --model opencode/gpt-5-nanoOverride 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.$3
Share agents and rules across projects by loading them from any git repository:
`json
{
"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
- git@github.com:owner/repo.git — SSH formatExtends commands:
`bash
Install extends from config
diffray extends installInstall specific URL (auto-adds to config)
diffray extends install https://github.com/owner/repoForce re-clone all extends
diffray extends install --forceList installed extends
diffray extends listRemove an extend
diffray extends remove https://github.com/owner/repo
`Agents/rules from extends have lower priority than local ones.
$3
`bash
Create config file
diffray config initEdit config in your editor
diffray config editShow 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.
$3
| Location | When to use |
|----------|-------------|
|
~/.diffray/agents/ | Your personal agents (work in all projects) |
| .diffray/agents/ | Project-specific agents (share with team via git) |$3
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)$3
Step 1. Create the folder (if it doesn't exist):
`bash
mkdir -p ~/.diffray/agents
`Step 2. Create a new file
~/.diffray/agents/my-rules.md:`markdown
---
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:
`bash
diffray agents
`You should see
my-rules in the list.Step 4. Run a review - your agent will now analyze your code!
`bash
diffray review
`$3
`yaml
---
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)
---
`$3
#### React best practices checker
`markdown
---
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
`markdown
---
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
`markdown
---
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
`$3
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
$3
`bash
List all agents (shows name, description, enabled status)
diffray agentsShow full details of an agent
diffray agents bug-hunterDisable an agent via config (without deleting the file)
Add to .diffray.json:
{
"agents": {
"my-rules": { "enabled": false }
}
}
`$3
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 headerCreating Custom Rules
Rules connect agents to files. They tell diffray: "Run this agent on these files".
$3
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$3
| Location | When to use |
|----------|-------------|
|
~/.diffray/rules/ | Your personal rules (work in all projects) |
| .diffray/rules/ | Project-specific rules (share with team via git) |$3
Rules are also Markdown files with a header:
`markdown
---
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
`$3
Step 1. Create the folder:
`bash
mkdir -p ~/.diffray/rules
`Step 2. Create
~/.diffray/rules/python-security.md:`markdown
---
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:
`bash
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:
`bash
diffray rules python-security --test src/
`$3
`yaml
---
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
---
`$3
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 !) |$3
#### Backend API security
`markdown
---
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
`markdown
---
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
`markdown
---
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
`markdown
---
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
`markdown
---
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
`$3
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 |$3
`bash
List all rules
diffray rulesShow rule details
diffray rules code-bugsTest 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 }
}
}
`$3
| | 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)
$3
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 rootAgent not running on expected files?
- Make sure rule's
agent field matches an existing agent name
- Check that both rule and agent have enabled: trueOverriding 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 defaultsExample: To replace the built-in
bug-hunter agent:`bash
mkdir -p .diffray/agents
`Create
.diffray/agents/bug-hunter.md:`markdown
---
name: bug-hunter
description: My custom bug hunter
enabled: true
---Your completely custom instructions here...
`FAQ
$3
diffray uses Claude AI which takes time to analyze code properly. Typical review takes 10-30 seconds. For faster (but less accurate) reviews, use:
`bash
diffray review --skip-validation
`$3
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.
$3
Yes! Use
--json flag for machine-readable output:`bash
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`yaml
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 }}
`$3
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
`bash
Clone the repo
git clone https://github.com/diffray/diffray.git
cd diffrayInstall dependencies
npm installRun in dev mode
npm run devRun tests
npm testBuild
npm run build
``See CONTRIBUTING.md for detailed development guidelines.
MIT
---