Getting Started

Get DiffPulse running in your repository in under two minutes. You'll scaffold a policy file, verify your environment, and evaluate a feature branch diff.

Prerequisites

Node.js 20 or later
Git repository with at least one commit

Install

Add DiffPulse as a dev dependency:

npm install -D @diffpulse/cli

Or run commands directly with npx — no install required.

Initialize

Scaffold your policy file, GitHub workflow, and verify setup in one command:

npx @diffpulse/cli init

This creates:

.diffpulse/policy.yaml — check and threshold configuration
.github/workflows/diffpulse.yml — CI workflow (uses npx @diffpulse/cli)

If package.json exists, init also adds a devDependency and diffpulse:check npm script, then runs policy validation and doctor.

Verify your environment

Init runs doctor automatically. You can rerun it any time:

npx @diffpulse/cli doctor

Doctor checks Node.js version, git availability, repository status, and policy file validity.

Run your first check

DiffPulse compares commits between a base ref and HEAD. For meaningful results, work on a feature branch:

git checkout -b my-change
# ... edit files, commit ...
npx @diffpulse/cli check
# or: diffp check

On your default branch with no divergence, check may report zero changed files. Use a feature branch or pass --base <ref>.

Validate your policy

npx @diffpulse/cli config validate

Use with Cursor / MCP

Connect DiffPulse to your editor's AI via the MCP server. DiffPulse returns deterministic JSON — it does not call OpenAI or Anthropic; your editor's model interprets the results.

{
  "mcpServers": {
    "diffpulse": {
      "command": "npx",
      "args": ["-y", "@diffpulse/mcp"]
    }
  }
}

See MCP Setup for tool reference and workflow examples.