Skip to main content
plugin

vstack — Claude Code plugin: verification and installation

The vstack Claude Code plugin gives coding agents a formal workflow for checking state-machine models without weakening their safety properties. Run it on a module and a stated safety requirement.

MIT ★ 89 updated 2026-11-16

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hao-ai-lab/vstack
/plugin install vstack@hao-ai-lab-vstack
Open on GitHub

What vstack does

vstack coordinates formal checks for models and critical state machines. It separates coordinator, worker, and red-team roles, while hashes lock safety properties and theorem signatures. Model variables and actions are linked to specific code lines and a commit.

Its gates check that models expose historical bugs, pass after a fix, and fail again when guards are removed. A reported finding must also reproduce on a real engine alongside a passing control. The vstack setup command checks Java, TLC, and Z3, then installs the skills, agents, and linked documentation.

What it helps with

  • check state-machine invariants
  • find timeout and lifecycle bugs
  • catch weakened properties and missing guards
  • map a model to code lines and a commit

Example prompts for the agent

  • Check that the lease manager never reuses a page while it is still in flight after a timeout.
  • Formally verify this module's state machine against the stated safety property.
  • Test the model against historical bugs, then rerun it after the fix.

How to install vstack

Plugin marketplace

/plugin marketplace add hao-ai-lab/vstack
/plugin install vstack@hao-ai-lab-vstack

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about vstack

How do I install vstack in Claude Code?

Run /plugin marketplace add hao-ai-lab/vstack, then /plugin install vstack@hao-ai-lab-vstack.

What does vstack do?

It coordinates formal checks of models and state machines. Hash-pinned properties and mechanical gates help catch models that hide bugs by weakening checks.

What does vstack need to work?

The vstack setup command checks Java, TLC, and Z3. It also installs the skills, agents, and linked documentation.

Source text

SKILL.md · MIT
<p align="center">
  <img alt="vstack" src="assets/vstack-logo.svg" width="360">
</p>

<p align="center">
  <a href="https://haoailab.com/blogs/verifiable-llm-infra/"><b>Blog</b></a> ·
  <a href="https://docs.google.com/spreadsheets/d/1FL5QqgzEpja9k8Zw6GmIQDtHveddjj1coHe1MJ3Ts-Q/edit"><b>Verified AI Infra Bugs</b></a> ·
  <a href="https://github.com/hao-ai-lab/veriserve"><b>VeriServe</b></a> ·
  <a href="https://x.com/haoailab/status/2120595980659917024"><b>X</b></a>
</p>

`vstack` is a formal verification toolkit for coding agents. Naive agents routinely game formal checkers by weakening invariants, dropping timeout branches, or adding unverified assumptions; `vstack` enforces mechanical gates across TLA+, Apalache, TLAPS, and Z3 so agents find real bugs and prove critical state machines without cheating.

![vstack workflow](assets/vstack-anti-cheat.gif)

## News

- **[2026-11-13]** Shared 5 [vLLM](https://github.com/vllm-project/vllm) bug case studies on [X](https://x.com/haoailab/status/2121320482876399825), with 15+ bugs tracked and growing in our [bug tracker](https://docs.google.com/spreadsheets/d/1FL5QqgzEpja9k8Zw6GmIQDtHveddjj1coHe1MJ3Ts-Q/edit).
- **[2026-11-11]** Released `vstack` along with our [blog post](https://haoailab.com/blogs/verifiable-llm-infra/), [VeriServe](https://github.com/hao-ai-lab/veriserve), and [launch X thread](https://x.com/haoailab/status/2120595980659917024).

## Quick Start

```bash
git clone https://github.com/hao-ai-lab/vstack.git && cd vstack
uv tool install -e .
vstack setup   # checks Java/TLC/Z3 and installs skills, agents and the docs they link to into Claude Code, Codex, or Cursor
```

Or install directly as a plugin in Claude Code via `/plugin marketplace add hao-ai-lab/vstack` and `/plugin install vstack`, or in Cursor via `/add-plugin vstack`.

Run `/vstack-mode` on a target module and safety property:

```text
/vstack-mode verify that our RDMA KV cache lease manager never recycles an in-flight page on timeout.
```

## Anti-Reward-Hacking Gates

| Gate | What It Enforces |
| :--- | :--- |
| **[Role isolation](docs/layer-0.md)** | Separate coordinator, worker, and red-team agents keep specs, modeling, and review independent. |
| **[Hash-pinned specs](docs/contracts.md)** | SHA-256 locks safety properties and theorem signatures so workers cannot weaken the goal. |
| **[Line-anchored models](docs/method-selection.md)** | Every state variable and action maps to an exact `file:line@commit` across TLC, Apalache, and Z3. |
| **[Mutation & trace gates](docs/gates.md)** | Models must fail on historical bugs, pass with the fix, fail when guards are removed, and [replay real traces](docs/trace-validation.md). |
| **[Exposure gate](docs/exposure-gate.md)** | A finding is reported as caught by formal checking only if a faithful model with every bug switch off violates a named property, a red team fails to refute it, and it reproduces on a real engine next to a passing control. Shell models, experiment-only failures and calibration runs do not count. |
| **Proof & runtime checks** | Critical state machines scale to unbounded TLAPS proofs with preconditions mirrored as runtime checks. |

The **[model adequacy readout](docs/model-adequacy.md)** is not a gate: it reports how closely a model follows its code (trace acceptance, historical fix coverage and blind detection recall, each with its denominator and interval) and sets no thresholds. Bug hunts report a light version; full verification and regression skills report all of it.

## Recommended Models

| Workflow Stage | Recommended Models | Why |
| :--- | :--- | :--- |
| **Modeling, Proofs & Red-Team** | `Fable 5.2`, `GPT-6.1-Sol`, `Gemini 4 Carbon` at high reasoning effort | Strongest at state-machine abstraction, inductive invariants, and catching missing guards. |
| **Code Analysis & Repro Harness** | `Claude Opus 5.5`, `Gemini 4 Carbon` | Fast and reliable at navigating large Python/CUDA codebases and building multi-GPU reproducers. |

## Case Studies

- **AI Infra Bug Hunting:** Concurrency, lifecycle, and numerical bugs uncovered across [vLLM](https://github.com/vllm-project/vllm) and [SGLang](https://github.com/sgl-project/sglang), tracked in [Verified AI Infra Bugs](https://docs.google.com/spreadsheets/d/1FL5QqgzEpja9k8Zw6GmIQDtHveddjj1coHe1MJ3Ts-Q/edit) and synced from [`bugs/verified-bugs.csv`](bugs/verified-bugs.csv) with `Prior Status` separating net-new (`Unknown`) discoveries from partly tracked (`Partly Known`) and independently caught unfixed upstream bugs (`Known`).
- **Community Verification:** Reproduce an `In Progress` candidate on hardware, validate an open fix PR, or contribute a new formally caught infra bug via PR to [`bugs/`](bugs/README.md) to be credited under **`Human Verifier`**.
- **[VeriServe](https://github.com/hao-ai-lab/veriserve):** A Prefill-Decode serving engine built with `vstack`, proved across 226 TLAPS modules with +0.18% average p50 TPOT overhead on NVIDIA GB200.

## Contributors

<p>
  <a href="https://github.com/yuxuandexter"><img src="assets/contributors/yuxuandexter.png" width="56" alt="Yuxuan Zhang" title="Yuxuan Zhang (@yuxuandexter)"></a>&nbsp;
  <a href="https://github.com/alexzms"><img src="assets/contributors/alexzms.png" width="56" alt="Minshen Zhang" title="Minshen Zhang (@alexzms)"></a>&nbsp;
  <a href="https://github.com/Davids048"><img src="assets/contributors/Davids048.png" width="56" alt="Junda Su" title="Junda Su (@Davids048)"></a>&nbsp;
  <a href="https://github.com/Boreas618"><img src="assets/contributors/Boreas618.png" width="56" alt="Yi Sun" title="Yi Sun (@Boreas618)"></a>&nbsp;
  <a href="https://github.com/GindaChen"><img src="assets/contributors/GindaChen.png" width="56" alt="Junda Chen" title="Junda Chen (@GindaChen)"></a>
</p>

## Acknowledgments

Skill orchestration draws inspiration from Lauren Tan's [pstack](https://github.com/cursor/plugins/tree/main/pstack). Trace validation and proof gates build on lessons from [Specula](https://github.com/specula-org/Specula), [SysMoBench](https://github.com/specula-org/SysMoBench), and [TLAPS-Bench](https://github.com/specula-org/TLAPS-Bench). We thank the TLA+, Z3, SGLang, and vLLM communities.

## Citation

```bibtex
@misc{vstack2026,
  title        = {Towards Verifiable {LLM} Infra},
  author       = {Zhang, Yuxuan and Zhang, Minshen and Su, Junda and Sun, Yi and Chen, Junda and Zhang, Hao},
  year         = {2026},
  month        = nov,
  howpublished = {Hao AI Lab Blog},
  url          = {https://haoailab.com/blogs/verifiable-llm-infra/}
}
```

## License

MIT License — see [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).

© Hao AI Lab · MIT · hao-ai-lab/vstack

Similar plugins

All plugins for Testing and QA →
create-formal-verification-skill backnotprop The create-formal-verification-skill skill selects code for formal verification and creates a project-local guide for checking it again after changes. Use it when tests leave important invariants or event orderings uncovered. CX Codex +1 6,200installs Assura assura-lang This MCP server for Claude Code checks Assura contracts with Z3. An agent can verify a contract, infer a skeleton from Rust code, or explain an error code. CX Codex +1 ★ 9repo stars proof-theory parcadei proof-theory — a skill for mathematical logic proofs and decision trees across strategies. Guides you through direct proof, proof by contradiction, case analysis, and induction; verifies soundness, completeness, and cut elimination. CX Codex +1 1installs statechart backnotprop This skill verifies TLA+ models of stateful systems (purchase flows, protocols, services) with TLC and draws them as Mermaid statecharts. The report traces the shortest path to each state that breaks a rule. CX Codex +1 5,500installs writing-lean-proofs trailofbits writing-lean-proofs is a Claude Code skill for writing and reviewing Lean 4 proofs in line with Mathlib conventions. It comes into play for theorem proving, library design, proof refactoring, and project checks. CX Codex +1 1,800installs check_lean-and-lean-tools drawthingsai check_lean-and-lean-tools is a Claude Code skill that verifies Lean proofs for universal claims involving induction or recursion. It joins coding, debugging, review, or design tasks when a claim needs machine-checked lemmas. CX Codex +1 ★ 171repo stars

From the same set13

The whole set →
vstack-redteam The vstack-redteam Claude Code subagent probes model fidelity, property and gate strength, and scale assumptions. It records evidence that others can reproduce. CX Codex ★ 89repo stars vstack-main vstack-main — a subagent for Claude Code coordinates Verification Stack stages and checks their evidence independently. It accepts a stage only after reviewing its artifacts and results. CX Codex ★ 89repo stars vstack-s1-select The vstack-s1-select Claude Code skill selects verification methods and assurance tiers for system properties. It splits obligations by property and weighs scale, code ownership, and failure impact. CX Codex +1 ★ 89repo stars vstack-s6-hunt-fix The vstack-s6-hunt-fix Claude Code skill searches for bugs within a trace-validated model and checks proposed fixes. It classifies counterexamples and tests changes against real code. CX Codex +1 ★ 89repo stars vstack-s0-decompose vstack-s0-decompose is a Claude Code skill that maps system control, data flow, and boundaries, then builds evidence-backed historical anchors. It runs during analysis of a pinned source revision before verification. CX Codex +1 ★ 89repo stars vstack-s4-calibrate-tv The vstack-s4-calibrate-tv Claude Code skill calibrates behavior models and checks them against real traces. It runs stage S4 checks for bugs, fixes, repair components, and reachability witnesses. CX Codex +1 ★ 89repo stars vstack-mode The vstack-mode Claude Code skill runs staged verification for concurrent, distributed, and systems software. It takes a property from source investigation through proof and regression. CX Codex +1 ★ 89repo stars vstack-s2-spec The vstack-s2-spec Claude Code skill turns a design into testable specifications and pinned checks. It runs during specification work based on an approved S1 design and obligation matrix. CX Codex +1 ★ 89repo stars

Project sponsors

Companies that keep this analytics open