{"id":"9b02a3aa-206b-4195-94a9-87f8551c588c","slug":"yadavmandeep-veratum","kind":"mcp","name":"Veratum","summary":"\"Veratum - The production AI coding harness & skill for Antigravity, Claude Code, Cursor, and Windsurf. Prevents AI hallucinations, scope creep, and untested code.\"","owner":"yadavmandeep","repoUrl":"https://github.com/yadavmandeep/Veratum","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-15T17:29:48.000Z","addedAt":"2026-10-20T16:08:49.803Z","logoUrl":"https://avatars.githubusercontent.com/u/22600643?u=7cdf95cd3c35a7e44159d51f6a7413b0b5f83893&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["ai-agent","ai-agents","antigravity","claude-code","cline","code-quality","copilot","cursor"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-20T16:08:58.294Z","sample":false,"url":"https://conduits.dev/tools/yadavmandeep-veratum","language":"Python","transports":["stdio"],"install":{"npm":"@yadavmandeep/veratum"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n\n# Veratum\n\n**The AI coding skill and harness that remembers your repo, maps your code as a graph, and proves its work.**\n\n[yadavmandeep/Veratum](https://github.com/yadavmandeep/Veratum) · Antigravity · Claude Code · Cursor · Windsurf · Cline · GitHub Copilot · OpenCode\n\n[![Tests](https://img.shields.io/badge/tests-140%20passed-10B981.svg?style=flat-square&logo=githubactions&logoColor=white)](tests/)\n[![npm package](https://img.shields.io/npm/v/@yadavmandeep/veratum.svg?style=flat-square&logo=npm&color=CB3837)](https://www.npmjs.com/package/@yadavmandeep/veratum)\n[![npm downloads](https://img.shields.io/npm/dw/@yadavmandeep/veratum.svg?style=flat-square&logo=npm&color=CB3837)](https://www.npmjs.com/package/@yadavmandeep/veratum)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-3776AB.svg?style=flat-square&logo=python&logoColor=white)](pyproject.toml)\n[![Dependencies](https://img.shields.io/badge/dependencies-0-blue.svg?style=flat-square)](package.json)\n[![Supported IDEs](https://img.shields.io/badge/IDEs-7%20supported-8B5CF6.svg?style=flat-square)](docs/hosts.md)\n[![License: MIT](https://img.shields.io/badge/license-MIT-2563EB.svg?style=flat-square)](LICENSE)\n\n</div>\n\nVeratum is an open-source Agent Skill with a zero-dependency runtime. Your coding agent **remembers the project between sessions**, **locks the scope** of every change, **checks the blast radius** before it edits, **runs real validation** with compact logs, and **cannot say \"done\"** until a cryptographic gate confirms that the verified code is exactly the code on disk.\n\nFor Antigravity, install it in your project with one command:\n\n```bash\nnpx skills add yadavmandeep/veratum --skill veratum --agent antigravity --yes\n```\n\nThen say:\n\n```text\nUse Veratum to fix this bug and verify the result.\n```\n\n## Install\n\nPick **your** IDE or AI coding tool.\n\n### One-Command Full Setup (Recommended)\nRun this inside the project you want to use Veratum in (a brand-new project or one that already has code):\n\n```bash\nnpx @yadavmandeep/veratum init --ide antigravity   # or claude-code | cursor | windsurf | cline | copilot | opencode\n```\n*(Also works with `npx github:yadavmandeep/Veratum init` directly from source)*\n\n*Run `npx @yadavmandeep/veratum init` with no flags for an interactive picker that auto-detects your editors.*\n\n**What you get:** the runtime engine and project memory (`.veratum/`), the always-on rules, the MCP server and native hooks where your editor supports them, the **code graph** (builds itself the first time a session starts, and stays fresh), and the `/veratum` command (`/veratum graph build`, `/veratum graph query <question>`, `/veratum status`, ...). When it finishes, the installer prints the commands to type. Restart your editor (Claude Code: restart or open `/hooks`) so it loads them. Updating later: the same command with `update` instead of `init`.\n\n| IDE / Extension | Full Setup (Engine + Rules + MCP + Hooks + Code graph + `/veratum`) | Skill-only (`skills.sh`) |\n|---|---|---|\n| **Google Antigravity** | `npx @yadavmandeep/veratum init --ide antigravity` | `npx skills add yadavmandeep/veratum --skill veratum --agent antigravity --yes` |\n| **Claude Code** | `npx @yadavmandeep/veratum init --ide claude-code` | `npx skills add yadavmandeep/veratum --skill veratum --agent claude-code --yes` |\n| **Cursor** | `npx @yadavmandeep/veratum init --ide cursor` | `npx skills add yadavmandeep/veratum --skill veratum --agent cursor --yes` |\n| **Windsurf** | `npx @yadavmandeep/veratum init --ide windsurf` | `npx skills add yadavmandeep/veratum --skill veratum --agent windsurf --yes` |\n| **Cline (VS Code)** | `npx @yadavmandeep/veratum init --ide cline` | `npx skills add yadavmandeep/veratum --skill veratum --agent cline --yes` |\n| **GitHub Copilot (VS Code)** | `npx @yadavmandeep/veratum init --ide copilot` | `npx skills add yadavmandeep/veratum --skill veratum --agent github-copilot --yes` |\n| **OpenCode** | `npx @yadavmandeep/veratum init --ide opencode` | `npx skills add yadavmandeep/veratum --skill veratum --agent opencode --yes` |\n\n> ### ⚡ Map Your Entire Repo with Interactive Code Graph\n> After running `init`, simply type this in your agent's chat:\n> ```text\n> /veratum graph build\n> ```\n> *Veratum immediately maps all 24+ languages, markdown docs, and media assets into an interactive queryable graph (`graph.html`).*\n>\n> **Ask questions directly to the code graph:**\n> ```text\n> /veratum graph query where is authentication handled?\n> ```\n\n### Using VS Code with Multiple Extensions?\nVS Code supports several AI assistants. Configure Veratum for whichever assistant you use in VS Code:\n- **GitHub Copilot**: Use `--ide copilot` (writes `.github/copilot-instructions.md` and `.vscode/mcp.json`).\n- **Cline / Roo Code extension**: Use `--ide cline` (writes `.clinerules`).\n- **Claude Code CLI** (in VS Code terminal): Use `--ide claude-code` (writes `CLAUDE.md` and `.claude/settings.json`).\n- **Google Antigravity**: Use `--ide antigravity` (writes `.agents/skills/` and `.agents/plugins/`).\n- **Using more than one?** Pass multiple flags: `npx github:yadavmandeep/Veratum init --ide copilot --ide antigravity`, or select both in `npx github:yadavmandeep/Veratum init`. All tools share the same `.veratum/` memory and verification ledger!\n\n### 🔒 Privacy & Git: Keeping `.veratum/` Purely Local\nIf you are working on a company or shared repository and prefer not to commit Veratum's runtime or project memory to git, simply add `.veratum/` to your project's `.gitignore`:\n```gitignore\n# Keep Veratum runtime & memory 100% local\n.veratum/\n```\nVeratum functions completely offline and locally without needing to track or push anything to remote git. For machine-wide automatic exclusion across all your repos, add `.veratum/` to your global gitignore (`git config --global core.excludesfile ~/.gitignore_global`).\n\n### Or just ask your agent\n\nPaste this into any agent chat:\n\n```text\nInstall Veratum from https://github.com/yadavmandeep/veratum for this IDE only, following docs/install.md.\nInstall the skill with `npx skills add`, run its engine `init`, then run `doctor` and tell me the health score.\nDo not change unrelated configuration.\n```\n\n### Check it\n\n```bash\npython .veratum/engine/veratum_cli.py doctor     # → Health: 100%\n```\n\n## Use it\n\nYou don't need a special prompt. Veratum activates for implementation, debugging, refactoring and review work. Naming it makes sure:\n\n```text\nUse Veratum to find and fix why pagination sometimes skips records.\n```\n```text\nUse Veratum to add rate limiting to the API without breaking existing clients.\n```\n```text\nUse veratum-review to review this branch. Do not modify files.\n```\n```text\nUse veratum-highstakes to add the column migration for user emails.\n```\n\nEvery task ends with an evidence block you can check:\n\n```text\n━━━━━━━━━━━━━━━━ VERATUM EVIDENCE BLOCK ━━━━━━━━━━━━━━━━\nGoal:            Fix pagination skipping records\nChanged (2):     src/api/list.ts, src/api/list.test.ts\nScope:           ✓ all changes inside contract\nImpact checked:  src/routes/users.ts, src/routes/orders.ts\nVerified by:     `pnpm test -- list` → EXIT 0 (4.2s)\nTree hash:       sha256:9c41e0a7… (matches verified state)\n```\n\n### 🌐 Codebase & Multi-Format Knowledge Graph\n\nVeratum builds a queryable knowledge graph of your entire workspace on session start and keeps it fresh after every file edit. It is not limited to source code—it indexes **code, documents, papers, images, and media assets** with an honest audit trail:\n- **Languages (24+)**: Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, C#, Ruby, PHP, Bash, Kotlin, Swift, Elixir, Groovy, PL/SQL, JSP, etc.\n- **Documents & Prose**: Markdown (`.md`, `.mdx`), RST (`.rst`), Text (`.txt`), YAML (`.yaml`, `.yml`), HTML (`.html`), Quarto (`.qmd`), Org, AsciiDoc, LaTeX (`.tex`).\n- **Visual Assets & Media**: PNG, JPG, JPEG, GIF, WEBP, SVG, PDF, DOCX, XLSX, PPTX, MP4, MOV, WEBM, MP3, WAV.\n- **Automatic Graph Linkages**:\n  - Headings (`# Heading` or `<h1>...</h1>`) extract as navigable section nodes.\n  - Image and media embeds (`![alt](path)` or `<img src=\"path\">`) create direct **`embeds` [EXTRACTED]** edges to asset nodes.\n  - Relative links create **`references` [EXTRACTED]** edges.\n  - Symbol backticks (`` `myFunction()` ``) link prose directly to code definitions.\n- **Queryable Graph**: Your agent queries the graph before grep/globbing, reading only the relevant symbols and call paths instead of searching through thousands of files.\n\nType this directly in your agent's chat:\n\n```text\n/veratum graph query where is checkout handled?\n```\n\n`init` adds one unified slash command directly into your editor's chat: **`/veratum`**.\n\n> [!TIP]\n> **How to use slash commands:** In Claude Code, Cursor, Copilot, OpenCode, Windsurf, or Antigravity chat, type `/veratum` followed by the action:\n> - `/veratum graph build` *(builds code graph)*\n> - `/veratum graph query <question>` *(ask anything about the codebase)*\n> - `/veratum status` *(check contract and active task state)*\n> - `/veratum gate` *(check completion gate)*\n> - `/veratum impact <file>` *(check blast radius before touching code)*\n> \n> *If you're in a terminal or using Cline, simply use the engine CLI:*\n> `python .veratum/engine/veratum_cli.py graph query \"where is login?\"`\n\n| Type this in Chat | What happens |\n|---|---|\n| `/veratum graph build` | Maps code, docs, images & assets now (auto-refreshes incrementally in <50ms) |\n| `/veratum graph query <question>` | Answers from knowledge graph with file and line evidence |\n| `/veratum graph report` · `/veratum graph export` | Summary of god nodes & communities · Interactive HTML map, SVG, Obsidian vault & Cypher script |\n| `/veratum impact <file>` | Blast-radius analysis: dependents, symbols, and risk score before editing |\n| `/veratum status` · `/veratum gate` · `/veratum doctor` | Contract state & ledger evidence · Completion gate validation · 11-point health check |\n| `/veratum config graph_auto off` | Toggle auto-graph build (use `/veratum config` to list all options) |\n\n`/veratum graph export` (or `python .veratum/engine/veratum_cli.py graph export`) writes an interactive map (`graph.html`: open it in any browser. One dot per file, grouped into labelled community bubbles; zoom and drag, search a file or function, filter by link type, click a file to see what is inside it and exactly which lines link it to other files), a plain picture (`graph.svg`), an Obsidian vault and a Neo4j script to `.veratum/graph/export/`. `graph build` takes **every** file of the project (no 5000-file cap); on a big repo it prints progress, and `--max-files` / `--max-file-kb` are there if you want limits. `graph report` shows the most connected code and the code clusters (communities). `graph watch` rebuilds while you type. Every link shows the file and line it came from, marked `EXTRACTED` (it is written in the code), `INFERRED` (matched by name) or `AMBIGUOUS` (several candidates). In Claude Code, OpenCode and Antigravity a small hook also reminds the agent to use the graph the first two times it reaches for Grep/Glob in a task (it stops once the graph was used, and in the other editors the always-on rule text does that job; see [docs/hosts.md](docs/hosts.md)). To turn the automatic part off: `python .veratum/engine/veratum_cli.py config graph_auto off` (back on: `python .veratum/engine/veratum_cli.py config graph_auto auto`; just `python .veratum/engine/veratum_cli.py config` lists the settings you can change). More: [docs/usage.md](docs/usage.md#codebase-graph).\n\n**Example.** A tiny project with `app/billing.py` (`charge()` calls `audit()`) and `app/api.py` (`checkout()` calls `charge()`). You type:\n\n```text\n/veratum graph query how does checkout work?\n```\n\nThe agent runs `graph query` and gets this back (real output):\n\n```text\nNODE checkout (function) [src=app/api.py loc=L4 community=1]\nNODE charge (function) [src=app/billing.py loc=L1 community=0]\nNODE audit (function) [src=app/billing.py loc=L5 community=0]\nEDGE api.py --imports [EXTRACTED]--> billing.py  (app/api.py:L1)\nEDGE checkout --calls [INFERRED import-resolved]--> charge  (app/api.py:L5)\nEDGE charge --calls [INFERRED same-file]--> audit  (app/billing.py:L2)\n```\n\nReading it: `api.py` really imports `billing.py` on line 1 (`EXTRACTED`). `checkout` calls `charge` on line 5 and `charge` calls `audit` on line 2 (`INFERRED`: matched by name, so worth a glance). The agent opens those few lines instead of the whole repo.\n\nBefore changing `billing.py`, ask what could break:\n\n```text\n/veratum impact app/billing.py\n```\n```text\n[EXTRACTED] app/api.py:1 imports → app/billing.py  | from app.billing import charge\n[INFERRED]  app/api.py:5 calls   → app/billing.py::charge  | return charge(cart)\nRisk: LOW\n```\n\n```mermaid\nflowchart LR\n    G0[\"Gate 0<br/><b>Brain Sync</b><br/><i>Memory & Pitfalls</i>\"] --> G1[\"Gate 1<br/><b>Contract</b><br/><i>Blast Radius & Scope</i>\"]\n    G1 --> G2[\"Gate 2<br/><b>Checkpoint</b><br/><i>Hidden Snapshot</i>\"]\n    G2 --> G3[\"Gate 3<br/><b>Scope Exec</b><br/><i>Read-Before-Write</i>\"]\n    G3 --> G4[\"Gate 4<br/><b>Validation</b><br/><i>Compacted Logs (-90%)</i>\"]\n    G4 --> G5[\"Gate 5<br/><b>Crypto Gate</b><br/><i>SHA-256 Tree Match</i>\"]\n    G5 --> DONE([\"✨ Verified Done\"])\n\n    style G0 fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#f8fafc\n    style G1 fill:#1e293b,stroke:#6366f1,stroke-width:2px,color:#f8fafc\n    style G2 fill:#1e293b,stroke:#8b5cf6,stroke-width:2px,color:#f8fafc\n    style G3 fill:#1e293b,stroke:#ec4899,stroke-width:2px,color:#f8fafc\n    style G4 fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#f8fafc\n    style G5 fill:#1e293b,stroke:#10b981,stroke-width:2px,color:#f8fafc\n    style DONE fill:#065f46,stroke:#10b981,stroke-width:2px,color:#ecfdf5\n```\n\n## Why Veratum? (The Problem with Vanilla AI Agents)\n\n| Common AI Agent Failure | What Happens Without Veratum | How Veratum Solves It |\n|---|---|---|\n| **Amnesia Across Sessions** | Agent forgets repo conventions, test runners, and previous fixes. | **Gate 0 (Brain)**: Loads `.veratum/brain.json` with auto-detected stack, proven commands, and architectural pitfalls. |\n| **Silent Scope Creep** | Agent refactors unrelated files or imports new dependencies unasked. | **Gate 1 & 3 (Contract & Scope)**: Strict file lock; edits outside scope are blocked before they run. |\n| **Unintended Breakage** | Edits break callers in other modules because the agent had no dependency awareness. | **Blast-Radius Analysis**: Traces AST imports, dependent symbols, and co-change history before any edit. |\n| **Disastrous Experiments** | Agent gets lost in broken diffs, leaving broken working tree. | **Gate 2 (Shadow Checkpoint)**: Hidden zero-risk git snapshot with instant 1-command rollback (`V rollback`). |\n| **Token Exhaustion** | Huge test stack traces overflow the context window, causing hallucinations. | **Gate 4 (Compacted Validation)**: Strips 80–95% noisy terminal output, retaining only actionable failures. |\n| **False \"Done\" Claims** | Agent says \"fixed\" without testing, or tests and then sneaks in an untested final edit. | **Gate 5 (Cryptographic Gate)**: Completion blocked unless current working-tree SHA-256 matches verified ledger hash. |\n\n| Gate | What happens | Why it matters |\n|---|---|---|\n| 0 · Brain | Loads `.veratum/brain.json`: stack, proven commands, decisions, pitfalls | No re-learning the repo every session |\n| 1 · Contract | Goal + allowed files + verify command, plus a list of every file that imports what you'll touch | No blind edits, no surprise breakage |\n| 2 · Checkpoint | Hidden git snapshot (including untracked files) | One-command rollback of a bad experiment |\n| 3 · Scope | Only contracted files may change | No drive-by refactors |\n| 4 · Verify | Runs the real command. Failures are compacted to errors only (80–95% fewer tokens) | The agent reasons on signal, not noise |\n| 5 · Gate | Passes only if the **exact verified bytes** are still on disk | \"I tested it, then edited one more thing\" gets caught |\n\n## The skill pack\n\n| Skill | Use it for |\n|---|---|\n| `veratum` | Core 6-gate protocol + engine (install this first) |\n| `veratum-debug` | Bugs: reproduce first, root cause, regression test |\n| `veratum-review` | Read-only review with blast radius and evidence |\n| `veratum-refactor` | Behaviour-preserving refactors in small, checkpointed steps |\n| `veratum-highstakes` | Auth, payments, migrations, deletions, infra |\n| `veratum-typescript` | TS/JS stack pack (package managers, aliases, pitfalls) |\n| `veratum-python` | Python stack pack (envs, runners, pitfalls) |\n\n```bash\nnpx skills add yadavmandeep/veratum --skill veratum-debug --agent cursor --yes\nnpx skills add yadavmandeep/veratum --agent claude-code --yes          # whole pack\n```\n\n## Skill vs Enforced\n\n| Capability | Skill | Enforced |\n|---|:---:|:---:|\n| 6-gate protocol, project memory, blast radius, checkpoints, compacted verify | ✓ | ✓ |\n| Completion gate with tree-hash check | Agent runs it | Runs automatically when the agent stops |\n| Block edits outside the contract | — | ✓ (Antigravity, Claude Code, OpenCode). Cursor/Windsurf/Cline/Copilot get scope checks via MCP tools |\n| Read-before-write + stale-read detection | Instruction | ✓ hook hosts |\n| Shell guard: tokenized capability levels, out-of-scope writes blocked *before* they run | `explain-shell` on demand | ✓ hook hosts |\n| Plan/review mode action lock | Instruction + gate | ✓ hook hosts |\n| Mark evidence stale on every edit | Detected at gate | Immediately, after each tool call |\n| Duplicate-failure guard, same-failure signature, hash-chained evidence, risk-adaptive profiles | ✓ | ✓ |\n| Block evidence tampering, and destructive commands without a checkpoint | — | ✓ (hook hosts) |\n\nHooks are workflow guardrails, not an OS sandbox. See [hosts](docs/hosts.md) for the exact capability of each IDE.\n\n## Documentation\n\n- [Quickstart](docs/quickstart.md): first task in 3 minutes\n- [Installation guide](docs/install.md): every IDE, verify, update, uninstall\n- [Using Veratum](docs/usage.md): prompts, commands, the evidence block\n- [Skill pack](docs/skills.md): when to use which skill\n- [Hosts](docs/hosts.md): what each IDE enforces, honestly\n- [Concepts](docs/concepts.md): brain, contract, ledger, tree hash, scope drift\n- [Configuration](docs/configuration.md): `.veratum/config.json`\n- [Troubleshooting](docs/troubleshooting.md)\n- [Publishing & launch](docs/publishing.md): for maintainers\n\n## Contributing\n\n```bash\nnode bin/veratum.js build     # regenerate skills/veratum + IDE adapters from core/SKILL.template.md\nnpm test                     # sync check + full test suite\n```\n\nMIT © [yadavmandeep/Veratum](https://github.com/yadavmandeep/Veratum)\n"}