{
  "markdown": "<h1 align=\"center\">👁️ Vigilis</h1>\n\n<p align=\"center\"><b>The QA gate for AI-written code.</b><br/>\nIt heals safe test drift, <b>refuses real regressions</b>, and signs every decision into an independent, verifiable receipt.</p>\n\n<p align=\"center\">\n<a href=\"https://www.npmjs.com/package/vigilis\"><img src=\"https://img.shields.io/npm/v/vigilis?color=41f59a&label=npm\" alt=\"npm\"></a>\n<a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"MIT\"></a>\n<a href=\"https://github.com/piyushpathakqa/Vigilis/actions/workflows/ci.yml\"><img src=\"https://github.com/piyushpathakqa/Vigilis/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"></a>\n<a href=\"https://vigilis.dev\"><img src=\"https://img.shields.io/badge/site-vigilis.dev-ece7da\" alt=\"site\"></a>\n</p>\n\n<p align=\"center\"><img src=\"./docs/vigilis-receipts-comparison.png\" alt=\"One agent, two decisions: a cosmetic drift is healed; a real bug is refused — both signed.\" width=\"880\"></p>\n\n---\n\n## The problem\n\nTell 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?**\n\nVigilis answers it. Point it at the Playwright, Cypress, or Selenium suite you already have. When a test breaks, it decides:\n\n- **Cosmetic drift** (a renamed selector) → it heals the locator, re-runs to verify green, opens a PR.\n- **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.\n\nAnd **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.\n\n> Self-healing is the wedge. **Verifiable proof is the point.**\n\n**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)\n\n## See it refuse a real bug\n\n<img src=\"./docs/images/vigilis-refuse-terminal.png\" alt=\"vigilis heal refusing a real bug and sealing a verifiable receipt\" width=\"820\">\n\nThe 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.\n\n## Quickstart\n\n```bash\nnpm i -D vigilis                      # in your Playwright / Cypress / Selenium project\nnpx playwright install chromium       # one-time, for browser automation\nexport ANTHROPIC_API_KEY=sk-ant-...   # a pay-as-you-go API key (not a Claude.ai subscription)\n\nnpx vigilis init                                   # scaffold vigilis.config.json (auto-detects your framework)\nnpx vigilis generate https://your-app.com --run    # explore the app → write + run a real spec\nnpx vigilis heal https://your-app.com --spec tests/login.spec.ts   # heal drift → verify green → PR (refuses real bugs)\n\n# already have a suite running in CI? attest the run you just did — no API key, no secrets:\nnpx playwright test --reporter=json > report.json\nnpx vigilis attest-run report.json --commit $GITHUB_SHA --exit-code $?\nnpx vigilis verify .vigilis/attestation/qa-run-*.json    # offline: chain intact, or broken at record #N\n```\n\nRuns 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.\n\n## Why it's different\n\n| | Vigilis |\n|---|---|\n| **Heals** | Rewrites the locator for cosmetic drift, re-verifies green, opens a PR. |\n| **Refuses** | A real regression is a hard, fail-closed contract — it will not weaken the assertion that caught the bug. |\n| **Proves** | Every heal *and* every refusal is sealed into an independent, offline-verifiable receipt (via [Treeship](https://www.treeship.dev)). |\n\nAttestation 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.\n\n**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.\n\n## Optional: alert on a refusal\n\nOn 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`](./docs/REFUSAL-ACTIONS.md).\n\n## Drive it from Claude (MCP)\n\nThe 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"vigilis\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"vigilis-mcp\"],\n      \"env\": { \"ANTHROPIC_API_KEY\": \"sk-ant-...\" }\n    }\n  }\n}\n```\n\nFull setup: [`docs/MCP.md`](./docs/MCP.md).\n\n## Provenance receipts\n\nReceipts work out of the box with **zero secrets** — no account, no API key, no network:\n\n- **`vigilis attest-run <report.json>`** 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.\n- **`vigilis heal`** seals its whole triage-and-heal session the same way — every tool call and every decision, hash-chained in order.\n- **`vigilis verify <bundle>`** 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.\n\nWhen 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`](./docs/TREESHIP.md).\n\nLocal 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.\n\n## Why I built this\n\nI'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.\n\nSo 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.\n\nThe 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.\n\n— [Piyush](https://vigilis.dev)\n\n---\n\n## How it's built\n\nVigilis defines its QA tools **once** and exposes them **twice** — as an MCP server and as a CLI — over one Claude agent loop:\n\n```\n                     ┌──────────────────────────────┐\n                     │   core                       │  Anthropic Messages API + tool use\n                     │   Agent loop + Tool Registry │  browser · dom · fs · playwright · git\n                     └───────┬───────────────┬──────┘\n                ┌────────────▼──┐         ┌──▼───────────────┐\n                │ vigilis-mcp   │         │ vigilis (CLI)    │\n                │ MCP server    │         │ npx vigilis ...  │\n                │ (Claude)      │         │ (used in CI)     │\n                └───────────────┘         └──────────────────┘\n```\n\nThe 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.\n\n### Repo layout\n\n```\nvigilis/\n├─ packages/\n│  ├─ core/   # agent loop, tool registry, Claude client, prompts, refusal actions\n│  ├─ mcp/    # MCP server wrapping the registry\n│  └─ cli/    # the `vigilis` command (generate | triage | heal | attest-run | verify)\n├─ apps/\n│  ├─ sample-shop/   # Next.js demo target (login + products + cart, with seeded drift/bug toggles)\n│  ├─ cloud/         # governance cloud — org audit dashboard over signed receipts\n│  └─ web/           # landing page → vigilis.dev\n└─ tests/            # generated specs land here\n```\n\n### Develop\n\n```bash\npnpm install\ncp .env.example .env    # add ANTHROPIC_API_KEY\npnpm build && pnpm test\n```\n\nWatch the full loop against the bundled demo app — see [`docs/DEMO.md`](./docs/DEMO.md).\n\n## Roadmap\n\n- ✅ Generate · Triage · Heal (Playwright, Cypress & Selenium — all live-verified)\n- ✅ GitHub Actions QA gate · signed provenance receipts · MCP server\n- ✅ Refusal actions (Slack + Linear) · governance-cloud audit dashboard\n- ✅ Zero-secret attestation: `attest-run` + `verify` — receipts for any test run, no keys\n- 🚧 Author (intent → test plan) · broader agent-attestation surface\n\n## Credits\n\nProvenance 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.\n\n## License\n\n[MIT](./LICENSE) © Piyush Pathak\n",
  "bytes": 9900,
  "sha": "89e874ea5d233eb1ec1a67b26c4f1c8cc543860eb31a45582d88b1910be255fa",
  "repo_slug": "piyushpathakqa/vigilis",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_piyushpathakqa_vigilis_mcp_eb59281c/readme"
}