Install Hibi and Record Your First Code-Anchored Claim

Install Hibi, record your first claim anchored to real source code, run a drift check, and read your first verdict — all in a few commands.

You’re about to edit src/auth.ts. Does any doc ride on it? hibi query --path src/auth.ts lists the two claims — one in README.md, one in CLAUDE.md — that both anchor to the 30-minute token TTL you’re about to touch. You change the constant, run hibi diff --since origin/main, and Hibi tells you exactly which two sentences you just broke — and hands you the command to fix each. That is the whole point: docs that flag themselves the moment the code beneath them moves.

Hibi tracks claims: sentences in your docs or AI-agent instructions that assert how the code behaves. You anchor each claim to the code that backs it, and hibi check flags the claim whenever either side drifts, so no reader, and no agent, acts on a page that has fallen out of sync with the source.

This page takes you from nothing to a checked claim. The whole loop is three verbs: record a claim, check it, and read the verdict. A flag is a request to re-verify, not a claim that the doc is wrong.

Install

Hibi ships as a single self-contained executable, with no runtime to install. You can also add it to a Bun project from npm.

Prebuilt binary

# Single-file executable, no runtime needed
curl -fsSL https://raw.githubusercontent.com/npupko/hibi/main/scripts/install.sh | sh

The npm package is Bun-targeted: it runs under Bun. For a zero-runtime install on any machine, use the prebuilt binary above.

Record and check a claim

1. Initialize the store

   hibi init creates a committed .claims/ directory beside your docs, with a per-repo banner nonce. Each claim becomes its own file in here, so merges stay scoped: there is no monolithic lockfile.

   hibi init
   
2. Record a claim, anchored to the code that backs it

   Hibi is span-first: you point at the documented sentence and at the code it describes, and the doc span supplies the claim text. The example below binds a line of your README to the constant that enforces it.

   hibi record \
     --doc README.md --doc-quote "Retries are capped at 5 attempts" \
     --code-file src/retry.ts --code-quote "MAX_ATTEMPTS = 5" \
     --trust verified --ref PR-1024 --owner alice
   

   Because the code side mentions the literal 5, changing MAX_ATTEMPTS to 50 later will trip this claim even if nothing else in the file moves.

3. Verify every claim

   hibi check re-finds each claim’s anchors in your current files and computes a verdict. Add --write to stamp a status banner into any doc whose claims are now suspect, so the staleness is visible in the file itself.

   hibi check              # verify every claim
   hibi check --write      # verify, and stamp status banners into affected docs
   

A verdict reads like doc:unchanged · code:changed · behavior:at-risk: one short, side-prefixed status per axis. hibi check exits 0 when everything is clean, 2 when an enforced claim has a gating problem (changed, orphaned, or ambiguous on either side, expired, or refuted), and 3 for a re-anchorable warning (moved or at-risk). A moved claim never fails the build on its own.

Everyday commands

hibi diff --since origin/main     # what did this change invalidate?
hibi query --path src/retry.ts    # before editing: which claims cover this file?
hibi list --state gating          # triage: one lean row per drifting claim
hibi coverage --doc README.md     # which blocks of a doc are backed by a claim vs uncovered?
hibi reanchor <claim-id> --doc-quote "…" --code-file src/retry.ts  # re-resolve a drifted claim
hibi retire <claim-id>            # withdraw a single obsolete claim
hibi relocate --from docs/old.md --to docs/merged.md  # re-home every claim onto the merged doc
hibi doctor                       # store-health report (informational; always exits 0)
hibi status --doc README.md       # is this one doc still current?

hibi status --doc <path> is the read-time gate an agent runs before it trusts a doc; hibi diff --since <ref> is the write-time loop that reports what a change invalidated. Both exit 2 on a gating problem and 3 on an advisory warning, so they drop straight into CI or a git hook.

Every drift verdict comes with a remediation menu — a recommended next step and a list of actions, each with a ready-to-run command where Hibi can perform the fix (hibi reanchor asrt_…, hibi retire asrt_…). You rarely have to figure out the fix yourself; the verdict hands it to you.

Output is TTY-aware: a rich human view in a terminal, compact JSON when piped or in CI. Pass --json to force the machine contract, --pretty to force the human view. The JSON is concise by default — add --explain for the full evidence tail, or --no-hints to drop the remediation menu.

See the CLI reference for every command, flag, exit code, and strictness level (--fail-on gating|warn|tamper|never).

How it works

Claims, redundant anchors, the doc-first resolution flow, and how verdicts are graded, deterministically, with no model in the check loop.