Get started

Install the gate. Break something. Watch it catch it.

Polygraph doesn't review — it verifies: aim it at any stateful code, it walks every reachable state and hands back the exact steps that break your rules. A repro, not a hunch. This page takes you from zero to that moment in three demos, on one small machine.

1 · Install

Polygraph is a Claude Code plugin, and the repo is its own marketplace.

In the terminal

# inside Claude Code
/plugin marketplace add cognitive-fab/polygraph
/plugin install polygraph@polygraph

Update later with /plugin marketplace update polygraph. Or clone directly into ~/.claude/plugins/polygraph.

In the VS Code extension

Type /plugin and pick Manage plugins, then:

  1. Marketplaces tab → paste https://github.com/cognitive-fab/polygraph and hit Add
  2. Back on the Plugins tab → polygraph appears under AvailableInstall
  3. Restart Claude Code when the banner asks
VS Code prompt box — typing /plugin surfaces the Manage plugins command VS Code Manage Plugins — Marketplaces tab with the polygraph marketplace added VS Code Manage Plugins — Plugins tab with polygraph ready to install click to enlarge

One gotcha: VS Code may not inherit your shell's ANTHROPIC_API_KEY — set it in the env block of ~/.claude/settings.json, which both surfaces share.

Requirements: Node ≥ 20. No npm install for the core loop — the SAM runtime is vendored. Replay, model checking, and the version gate run without any API key; only spec generation and code authoring call a model.

2 · Meet the machine: DAAO

The demo repo is a show-and-tell on one small machine — a Dual-Authorization Action Order: an order needs two distinct approvers inside a time window before it can fire two real-world effects (transmit, execute), each exactly once.

Small, but it's the shape of every approval, checkout, and payment flow — and the two-person rule is exactly the kind of property that hides from code review. The machine has 28 reachable states; the gate visits all of them.

git clone https://github.com/cognitive-fab/polygraph-demo-daao

3 · Three demos, each one prompt

Demos 1 and 3 are deterministic and need no key; Demo 2 authors code, so it needs an ANTHROPIC_API_KEY.

Demo 1 — Find the bug the review would miss

deterministic · no key

The code under test is AI-generated. Delete the one guard that stops a redelivered approval from counting twice — the classic two-person bug — and point Polygraph at it. It walks all 28 reachable states and hands back the shortest path to disaster:

submit(alice) → approve(bob) → approve(bob) → APPROVED, approvers=[bob,bob], distinct=1

That failing path is the reproduction — paste it into a test. The clean build passes the identical gate. No test was written; the gate found the bug class regardless of who wrote the code.

promptTake the DAAO machine in daao/verify/, make a copy with the distinct-approver guard removed, and run the Polygraph gate on both. Show me it clears the clean build and, on the buggy one, returns the shortest path to a state that violates the two-person rule — the reproduction — without me writing a test.
Honest note. The model actually wrote the two-person logic correctly — the more interesting result. The bug was planted to show the catch. The point isn't "AI writes bad code"; it's that the gate finds this bug class in CI, not in an incident channel.

Demo 2 — Author code that's verifiable from the first line

polygen · needs API key

Turn it around. One paragraph of English → a machine born with a contract, its invariants, and a regression corpus, model-checked before you ever see it. A frontier model wrote the whole DAAO and converged on the first try — for $1.81 of model spend.

promptAuthor a verifiable dual-authorization action-order machine with polygen from this description: [the states, the two-distinct-approver rule, the in-window exactly-once effects, recall, and expiry]. Model-check it against its own invariants, self-repair any reachable violation, and give me the contract, invariants, and a regression corpus.

Demo 3 — Evolve a live system without breaking it

polyvers · no key

Change one rule — two approvers to three — and the gate replays it against the orders already in flight under the old rule. It blocks the deploy, naming the four live orders the new rule would strand and the exact path by which one still reaches execute. Before you ship, not after in an incident.

promptThe DAAO machine in daao/verify/ is verified under a two-approver rule. Tighten it to three, build in-flight fleet snapshots (orders already approved or released under the old rule), and run polyvers to version-gate the change against them. If it's unsafe, block it and name which in-flight orders break and the path by which one reaches execute.

Or run the keyless path in one command

# Demo 1 (the catch) + Demo 3 (the version gate) + liveness + differential
bash daao/run_demo.sh

Dig deeper

Disclosure. Polygraph is experimental, not peer-reviewed technology — a consistency check, not a proof, over the finite (action, data) domains the contract declares. Every finding is a lead to investigate by hand. Results above verified on Polygraph v6.0.0 and reproduce bit-for-bit.