Documentation

1. Installation

The DiffSwarm CLI is available via Homebrew for macOS and Linux. The install includes the public diffswarm wrapper, the terminal UI, and the internal diffswarm-rs backend.

Copy# New install
$ brew install bro4all/diffswarm/diffswarm

# Upgrade an existing install
$ brew upgrade diffswarm

# Bun is installed as a dependency for the terminal app runtime

2. Engine Setup (BYOK)

DiffSwarm requires a local AI engine to function. We support Anthropic Claude Code and OpenAI Codex CLI. You must install and authenticate at least one.

Copy# Anthropic Claude Code (Recommended)
$ npm install -g @anthropic-ai/claude-code
$ claude setup-token

# OpenAI Codex
$ npm install -g @openai/codex
$ codex login

3. DiffSwarm Login

DiffSwarm is a paid CLI orchestration tool. You need to authenticate your active subscription.

Copy$ diffswarm login
# Follow the prompt. Enter the email used during Stripe checkout.
# A one-time code will be sent to your inbox.

Running a Bug Hunt

Bug Hunt mode keeps the default view centered on changed files, surfaced issues, and live activity. You follow the repo and inspect exact code or diff evidence when something looks worth fixing.

Copy# Review a remote GitHub PR (Outputs to console & markdown)
$ diffswarm pr https://github.com/ORG/REPO/pull/123 --out report.md

# Review a local diff file
$ diffswarm diff path/to/changes.diff --out report.md

# Post verified findings directly as a PR comment
$ diffswarm pr https://github.com/ORG/REPO/pull/123 --comment

# Dry-run smoke test (No LLM calls, fast check)
$ diffswarm diff tests/fixtures/sample.diff --dry-run

Security Audit Mode

Security mode applies the same repo-first workflow to auth, input handling, config, and crypto changes so security findings stay readable and actionable.

Copy# Standard security review
$ diffswarm security https://github.com/ORG/REPO/pull/123 --out sec_report.md

# Focus on specific OWASP categories and minimum severity
$ diffswarm security https://github.com/ORG/REPO/pull/123 --owasp-focus "A01,A03" --min-severity high

Profiles & Budgets

DiffSwarm auto-tunes review depth and runtime based on PR risk. You can still override that with profiles and explicit budget caps.

Bug Hunt Profiles

Security Profiles

CLI Reference

Copy# Global Flags
--engine codex|claude         # AI engine to use (default: codex)
--model MODEL                 # Override specific model
--out FILE                    # Write Markdown report
--json FILE                   # Write JSON machine-readable findings
--comment                     # Post findings to PR
--dry-run                     # Skip actual LLM calls

# Bug Hunt Tuning
--profile cheap|balanced|thorough
	--token-budget N              # Planning target (use with --strict-budget to constrain extra review work)
	--time-budget-minutes N       # Cap wall-time
	--strict-budget               # Enforce budget best-effort by limiting extra review work
	--allow-expensive-rerun       # Required for large/repeated reruns
	--fleet-size N                # Override parallel review width

# Security Tuning
--security-profile quick|standard|thorough
--owasp-focus CATEGORIES      # Comma-separated (e.g. "A01,A03")
--min-severity low|medium|high|critical

Recovery

Use reconciliation when a run is already semantically complete and only needs final artifacts written. Use resume when work is still in progress and you want to continue from the saved scheduler checkpoint.

Copy$ diffswarm reconcile-run --run-dir runs/example-run

Copy$ diffswarm resume-run --run-dir runs/example-run

resume-run continues the saved run configuration as-is. In v1 it does not accept engine, model, or budget overrides.