# Vigilis
**Category:** ๐ป Developer Tools
**Repository:** https://github.com/piyushpathakqa/Vigilis
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/vigilis
## Description
Gate AI-written tests: heal safe drift, refuse to hide real bugs, sign a verifiable receipt.
## Claude Desktop Quick Installation
Heuristic fallback โ verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"vigilis": {
"command": "npx",
"args": ["-y","vigilis"]
}
}
```
## Documentation & README
๐๏ธ Vigilis
The QA gate for AI-written code.
It heals safe test drift, refuses real regressions, and signs every decision into an independent, verifiable receipt.
---
## The problem
Tell any coding agent to *"make CI pass"* and the cheapest path to green is **deleting the test that caught the bug.** AI now writes and fixes tests on its own โ so the only question that matters is: **can you trust what it did?**
Vigilis answers it. Point it at the Playwright, Cypress, or Selenium suite you already have. When a test breaks, it decides:
- **Cosmetic drift** (a renamed selector) โ it heals the locator, re-runs to verify green, opens a PR.
- **A real behaviour change** (checkout total went from `$49` to `$0`) โ it **refuses to touch the test, fails the gate**, and surfaces the bug instead of burying it.
And **every decision is sealed into a signed, offline-verifiable receipt** by an independent notary โ so a refusal is something you can *prove*, not just claim.
> Self-healing is the wedge. **Verifiable proof is the point.**
**Where teams point it:** gate AI-written code ยท self-heal without hiding bugs ยท auditable test runs ยท audit-grade evidence for SOX / payment controls ยท agent-native (MCP). โ [see the use cases](https://vigilis.dev/use-cases)
## See it refuse a real bug
The agent ran the spec, saw it fail, checked that the selectors were all correct, concluded the app's login was genuinely broken, and **refused to heal** โ then sealed a receipt anyone can verify offline.
## Quickstart
```bash
npm i -D vigilis # in your Playwright / Cypress / Selenium project
npx playwright install chromium # one-time, for browser automation
export ANTHROPIC_API_KEY=sk-ant-... # a pay-as-you-go API key (not a Claude.ai subscription)
npx vigilis init # scaffold vigilis.config.json (auto-detects your framework)
npx vigilis generate https://your-app.com --run # explore the app โ write + run a real spec
npx vigilis heal https://your-app.com --spec tests/login.spec.ts # heal drift โ verify green โ PR (refuses real bugs)
# already have a suite running in CI? attest the run you just did โ no API key, no secrets:
npx playwright test --reporter=json > report.json
npx vigilis attest-run report.json --commit $GITHUB_SHA --exit-code $?
npx vigilis verify .vigilis/attestation/qa-run-*.json # offline: chain intact, or broken at record #N
```
Runs in your CI on your own key + chromium. About **10ยข per run** on the fast model (`--model claude-haiku-4-5`); Opus by default for quality.
## Why it's different
| | Vigilis |
|---|---|
| **Heals** | Rewrites the locator for cosmetic drift, re-verifies green, opens a PR. |
| **Refuses** | A real regression is a hard, fail-closed contract โ it will not weaken the assertion that caught the bug. |
| **Proves** | Every heal *and* every refusal is sealed into an independent, offline-verifiable receipt (via [Treeship](https://www.treeship.dev)). |
Attestation is **verifiable** and **auditable** โ it proves *what the agent did*, in order, unaltered. It does **not** claim the agent's judgement was correct. That honesty is the point: Vigilis improves signal, it doesn't hide failures.
**Why a refusal is credible: no layer grades its own work.** The **actor** (any agent) writes the code and tests; **Vigilis** judges the behaviour and gates the deploy; an **independent notary** ([Treeship](https://www.treeship.dev)) signs the verdict. Vigilis never signs its own homework โ which is what makes the proof worth anything to someone who doesn't already trust you.
## Optional: alert on a refusal
On a real-bug refusal, Vigilis can post a **Slack** alert and file a **deduplicated Linear** ticket โ each linking the signed receipt. Off by default; a no-op until you set `SLACK_WEBHOOK_URL` / `LINEAR_API_KEY`. See [`docs/REFUSAL-ACTIONS.md`](https://github.com/piyushpathakqa/Vigilis/blob/HEAD/docs/REFUSAL-ACTIONS.md).
## Drive it from Claude (MCP)
The same tools ship as an **MCP server** ([`vigilis-mcp`](https://www.npmjs.com/package/vigilis-mcp), [in the official MCP registry](https://registry.modelcontextprotocol.io)) โ generate / triage / heal straight from Claude Desktop, Claude Code, or Cursor. Add it to your MCP client config:
```json
{
"mcpServers": {
"vigilis": {
"command": "npx",
"args": ["-y", "vigilis-mcp"],
"env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
}
}
}
```
Full setup: [`docs/MCP.md`](https://github.com/piyushpathakqa/Vigilis/blob/HEAD/docs/MCP.md).
## Provenance receipts
Receipts work out of the box with **zero secrets** โ no account, no API key, no network:
- **`vigilis attest-run `** seals *any* test run (not just Vigilis's own) into a receipt: it hash-chains the Playwright report's digest, the commit SHA, and the runner's exit code into a tamper-evident bundle under `.vigilis/attestation/`. Drop it after your existing `playwright test` step in CI and every run leaves evidence.
- **`vigilis heal`** seals its whole triage-and-heal session the same way โ every tool call and every decision, hash-chained in order.
- **`vigilis verify `** re-walks the chain offline and reports *chain intact* or *broken at record #N*. Anyone holding the file can check it; editing or deleting any step breaks every hash after it.
When the [Treeship](https://www.treeship.dev) CLI is present, `heal` receipts are additionally **signed by an independent notary** โ verify with `treeship verify last`, or share the hosted URL. No hard dependency; `--no-receipt` to opt out. See [`docs/TREESHIP.md`](https://github.com/piyushpathakqa/Vigilis/blob/HEAD/docs/TREESHIP.md).
Local bundles are verifiable and auditable (they prove *what the agent did*, unaltered and in order โ not that its judgment was correct); Treeship upgrades that to a signed, independently-notarized receipt.
## Why I built this
I've spent my career in QA, and AI just rewrote the job: agents now write and fix tests on their own. Huge speed win โ but it quietly breaks the one thing testing exists for. When an agent makes a red test green, did it *fix* the bug, or delete the test that caught it? At scale, nobody can check every change by hand.
So Vigilis isn't another self-healer โ healing is becoming a commodity. It's the layer that decides **honestly** which failures to heal and which to refuse, and signs every call so you don't have to take its word for it.
The way I think about it: **git is a ledger of your code; Vigilis is a ledger of your agent's decisions** โ proof you can hand to someone who doesn't already trust you.
โ [Piyush](https://vigilis.dev)
---
## How it's built
Vigilis defines its QA tools **once** and exposes them **twice** โ as an MCP server and as a CLI โ over one Claude agent loop:
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ core โ Anthropic Messages API + tool use
โ Agent loop + Tool Registry โ browser ยท dom ยท fs ยท playwright ยท git
โโโโโโโโโฌโโโโโโโโโโโโโโโโฌโโโโโโโ
โโโโโโโโโโโโโโผโโโ โโโโผโโโโโโโโโโโโโโโโ
โ vigilis-mcp โ โ vigilis (CLI) โ
โ MCP server โ โ npx vigilis ... โ
โ (Claude) โ โ (used in CI) โ
โโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
```
The loop: **Generate** (explore a URL โ write specs) โ **Triage** (real-bug vs drift vs flake) โ **Heal** (fix drift โ verify green โ PR, refuse real bugs). *Author* (plain-English intent โ test plan) is on the roadmap.
### Repo layout
```
vigilis/
โโ packages/
โ โโ core/ # agent loop, tool registry, Claude client, prompts, refusal actions
โ โโ mcp/ # MCP server wrapping the registry
โ โโ cli/ # the `vigilis` command (generate | triage | heal | attest-run | verify)
โโ apps/
โ โโ sample-shop/ # Next.js demo target (login + products + cart, with seeded drift/bug toggles)
โ โโ cloud/ # governance cloud โ org audit dashboard over signed receipts
โ โโ web/ # landing page โ vigilis.dev
โโ tests/ # generated specs land here
```
### Develop
```bash
pnpm install
cp .env.example .env # add ANTHROPIC_API_KEY
pnpm build && pnpm test
```
Watch the full loop against the bundled demo app โ see [`docs/DEMO.md`](https://github.com/piyushpathakqa/Vigilis/blob/HEAD/docs/DEMO.md).
## Roadmap
- โ
Generate ยท Triage ยท Heal (Playwright, Cypress & Selenium โ all live-verified)
- โ
GitHub Actions QA gate ยท signed provenance receipts ยท MCP server
- โ
Refusal actions (Slack + Linear) ยท governance-cloud audit dashboard
- โ
Zero-secret attestation: `attest-run` + `verify` โ receipts for any test run, no keys
- ๐ง Author (intent โ test plan) ยท broader agent-attestation surface
## Credits
Provenance receipts are powered by **[Treeship](https://www.treeship.dev)** โ the independent attestation primitive โ and governed memory by **ZMem**, both built by **Zerker Labs**. Thanks to the Zerker Labs team for the trust primitives Vigilis stands on.
## License
[MIT](https://github.com/piyushpathakqa/Vigilis/blob/HEAD/LICENSE) ยฉ Piyush Pathak