diffcheck

AI-powered code review CLI using opencode with parallel focused agents.

Overview

Runs parallel AI agents against your git diff, each focused on a different concern. Agents are auto-discovered from Markdown files in the agents/ directory — just drop in a new .md file and it runs on the next review.

Built-in agents:

Agent	Focus
Security	Vulnerabilities, auth issues, injection risks
Correctness	Logic errors, bugs, edge cases
Design	Patterns, architecture, code organization
Readability	Code clarity, naming, complexity
Tests	Coverage, quality, edge cases
Reliability	Error handling, edge cases, robustness

Issues are filtered by confidence score (default 80%) to reduce false positives.

Prerequisites

• Node.js >= 20 and npm
• opencode CLI installed and authenticated
• Git repository

Install prerequisites

# Install opencode
npm install -g opencode-ai

# Authenticate with a provider (Optional - only needed if you have your own api key)
opencode auth login

See Opencode Docs for alternative installation methods.

Installation

npm install -g diffcheck

Or run without installing:

npx diffcheck

Usage

# Review staged changes (falls back to diff vs main)
diffcheck

# Use a specific model
diffcheck --model anthropic/claude-sonnet-4-20250514
diffcheck --model ollama/qwen3:8b

# Compare against a different base branch
diffcheck --base develop

# Lower confidence threshold to see more issues
diffcheck --confidence 60

# Output as JSON (useful for CI artifacts)
diffcheck --format json

# Fail if issues found (for CI/CD)
diffcheck --fail-on-issues

# Interactively change the default model
diffcheck --set-model

# Show help
diffcheck --help

Options

Option	Short	Default	Description
--model	-m	opencode/big-pickle	LLM model to use
--base	-b	main	Base branch for diff comparison
--confidence	-c	80	Minimum confidence threshold (0–100)
--verbose	-v	false	Show detailed agent outputs for debugging
--deep		false	Deep mode: agents use tools to explore the codebase (slower)
--local-only		false	Review only local changes (staged + unstaged + untracked)
--fail-on-issues		false	Exit with non-zero code when issues found (for CI/CD)
--set-model			Interactively select and save the default model
--save-defaults			Save current --model, --base, --confidence as defaults
--format		terminal	Output format: terminal, json, markdown
--help	-h		Show help message

How It Works

1. Get diff — checks staged changes (git diff --staged), falls back to branch comparison (git diff <base>...HEAD)
2. Spawn agents — discovers all .md files in agents/ and runs them in parallel via opencode
3. Collect results — each agent outputs JSON with issues and confidence scores
4. Aggregate — merges all issues, filters by confidence threshold, removes duplicates
5. Synthesize — runs a final pass to validate and de-duplicate issues
6. Display — formats results as terminal output, JSON, or Markdown

Output Example

  ╔═════════════════════════════════════════════╗
  ║            AGENT EXECUTION SUMMARY          ║
  ╚═════════════════════════════════════════════╝

  Total agents:       6
  Successful:         6
  Failed:             0
  Timed out:          0

  ──────────────────────────────────────────────

  security       ✓ OK     2 issues   18s
  correctness    ✓ OK     1 issue    22s
  design         ✓ OK     0 issues   15s
  readability    ✓ OK     0 issues   17s
  tests          ✓ OK     1 issue    20s
  reliability    ✓ OK     0 issues   16s

══════════════════════════════════════════════════
                  CODE REVIEW SUMMARY
══════════════════════════════════════════════════

Found 3 issue(s) (filtered from 4 candidates, threshold: 80%)

By Severity:
  HIGH:   1
  MEDIUM: 2

──────────────────────────────────────────────────

1. [SECURITY] SQL injection risk — raw user input in query
   Severity: HIGH | Confidence: 92%
   → src/controllers/UserController.php:45

2. [LOGIC] Null pointer possible — variable used before check
   Severity: MEDIUM | Confidence: 85%
   → src/services/OrderService.php:123

3. [TESTS] Missing error case — no test for invalid input
   Severity: MEDIUM | Confidence: 82%
   → tests/UserService.test.ts:89

CI/CD Integration

GitHub Actions

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install diffcheck
        run: npm install -g diffcheck
      - name: Run code review
        run: diffcheck --format json > review.json
        continue-on-error: true
      - name: Upload results
        uses: actions/upload-artifact@v4
        with:
          name: code-review
          path: review.json
      - name: Fail on issues
        run: diffcheck --fail-on-issues

GitLab CI

code_review:
  stage: test
  script:
    - npm install -g diffcheck
    - diffcheck --format json > review.json
  artifacts:
    paths:
      - review.json
    when: always
  allow_failure: true

Configuration

Using local models (Ollama)

For fully self-hosted reviews with no external API calls:

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull qwen3:8b

# Run code review
diffcheck --model ollama/qwen3:8b

See Ollama for installation instructions.

Saving defaults

Interactively pick a default model:

diffcheck --set-model

Or save any combination of model, base branch, and confidence threshold:

diffcheck --model ollama/qwen3:8b --base develop --confidence 70 --save-defaults

Saved defaults are stored in .code-review.json and can always be overridden per-run with explicit flags.

File Structure

diffcheck/
├── agents/               # Agent prompts — each .md file = one agent (auto-discovered)
│   ├── security.md
│   ├── correctness.md
│   ├── design.md
│   ├── readability.md
│   ├── tests.md
│   ├── reliability.md
│   ├── synthesizer.md    # Final deduplication & validation
│   └── *.md              # Drop any new .md file here to add an agent
├── src/                  # TypeScript source (dist/cli.js is the bin entry point)
├── test/                 # Unit tests
├── .code-review.json     # Saved defaults (model, base branch, confidence)
└── package.json

Customization

Adding a new agent

Agents are auto-discovered from agents/*.md — no code changes required. To add one:

1. Create a new .md file in agents/:

   touch agents/accessibility.md

2. The agent output must follow this JSON schema:

   {
     "issues": [
       {
         "type": "ACCESSIBILITY",
         "severity": "HIGH | MEDIUM | LOW",
         "title": "Brief description",
         "file": "path/to/file.ext",
         "line": 123,
         "evidence": "What you found and why it matters",
         "impact": "What could go wrong",
         "recommendation": "How to fix it",
         "confidence": 85
       }
     ]
   }

3. That's it. Run diffcheck and the new agent runs in parallel with all the others.

Removing an agent

Delete or move the .md file out of agents/. It will no longer run.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.

Acknowledgments

Built with:

• opencode — LLM execution framework
• Node.js — Runtime
• TypeScript — Type safety

---

Made with ❤️ for better code reviews