vericontext

Docs lie. Hashes don't.

SHA-256 citations for docs that reference code.
One stale citation breaks the whole document. By design.

English · 한국어

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

Manual install per agent

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  │
                                └───────────────────────┘

• Cite — snapshot a file range with its SHA-256 hash (first 8 hex chars)
• Claim — declare structure facts: exists-dir, missing
• 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

Error reasons

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