The Problem

AI agents scatter README.md and AGENTS.md across directories. It works great until the code changes and the docs don't. Files move, functions get rewritten, but the docs still say "handler logic lives in src/handler.ts at L30-L45."

Over time, docs become liars. Agents that trust stale docs make worse decisions.

VeriContext embeds a SHA-256 content hash into every code citation at write time. Verify later: hash matches or it doesn't. No fuzzy matching. No "close enough."

Write time:    "handler logic" [ [vctx:src/handler.ts#L30-L45@a1b2c3d4] ]
After change:  vericontext verify → ❌ hash_mismatch (a1b2c3d4 ≠ f5e6d7c8)

One broken citation → entire doc fails. Fail-closed by design.

What It Looks Like

Citations live in HTML comments — invisible in GitHub, VSCode, or any Markdown renderer.

Raw Markdown:

The auth module handles login.
<!-- [ [vctx:src/auth.ts#L1-L50@abcd1234] ] -->

├── src/          <!-- [ [vctx-exists-dir:src/] ] -->
├── tests/        <!-- [ [vctx-exists-dir:tests/] ] -->

Rendered:

The auth module handles login.

├── src/ ├── tests/

vericontext verify finds and checks every citation. If src/auth.ts changes, the hash breaks, the doc fails.

Setup

npx skills add amsminn/vericontext --skill vericontext-enforcer

Auto-detects your agent (Claude Code, Codex, Antigravity, Cursor, Windsurf, OpenCode, ...) and installs to the right path. Supports 40+ agents.

# uninstall
npx skills remove vericontext-enforcer

Once installed, the agent automatically:

• Inserts [[vctx:...]] citations when referencing code in docs
• Runs vctx_verify_workspace before commits
• Flags stale citations for update

The skill lives at skills/vericontext-enforcer/SKILL.md. Copy it to the right place:

| Agent | Skill path | MCP needed? | |-------|-----------|-------------| | Claude Code | .claude/skills/vericontext-enforcer/ | No | | Antigravity | ~/.gemini/antigravity/skills/vericontext-enforcer/ | No | | Codex | .codex/skills/vericontext-enforcer/ | Yes | | Cursor | .cursor/rules/vericontext.mdc | Yes | | Windsurf | .windsurf/rules/vericontext.md | Yes | | OpenCode | Project rules | Yes |

For agents that need MCP, add to your config:

{ "mcpServers": { "vericontext": { "command": "npx", "args": ["-y", "vericontext", "mcp"] } } }

MCP tools: vctx_cite, vctx_claim, vctx_verify_workspace

How It Works

Three operations, one principle: hash it or it doesn't count.

  cite           claim           verify
┌────────┐    ┌────────────┐    ┌───────────────────────┐
│  file  │──→ │ [[vctx:..  │    │ for each token:       │
│ +lines │    │  @hash8]]  │    │   recompute hash      │
└────────┘    └────────────┘    │   match? → ok : fail  │
                                │ any fail → doc fails  │
                                └───────────────────────┘

1. Cite — snapshot a file range with its SHA-256 hash (first 8 hex chars)
2. Claim — declare structure facts: exists-dir, missing
3. Verify — check every citation and claim. One failure → whole doc fails

Token Syntax

| Type | Token | Example | |------|-------|---------| | Code citation | [ [vctx:path#Lstart-Lend@hash8] ] | [ [vctx:src/cli.ts#L1-L10@a1b2c3d4] ] | | Directory exists | [ [vctx-exists-dir:path/] ] | [ [vctx-exists-dir:src/] ] | | Path missing | [ [vctx-missing:path] ] | [ [vctx-missing:tmp-output/] ] |

Files always get hashed. Any mention of a file — its role, code, or existence — uses vctx_cite to hash the full file. Only directories use exists-dir claims.

CLI Reference

npm install -g vericontext    # or use npx

cite — generate a code citation

npx vericontext cite --root <dir> --path <file> --start-line <n> --end-line <n> [--json]

claim — generate a structure claim

npx vericontext claim --root <dir> --kind <kind> --path <path> [--json]

--kind: exists | exists-file | exists-dir | missing

verify workspace — verify all claims in a document

npx vericontext verify workspace --root <dir> (--in-path <doc> | --text <text>) [--json]

| Exit code | Meaning | |-----------|---------| | 0 | All valid | | 1 | One or more failures |

| Reason | Meaning | |--------|---------| | hash_mismatch | Content changed since citation | | file_missing | File does not exist | | path_escape | Path escapes root jail | | range_invalid | Line range out of bounds | | binary_file | Binary file detected | | symlink_skipped | Symlink skipped for determinism | | invalid_input | Malformed input |

mcp — run as MCP server

npx vericontext mcp

Exposes vctx_cite, vctx_claim, vctx_verify_workspace over stdio.

GitHub Actions

- name: Verify docs
  run: npx -y vericontext verify workspace --root . --in-path README.md --json

Pre-commit Hook

# .husky/pre-commit
npx vericontext verify workspace --root . --in-path README.md --json

Self-Verifying Docs

This README contains hidden VeriContext claims. Verify it:

npx vericontext verify workspace --root . --in-path README.md --json

To see how claims look in raw source, view this file with cat README.md or click "Raw" on GitHub.

Contributing

See CONTRIBUTING.md.

License

MIT