Give It to Your Agent.

The Gate

Your agent compares the version you trust against the incoming one before it installs.

vigi diff --old <trusted> --new <incoming> --json

• Exit code 0: nothing gained a capability. The agent proceeds.
• Exit code 1: a file gained a capability. The agent stops and reads the findings.
• The JSON record is the only thing written to stdout, so it stays clean to parse.

What It Hands Back

One record per comparison. Each finding shows the file and the capability it gained.

{
  "format": "vigi-diff",
  "format_version": 1,
  "target": "left-pad-1.4.0",
  "files_now": 3,
  "files_before": 3,
  "verdict": "HEADS UP",
  "exit_code": 1,
  "findings": [
    {
      "path": "index.js",
      "new": false,
      "loudness": "high",
      "size": 512,
      "capability_gained": ["can run other programs", "can reach the network"],
      "capability_gained_raw": ["exec", "fetch"],
      "talks_to": ["evil.example"]
    }
  ]
}

verdict is OK or HEADS UP. loudness is high, medium, or low. Read capability_gained_raw in code, capability_gained for a person.

As a Hook

One command brackets an npm install with a snapshot before and a check after.

vigi hook npm

Or gate it yourself in a harness, and act on the exit code.

vigi diff --old ./prev --new ./incoming --json > vigi.json || echo "review vigi.json before trusting this update"

In Your Agent's Instructions

Drop one rule into AGENTS.md or CLAUDE.md. The agent runs the gate on its own.

Before you install or upgrade any dependency, run:

  vigi diff --old <current version> --new <incoming version> --json

If the exit code is not 0, do not proceed. Show the findings and let a person decide.
Only 0 is a pass. 1 means a file gained a capability. 3 means there was no trusted
copy to compare against, and 2 and 4 mean the run checked nothing.
If many projects take the same update, check that package version once. Use the
result for every project that takes it.

When vigi prints "version X is available", update vigi with the tool that
installed it: brew upgrade vigihq/vigi/vigi, or npm install -g vigihq@latest.

The One Limit

Vigilance compares two versions, so it needs a version you already trust. On a brand-new package there is nothing to diff, so run the gate on updates. For a first install, vigi profile --artifact <path> still lists the capabilities a file holds.