Diffray

https://github.com/strelov1/diffray
Admin
Free open-source multi-agent code review CLI tool that runs specialized AI agents to analyze code...
Tokens:22,753
Snippets:313
Trust Score:9.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### GitHub Actions CI/CD Setup

Source: https://github.com/strelov1/diffray/blob/main/README.md

A GitHub Actions workflow example for running Diffray code reviews on pull requests. It demonstrates checking out code, setting up Node.js, installing Diffray, and running the review command using environment secrets for API keys.

```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 }}
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/strelov1/diffray/blob/main/CONTRIBUTING.md

Clone the diffray repository, navigate into the directory, install dependencies, and link for local development. This setup is necessary before running any diffray commands.

```bash
git clone https://github.com/diffray/diffray.git
cd diffray
npm install
npm run link:local

diffray --help
```

--------------------------------

### Install OpenCode CLI

Source: https://github.com/strelov1/diffray/blob/main/README.md

Install the OpenCode CLI using a curl script.

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

--------------------------------

### Install Diffray CLI

Source: https://github.com/strelov1/diffray/blob/main/README.md

Install the diffray CLI tool globally using npm.

```bash
npm install -g diffray
```

--------------------------------

### Install Dependencies

Source: https://github.com/strelov1/diffray/blob/main/README.md

Installs the necessary Node.js dependencies for the Diffray project. This command should be run after cloning the repository.

```bash
npm install
```

--------------------------------

### Example Global Configuration

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

A sample `~/.diffray/config.json` file demonstrating user-wide settings, including rule extensions, executor configurations, and output formatting.

```json
{
  "extends": ["https://github.com/diffray/diffray-rules"],
  "executor": "claude-cli",
  "concurrency": 6,
  "executors": {
    "claude-cli": {
      "review": { "model": "sonnet", "concurrency": 6 },
      "validation": { "model": "opus", "timeout": 180, "batchSize": 10, "concurrency": 3 }
    }
  },
  "agents": {},
  "rules": {},
  "output": { "colorize": true, "verbose": false, "format": "terminal" }
}
```

--------------------------------

### Example Project Configuration

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

A sample `.diffray.json` file showing project-specific overrides for agents and rules. This configuration takes precedence over global settings.

```json
{
  "agents": {
    "security-scan": { "enabled": false },
    "bug-hunter": { "model": "haiku" }
  },
  "rules": {
    "code-security": { "enabled": false }
  }
}
```

--------------------------------

### Install Cursor Agent CLI

Source: https://github.com/strelov1/diffray/blob/main/README.md

Install the Cursor Agent CLI using a curl script.

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

--------------------------------

### Install Codex CLI

Source: https://github.com/strelov1/diffray/blob/main/README.md

Install the OpenAI Codex CLI tool globally using npm.

```bash
npm install -g @openai/codex
```

--------------------------------

### List Installed Extends

Source: https://github.com/strelov1/diffray/blob/main/README.md

Bash command to display a list of all currently installed Diffray extends. This helps in managing your shared configurations.

```bash
diffray extends list
```

--------------------------------

### Extends Configuration Example

Source: https://github.com/strelov1/diffray/blob/main/README.md

JSON configuration snippet demonstrating how to extend Diffray with rules and agents from a git repository. This promotes sharing and reusability of configurations.

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

--------------------------------

### Glob Pattern Matching Examples

Source: https://github.com/strelov1/diffray/blob/main/README.md

Illustrates common glob patterns used for matching files within Diffray rules.

```markdown
| 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 Workflow Configuration

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Demonstrates defining custom workflows in `.diffray.json` to run agents multiple times with different executors and models for review and validation stages.

```json
{
  "workflows": {
    "review": [
      {"executor": "claude-cli", "model": "sonnet"},
      {"executor": "claude-cli", "model": "opus"},
      {"executor": "opencode-cli", "model": "gpt-5-nano"}
    ],
    "validation": [
      {"executor": "claude-cli", "model": "opus"}
    ]
  }
}
```

--------------------------------

### Custom Agent with Frontmatter and Prompt

Source: https://github.com/strelov1/diffray/blob/main/docs/AGENTS.md

Example of a custom agent configuration including YAML frontmatter and a detailed system prompt for a TypeScript checker.

```markdown
---
name: typescript-checker
description: Analyzes TypeScript code for type safety issues
enabled: true
executor: claude-cli
---

You are a TypeScript expert specializing in type safety.

### Focus Areas
- Type inference issues
- Missing type annotations
- Use of `any` type
- Generic type usage

### Instructions
- Only report actual type safety issues
- Be concise and actionable

```

--------------------------------

### Project-Specific Diffray Configuration

Source: https://github.com/strelov1/diffray/blob/main/README.md

Example of a project-specific configuration file named .diffray.json. This allows for overrides of global settings on a per-project basis.

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

--------------------------------

### Diffray Configuration File Example

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

JSON configuration for Diffray, showing the active executor and detailed settings for multiple executors across different stages.

```json
{
  "executor": "claude-cli",
  "executors": {
    "claude-cli": {
      "review": { "model": "sonnet", "timeout": 120 },
      "validation": { "model": "opus", "timeout": 180 }
    },
    "cursor-agent-cli": {
      "review": { "model": "claude-3-5-sonnet" },
      "validation": { "model": "claude-3-opus" }
    }
  }
}
```

--------------------------------

### Install Extends from Git URL

Source: https://github.com/strelov1/diffray/blob/main/README.md

Bash command to install Diffray extends directly from a git repository URL. This command automatically adds the URL to the configuration.

```bash
diffray extends install https://github.com/owner/repo
```

--------------------------------

### Install Claude Code CLI

Source: https://github.com/strelov1/diffray/blob/main/README.md

Install the official Anthropic Claude Code CLI tool globally using npm.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Documentation Checker Rule Example

Source: https://github.com/strelov1/diffray/blob/main/README.md

Defines a rule to check documentation files for common issues like broken links and outdated examples.

```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
```

--------------------------------

### Example Diffray Configuration

Source: https://github.com/strelov1/diffray/blob/main/README.md

This JSON configuration file allows customization of Diffray's behavior, including file exclusion patterns, concurrency settings, agent-specific overrides, and executor configurations.

```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 }
    }
  }
}
```

--------------------------------

### CLI Executor Configuration Example

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

TypeScript configuration for a CLI executor, detailing the command, arguments, model, and timeout.

```typescript
{
  type: "cli",
  command: "claude",
  args: ["-p", "--output-format", "json"],
  model: "sonnet",
  timeout: 120
}
```

--------------------------------

### Load Executors

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

Imports and loads all available executors. This is a setup step before agents can be assigned to executors.

```typescript
import { loadExecutors } from "./executors";

// Load all executors
const executors = await loadExecutors();

```

--------------------------------

### Config Security Rule Example

Source: https://github.com/strelov1/diffray/blob/main/README.md

Defines a rule to check configuration files for exposed secrets. Includes patterns for common config file types.

```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
```

--------------------------------

### Use a Specific Executor

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Specify the AI execution tool to be used for running the agents. Ensure the executor is installed and configured.

```bash
diffray review --executor opencode-cli
```

--------------------------------

### Adding a New GitHub Integration Stage

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

Provides an example of how to create and integrate a new stage, 'GitHub Publish', into the pipeline. This demonstrates the extensibility of the stage-based architecture.

```typescript
// src/stages/github-publish.ts
export function createGitHubPublishStage(): Stage {
  return {
    id: "github-publish",
    name: "Publish to GitHub",
    enabled: true,
    execute: async (context) => {
      // Post issues as PR comments
      await postToGitHub(context.issues);
      return { success: true, ... };
    },
  };
}

// Add to BUILTIN_STAGES after validation

```

--------------------------------

### Rule File Header Example

Source: https://github.com/strelov1/diffray/blob/main/README.md

Defines a rule for detecting bugs in React frontend code. Specifies patterns to match and the agent to use.

```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
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/strelov1/diffray/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification. This standard helps in automating changelog generation and semantic versioning.

```bash
feat: add new feature
fix: fix a bug
docs: update documentation
refactor: refactor code without changing behavior
test: add or update tests
chore: maintenance tasks

Examples:
feat: add --exclude-agent flag for filtering agents
fix: handle empty diff gracefully
docs: add CI/CD example to README
refactor: simplify executor initialization
```

--------------------------------

### Displaying Issues in Diffray CLI

Source: https://github.com/strelov1/diffray/blob/main/docs/ISSUES.md

This is an example of the Diffray CLI output when issues are found. It shows the count of issues, files affected, and detailed information for each issue including severity, location, description, suggestion, agent, rule, and confidence.

```text
Found 3 issue(s) in 2 file(s)

src/example.ts (2 issue(s))

✗ HIGH 🐛 bug
src/example.ts:10-15

Variable 'x' is never used

The variable 'x' is declared but never used in the function.

→ Suggestion:
Remove the unused variable or use it in the function body.

Agent: bug-hunter
Rule: code-bugs
Confidence: 95%
────────────────────────────────────────────────────────────────────────────────

○ MEDIUM ✨ quality
src/example.ts:25

Missing error handling

The async function does not handle potential errors.

→ Suggestion:
Add try-catch block or .catch() handler.

Agent: bug-hunter
Rule: code-bugs, code-quality
Confidence: 80%
────────────────────────────────────────────────────────────────────────────────
```

--------------------------------

### React Quality Rule Example

Source: https://github.com/strelov1/diffray/blob/main/README.md

Defines a rule for quality checks on React components. Includes patterns and focuses on React best practices.

```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
```

--------------------------------

### Agent Definition Example

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

Defines a 'bug-hunter' agent, specifying its name, description, system prompt, enablement status, order, and the executor it should use.

```json
{
  "id": "bug-hunter",
  "name": "Bug Hunter",
  "description": "Detects bugs, logic errors and runtime issues",
  "systemPrompt": "You are a bug detection specialist focused on identifying logic errors...",
  "enabled": true,
  "order": 1,
  "executor": "claude-cli"
}
```

--------------------------------

### JSON Output Format for Issues

Source: https://github.com/strelov1/diffray/blob/main/docs/ISSUES.md

An example of how issues are represented in JSON format. This includes multiple issues with varying fields and details.

```json
[
  {
    "file": "src/example.ts",
    "lineStart": 10,
    "lineEnd": 15,
    "severity": "high",
    "category": "bug",
    "shortDescription": "Variable 'x' is never used",
    "fullDescription": "The variable 'x' is declared but never used",
    "suggestion": "Remove the unused variable",
    "agent": "bug-hunter",
    "rule": "code-bugs",
    "evidence": "const x = 10;",
    "confidence": 95
  },
  {
    "file": "src/utils.ts",
    "lineStart": 25,
    "lineEnd": 25,
    "severity": "medium",
    "category": "quality",
    "shortDescription": "Missing error handling",
    "fullDescription": "The async function does not handle potential errors",
    "suggestion": "Add try-catch block or .catch() handler",
    "agent": "bug-hunter",
    "rule": "code-bugs, code-quality",
    "confidence": 80
  }
]
```

--------------------------------

### Bug Hunter Agent Example

Source: https://github.com/strelov1/diffray/blob/main/docs/AGENTS.md

Markdown configuration for a 'bug-hunter' agent, specifying its role, focus areas, and instructions for identifying logic errors and runtime issues.

```markdown
---
name: bug-hunter
description: Detects bugs, logic errors and runtime issues
enabled: true
executor: claude-cli
---

You are a bug detection specialist focused on identifying logic errors and runtime issues.

**Focus Areas**:
- **Null/Undefined Safety**: Missing null checks, potential NPE
- **Logic Errors**: Incorrect conditionals, wrong operators, off-by-one errors
- **Edge Cases**: Empty arrays, boundary conditions
- **Async/Concurrency**: Race conditions, unhandled promise rejections

**Instructions**:
- ONLY report issues likely to cause runtime errors
- Focus on "will this crash or produce wrong results?"
- Provide evidence: what input will break it?

```

--------------------------------

### Run Diffray in Development Mode

Source: https://github.com/strelov1/diffray/blob/main/README.md

Starts the Diffray application in development mode, allowing for active coding and testing. This command is used during local development.

```bash
npm run dev
```

--------------------------------

### Security Scanner Agent Example

Source: https://github.com/strelov1/diffray/blob/main/docs/AGENTS.md

Markdown configuration for a 'security-scan' agent, detailing its purpose, focus areas like injection attacks and secrets, and quality standards for reporting findings.

```markdown
---
name: security-scan
description: Scans for security vulnerabilities
enabled: true
executor: claude-cli
---

You are a security engineer performing focused security audits.

**Focus Areas**:
- **Injection Attacks**: SQL, XSS, command injection
- **Authentication**: bypass, privilege escalation
- **Secrets**: hardcoded credentials, key exposure
- **Data Protection**: sensitive data exposure, PII leakage

**Quality Standards**:
- Only flag issues with high confidence of actual exploitability
- Every finding must have a concrete attack path

```

--------------------------------

### Example React Best Practices Agent

Source: https://github.com/strelov1/diffray/blob/main/README.md

A sample agent configuration focused on identifying common mistakes in React code. It checks for missing keys, useEffect dependencies, state mutations, and memory leaks.

```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
```

--------------------------------

### Custom Rule Definition Example

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

This Markdown snippet defines a custom rule for input validation using Zod schemas. It specifies patterns, the agent to use, and provides detailed rules and examples for flagging code.

```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.

## Rules

### ❌ Avoid:
- Manual `parseInt`, `parseFloat`, `isNaN` checks
- String splitting with manual array validation

### ✅ Use instead:
- Zod `.coerce.number()` for number parsing
- Zod `.refine()` for validation with clear errors
- Centralized schemas in `*-schema.ts` files

## Example

See `src/cli-schema.ts` for reference implementation.

## When to flag

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

## When NOT to flag

Don't flag existing Zod schemas or internal calculations.

```

--------------------------------

### LLM API Executor Configuration Example

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

TypeScript configuration for an LLM API executor, specifying the provider, model, API key, temperature, and maximum tokens.

```typescript
{
  type: "llm-api",
  provider: "cerebras",
  model: "llama-4-scout-17b-16e-instruct",
  apiKey: process.env.CEREBRAS_API_KEY,
  temperature: 0.7,
  maxTokens: 4096
}
```

--------------------------------

### Python Security Rule Example

Source: https://github.com/strelov1/diffray/blob/main/README.md

Defines a rule for security checks on Python files. Includes patterns and focuses on specific Python security issues.

```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
```

--------------------------------

### API Security Rule Example

Source: https://github.com/strelov1/diffray/blob/main/README.md

Defines a rule for security review of API endpoints. Includes patterns and focuses on common API security concerns.

```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
```

--------------------------------

### Force Re-clone All Extends

Source: https://github.com/strelov1/diffray/blob/main/README.md

Bash command to force a re-clone of all installed Diffray extends. Use this to ensure you have the latest versions of shared rules and agents.

```bash
diffray extends install --force
```

--------------------------------

### Example API Security Checker Agent

Source: https://github.com/strelov1/diffray/blob/main/README.md

A sample agent configuration for identifying security vulnerabilities in API code. It checks for missing authentication, SQL injection, rate limiting, and exposed secrets.

```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
```

--------------------------------

### Formatting Issues with Diffray API

Source: https://github.com/strelov1/diffray/blob/main/docs/ISSUES.md

These examples demonstrate how to format issue data using the Diffray API. You can format a single issue, all issues, or issues grouped by file, which is useful for CLI output.

```typescript
import { formatIssue, formatIssues, formatIssuesByFile } from "./issue-formatter";

// Format single issue
const formatted = formatIssue(issue, compact);

// Format all issues
const formatted = formatIssues(issues, compact);

// Format grouped by file (used for CLI output)
const formatted = formatIssuesByFile(issues);
```

--------------------------------

### CLI Override: OpenCode Executor with Specific Model

Source: https://github.com/strelov1/diffray/blob/main/README.md

Command to use the OpenCode executor with a specific model. This is an example of mixing executors and models for specialized tasks.

```bash
diffray review --executor opencode-cli --model opencode/gpt-5-nano
```

--------------------------------

### Example TypeScript Strict Checker Agent

Source: https://github.com/strelov1/diffray/blob/main/README.md

A sample agent configuration for enforcing strict TypeScript practices. It checks for the usage of 'any' type, unnecessary type assertions, missing null checks, and implicit 'any' types.

```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
```

--------------------------------

### Input Validation with Zod Rule Example

Source: https://github.com/strelov1/diffray/blob/main/README.md

Defines a rule to ensure all input validation uses Zod schemas for type safety. Includes patterns and guidance on avoiding manual validation.

```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).

```

--------------------------------

### Initialize Project Configuration

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Creates a new `.diffray.json` file in the current project directory. This file allows for project-specific overrides.

```bash
diffray config init
```

--------------------------------

### Build Project

Source: https://github.com/strelov1/diffray/blob/main/CONTRIBUTING.md

Compile the project into a distributable format. The output will be available in `dist/diffray.cjs`.

```bash
npm run build
```

--------------------------------

### Show Detailed Progress with Streaming

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Enable verbose output that streams results in real-time, providing detailed progress information during the review process.

```bash
diffray review --stream
```

--------------------------------

### Create Custom Agent Files

Source: https://github.com/strelov1/diffray/blob/main/docs/AGENTS.md

Commands to create new agent Markdown files in user or project directories.

```bash
# User-level agent (applies to all projects)
mkdir -p ~/.diffray/agents
touch ~/.diffray/agents/my-agent.md

# Or project-level agent
mkdir -p .diffray/agents
touch .diffray/agents/my-agent.md

```

--------------------------------

### Verify Agent Configuration

Source: https://github.com/strelov1/diffray/blob/main/docs/AGENTS.md

Command to list all configured agents to verify custom agents are loaded.

```bash
diffray agents list

```

--------------------------------

### Stage Configuration and Ordering

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

Demonstrates how stages are defined, ordered, and can be enabled or disabled via configuration. The order is crucial for pipeline execution.

```typescript
// stages order defined in getStages() function
const stages = [
  createLoadRulesStage(),      // must be first
  createMatchRulesStage(),     // needs rules
  createReviewStage(),         // needs matched rules
  createAggregateResultsStage(),
  createDeduplicationStage(),
  createValidationStage(),     // must be last
];

// User can enable/disable via config.stages
{ id: "deduplication", enabled: false }

```

--------------------------------

### Create a New Agent Configuration

Source: https://github.com/strelov1/diffray/blob/main/CONTRIBUTING.md

Define a new agent by creating a Markdown file in `src/defaults/agents/`. This file includes metadata and instructions for the agent.

```markdown
---
name: my-agent
description: What this agent checks for
enabled: true
order: 5
---

You are a code reviewer focused on [specific area].

## What to check:
1. ...
2. ...

## How to report:
- Use severity: critical, high, medium, low
- Be specific about file and line
```

--------------------------------

### List All Agents

Source: https://github.com/strelov1/diffray/blob/main/README.md

Displays a list of all configured agents, including their name, description, and enabled status. Useful for managing and verifying agents.

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

--------------------------------

### Run First Code Review

Source: https://github.com/strelov1/diffray/blob/main/README.md

Perform a code review on uncommitted changes in your project directory.

```bash
cd your-project
diffray review
```

--------------------------------

### Create Rule Directory

Source: https://github.com/strelov1/diffray/blob/main/README.md

Command to create the directory for storing user-defined Diffray rules.

```bash
mkdir -p ~/.diffray/rules
```

--------------------------------

### Show Agent Details

Source: https://github.com/strelov1/diffray/blob/main/README.md

Retrieves and displays the full configuration details for a specific agent. Use this to inspect a particular agent's rules and settings.

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

--------------------------------

### List Available Agents

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Display a list of all available code review agents configured for diffray.

```bash
diffray agents
```

--------------------------------

### Create Agent Directory

Source: https://github.com/strelov1/diffray/blob/main/README.md

Ensures the directory for storing agent configuration files exists. Use this before creating new agent files.

```bash
mkdir -p ~/.diffray/agents
```

--------------------------------

### Edit Project Configuration

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Opens the project's `.diffray.json` file in your default editor for modification. Use the --global flag to edit the user-wide configuration.

```bash
diffray config edit
```

```bash
diffray config edit --global
```

--------------------------------

### Show Merged Configuration

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Displays the currently active merged configuration. Use this to verify your settings.

```bash
diffray config show
```

--------------------------------

### Justification for Singletons in CLI

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

TypeScript comments explaining the rationale for using singletons in a CLI application, emphasizing the single-process, single-configuration context.

```typescript
// CLI runs once, does work, exits — no parallel pipelines
// One process = one configuration context
// Simpler than passing dependencies through 5+ call levels
// factory.reset() available for test isolation
```

--------------------------------

### List Available Rules

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Show all the code review rules that diffray can apply. This helps in understanding the scope of checks.

```bash
diffray rules
```

--------------------------------

### Example of Unintentional Side-Effect

Source: https://github.com/strelov1/diffray/blob/main/src/defaults/prompts/validation.md

This snippet illustrates a commit message and associated code description that suggests an unintentional side-effect (race condition) due to a focus on speed, without acknowledgment.

```text
Commit message: "Use finer-grained locking to speed things up"
Code: Lock only protects cache write, not entire operation
No TODO or comment acknowledging the race condition risk
Issue: "Race condition - multiple goroutines can build same index"
→ KEEP: Commit wanted speed, but likely didn't realize the race condition. No acknowledgment.
```

--------------------------------

### Run Tests

Source: https://github.com/strelov1/diffray/blob/main/CONTRIBUTING.md

Execute all tests, a specific test file, or run tests in watch mode for continuous feedback during development.

```bash
# Run all tests
npm test

# Run specific test file
npm test -- md-loader

# Watch mode
npm run test:watch
```

--------------------------------

### Rule Header Fields Explanation

Source: https://github.com/strelov1/diffray/blob/main/README.md

Explains the key fields within a Diffray rule file header: name, description, patterns, and agent.

```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
---

```

--------------------------------

### Clone Diffray Repository

Source: https://github.com/strelov1/diffray/blob/main/README.md

Clones the Diffray project repository from GitHub. This is the first step for local development.

```bash
git clone https://github.com/diffray/diffray.git
cd diffray
```

--------------------------------

### Test New Agent

Source: https://github.com/strelov1/diffray/blob/main/CONTRIBUTING.md

Run the CLI with the newly added agent to test its functionality. This command allows you to specify which agent to use for testing.

```bash
npm run dev -- --agent my-agent
```

--------------------------------

### Run Vitest Tests

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Commands to execute tests using the Vitest framework. Supports running all tests or specific ones, and watch mode.

```bash
npm test
npm test -- <name>
npm test:watch
```

--------------------------------

### Applying Executor Settings in Code

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

TypeScript code demonstrating how Diffray loads configuration and merges agent-specific settings with executor and stage settings.

```typescript
// src/agents.ts
const config = await loadConfig();
const currentExecutor = config.executor;
const executorConfig = config.executors[currentExecutor] || {};

return agents.map((agent) => {
  const stage = agent.stage || 'review';
  const stageSettings = executorConfig[stage] || {};

  return {
    ...agent,
    executor: agent.executor || currentExecutor,
    executorSettings: { ...stageSettings, ...agent.executorSettings },
  };
});
```

--------------------------------

### Build System Configuration

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Configuration for the esbuild build tool, located in `build.mjs`. It specifies the output file and how defaults are handled.

```javascript
// build.mjs (example structure, actual content not provided)
// Configures esbuild for bundling
// Output: dist/diffray.cjs
// Copies defaults from src/defaults/ to dist/defaults/
```

--------------------------------

### Review Specific Files

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Focus the review on changes within specified file paths. Multiple files can be comma-separated.

```bash
diffray review --files src/auth.ts
```

```bash
diffray review --files src/auth.ts,src/user.ts
```

--------------------------------

### Manage Diffray Agents

Source: https://github.com/strelov1/diffray/blob/main/docs/AGENTS.md

Commands for listing all agents and viewing details of a specific agent.

```bash
# List all agents
diffray agents

# Show agent details
diffray agents bug-hunter

```

--------------------------------

### Configure Diffray to Use OpenCode CLI

Source: https://github.com/strelov1/diffray/blob/main/README.md

Configure diffray to use the OpenCode CLI by editing the .diffray.json configuration file.

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

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

--------------------------------

### Show Rule Details

Source: https://github.com/strelov1/diffray/blob/main/README.md

Displays detailed information about a specific rule, such as 'code-bugs'. Use this to understand a rule's configuration and purpose.

```bash
diffray rules code-bugs
```

--------------------------------

### Pipeline Stages Directory Structure

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

Illustrates the file organization for the stage-based pipeline architecture. Each file represents a distinct stage in the processing flow.

```text
src/stages/
  index.ts              # Stage registry & ordering
  load-rules.ts         # Stage 1: Load rules from config
  match-rules.ts        # Stage 2: Match files to rules
  review.ts             # Stage 3: Run agents (main logic)
  aggregate-results.ts  # Stage 4: Combine results
  deduplication.ts      # Stage 5: Remove duplicates
  validation.ts         # Stage 6: Validate output

```

--------------------------------

### Test Rule File Matching

Source: https://github.com/strelov1/diffray/blob/main/README.md

Command to test which files match a specific rule, in this case, 'python-security' against files in the 'src/' directory.

```bash
diffray rules python-security --test src/
```

--------------------------------

### Run diffray CLI for Code Review

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Review uncommitted changes or the last commit if the working directory is clean. This is the default review command.

```bash
diffray review
```

--------------------------------

### Authorize OpenCode CLI

Source: https://github.com/strelov1/diffray/blob/main/README.md

Authorize the OpenCode CLI, which typically involves opening a browser.

```bash
opencode auth login
```

--------------------------------

### CLI Command Registration and Dispatch

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

Defines a command structure and demonstrates how to register and dispatch commands using a CommandRegistry. Ensure the CommandRegistry is instantiated and commands are registered before dispatching.

```typescript
// Define command
export const myCommand = createCommand({
  name: "my-command",
  description: "Does something",
  subcommands: [
    createSubcommand({
      name: "action",
      description: "Performs action",
      handler: async (args) => { /* ... */ },
    }),
  ],
});

// Register in cli.ts
const registry = new CommandRegistry();
registry.register(myCommand);
await registry.dispatch(commandName, subcommand, args);
```

--------------------------------

### Run CLI in Development Mode

Source: https://github.com/strelov1/diffray/blob/main/CONTRIBUTING.md

Execute the CLI directly using tsx for development without needing a build step. You can also pass arguments to the CLI.

```bash
npm run dev

# Or run with arguments
npm run dev -- --base main --stream
```

--------------------------------

### Diffray CLI Pipeline Statistics

Source: https://github.com/strelov1/diffray/blob/main/docs/ISSUES.md

This snippet shows the output from a successful Diffray CLI pipeline run, indicating completion time, agent success status, and a summary of the issues found.

```text
✓ Pipeline completed successfully in 109ms
■ 3/3 agents succeeded
■ 3 issue(s): 1 critical, 1 high, 1 medium
```

--------------------------------

### Configure Diffray to Use Cursor Agent

Source: https://github.com/strelov1/diffray/blob/main/README.md

Configure diffray to use the Cursor Agent CLI by editing the .diffray.json configuration file.

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

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

--------------------------------

### Common Diffray Review Commands

Source: https://github.com/strelov1/diffray/blob/main/README.md

A collection of common diffray commands for various review scenarios, including comparing branches, reviewing specific commits, filtering by files, severity, agents, and output formats.

```bash
# 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
```

--------------------------------

### Authorize Cursor Agent CLI

Source: https://github.com/strelov1/diffray/blob/main/README.md

Authorize the Cursor Agent CLI, which typically involves opening a browser.

```bash
cursor-agent
```

--------------------------------

### Viewing Current Executor Settings via CLI

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

Bash command to display the settings for the currently active executor.

```bash
# View current executor settings
diffray executors
```

--------------------------------

### Create Custom Agent Directory

Source: https://github.com/strelov1/diffray/blob/main/README.md

Creates the necessary directory structure for overriding built-in agents. This is part of the process for customizing agent behavior.

```bash
mkdir -p .diffray/agents
```

--------------------------------

### Pipeline vs. Direct Function Calls

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

Compares the benefits of a stage-based architecture over direct function calls, highlighting extensibility, configurability, and observability.

```typescript
// Could be simpler:
const rules = await loadRules();
const matched = matchRules(rules, diffs);
const results = await executeAgents(matched);
// ...

// But stages enable:
// 1. Add new stage by adding file (like executors)
// 2. Enable/disable stages via config
// 3. Reorder stages via config
// 4. Timing/logging per stage
// 5. Future: hooks before/after stages

```

--------------------------------

### Global Singletons in Diffray

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

TypeScript comments listing key global singletons used in Diffray for state management, such as executor registry, agent registry, and config cache.

```typescript
executors        // src/executors.ts - executor registry
agentRegistry    // src/agents/registry.ts - agent registry
configCache      // src/config.ts - config cache
```

--------------------------------

### Review Code Changes Against a Base Branch

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Compare current changes against a specified base branch, such as 'main'.

```bash
diffray review --base main
```

--------------------------------

### Output Review Results as JSON

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Format the review output as JSON, suitable for programmatic consumption in CI/CD pipelines or other automation scripts.

```bash
diffray review --json
```

--------------------------------

### CLI Override: Specific Executor and Model

Source: https://github.com/strelov1/diffray/blob/main/README.md

Command to specify a different executor and model for a review. This is useful when you need to use a particular executor's capabilities or models.

```bash
diffray review --executor cursor-agent-cli --model opus-4.5
```

--------------------------------

### Review Full File Content

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Analyze the entire content of specified files, ignoring git diffs. Useful for static analysis of specific files.

```bash
diffray review --files src/auth.ts --full
```

--------------------------------

### Configure Diffray to Use Codex CLI

Source: https://github.com/strelov1/diffray/blob/main/README.md

Configure diffray to use the Codex CLI by editing the .diffray.json configuration file.

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

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

--------------------------------

### Agent Execution Sequence Diagram

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Illustrates the parallel execution of multiple agents during the review stage, interacting with an executor.

```mermaid
sequenceDiagram
    participant Pipeline
    participant Review Stage
    participant Agent1 as general
    participant Agent2 as bug-hunter
    participant Agent3 as security-scan
    participant Executor as claude-cli

    Pipeline->>Review Stage: MatchedRule[]
    Review Stage->>Review Stage: Group by agent

    par Parallel Execution (concurrency: 6)
        Review Stage->>Agent1: Execute with files + diffs
        Agent1->>Executor: Run LLM
        Executor-->>Agent1: JSON issues
        Agent1-->>Review Stage: AgentResult

        Review Stage->>Agent2: Execute with files + diffs
        Agent2->>Executor: Run LLM
        Executor-->>Agent2: JSON issues
        Agent2-->>Review Stage: AgentResult

        Review Stage->>Agent3: Execute with files + diffs
        Agent3->>Executor: Run LLM
        Executor-->>Agent3: JSON issues
        Agent3-->>Review Stage: AgentResult
    end

    Review Stage->>Pipeline: AgentResult[]

```

--------------------------------

### Test Rule File Matching

Source: https://github.com/strelov1/diffray/blob/main/README.md

Tests which files a specific rule matches. This is useful for debugging rule configurations and ensuring they apply to the intended files.

```bash
diffray rules code-bugs --test src/
```

--------------------------------

### Define Custom Agent Configuration

Source: https://github.com/strelov1/diffray/blob/main/README.md

Defines a custom agent configuration in a Markdown file. This allows for completely custom instructions and settings for agents like 'bug-hunter'.

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

Your completely custom instructions here...
```

--------------------------------

### CLI Override: Fast Review with Skip Validation

Source: https://github.com/strelov1/diffray/blob/main/README.md

Command for a fast review using a specific model and skipping the validation stage. Ideal for processing large changesets quickly.

```bash
diffray review --model haiku --skip-validation
```

--------------------------------

### Agent Definition with YAML Frontmatter

Source: https://github.com/strelov1/diffray/blob/main/docs/AGENTS.md

Defines an agent with its name, description, and executor. The body serves as the agent's system prompt.

```markdown
---
name: bug-hunter
description: Detects bugs, logic errors and runtime issues
enabled: true
executor: claude-cli
---

You are a bug detection specialist focused on identifying logic errors.

### Focus Areas
- Null/undefined safety
- Logic errors and incorrect conditionals
- Edge cases and boundary conditions

```

--------------------------------

### Create a New Executor

Source: https://github.com/strelov1/diffray/blob/main/CONTRIBUTING.md

Implement a new executor by creating a TypeScript file in `src/executors/`. This involves defining the executor's name, type, and an execute method.

```typescript
import { Executor, ExecutionContext, ExecutionResult } from './types';

export function createMyExecutor(): Executor {
  return {
    name: 'my-executor',
    type: 'cli', // or 'llm-api'
    enabled: true,

    async execute(context: ExecutionContext): Promise<ExecutionResult> {
      // Implementation
    },

    getInfo() {
      return { name: 'my-executor', type: 'cli' };
    }
  };
}
```

--------------------------------

### When Singletons Are Problematic

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

TypeScript comments outlining scenarios where the use of global singletons would be problematic, such as in libraries with multiple instances or servers handling parallel requests.

```typescript
// Library with multiple independent instances
// Server handling parallel requests with different configs
// Plugin architecture requiring sandboxed execution
```

--------------------------------

### Run Diffray Tests

Source: https://github.com/strelov1/diffray/blob/main/README.md

Executes the test suite for the Diffray project. This is crucial for ensuring code changes do not introduce regressions.

```bash
npm test
```

--------------------------------

### Agent Header Fields Explanation

Source: https://github.com/strelov1/diffray/blob/main/README.md

Explains the purpose of key-value pairs in an agent's YAML header. These fields control the agent's behavior and identification.

```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)
---
```

--------------------------------

### Create a New Stage

Source: https://github.com/strelov1/diffray/blob/main/CONTRIBUTING.md

Define a new stage for the pipeline by creating a TypeScript file in `src/stages/`. This includes defining an ID, name, and an execute method for the stage.

```typescript
import { Stage, PipelineContext, StageResult } from '../types';

export function createMyStage(): Stage {
  return {
    id: 'my-stage',
    name: 'My Stage',
    enabled: true,

    async execute(context: PipelineContext): Promise<StageResult> {
      // Implementation
      return { success: true };
    }
  };
}
```

--------------------------------

### Agent Execution Flow Diagram

Source: https://github.com/strelov1/diffray/blob/main/docs/ARCHITECTURE.md

Visualizes the sequence of operations during agent execution, including parallel processing by different agents and interaction with an executor.

```mermaid
sequenceDiagram
    participant Pipeline
    participant Review as Review Stage
    participant A1 as general
    participant A2 as bug-hunter
    participant A3 as security
    participant Executor as claude-cli

    Pipeline->>Review: MatchedRule[]
    Review->>Review: Group by agent

    par Parallel Execution
        Review->>A1: files + diffs
        A1->>Executor: Run LLM
        Executor-->>A1: JSON issues
        A1-->>Review: AgentResult

        Review->>A2: files + diffs
        A2->>Executor: Run LLM
        Executor-->>A2: JSON issues
        A2-->>Review: AgentResult

        Review->>A3: files + diffs
        A3->>Executor: Run LLM
        Executor-->>A3: JSON issues
        A3-->>Review: AgentResult
    end

    Review->>Pipeline: AgentResult[]

```

--------------------------------

### Disable Rule via Configuration

Source: https://github.com/strelov1/diffray/blob/main/README.md

Shows how to disable a rule, like 'code-performance', by adding a configuration to the .diffray.json file. This allows customization of which rules are active.

```json
{
  "rules": {
    "code-performance": { "enabled": false }
  }
}
```

--------------------------------

### Define Custom Agent Rules (Markdown)

Source: https://github.com/strelov1/diffray/blob/main/README.md

Defines a custom agent's name, description, and enabled status. This format is used for agent configuration files.

```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
```

--------------------------------

### Markdown Frontmatter Parsing

Source: https://github.com/strelov1/diffray/blob/main/CLAUDE.md

Illustrates the use of custom regex for parsing Markdown frontmatter, as implemented in `src/agents/md-loader.ts` and `src/md-loader.ts`. Agents reference prompts via relative paths.

```javascript
// src/md-loader.ts (example concept)
// Loads markdown files and parses frontmatter
// Agents reference prompts like: "../prompts/output-format.md"
```
Tokens:
Raw