Install Hibi and Record Your First Claim

Install Hibi, record a claim anchored to source code, run hibi check, and read the verdict.

Hibi tracks claims: sentences in your docs or agent instruction files, each anchored to the code it describes. hibi check flags a claim when either side changes. A flag is a request to re-verify, not a statement that the doc is wrong.

Install

Prebuilt binary

curl -fsSL https://raw.githubusercontent.com/npupko/hibi/main/scripts/install.sh | sh

The npm package targets Bun. For a machine with no JS runtime, use the prebuilt binary.

Record and check a claim

1. Initialize the store

   hibi init creates a .claims/ directory with a per-repo banner nonce. One file per claim. Commit it.

   hibi init
   
2. Record a claim

   Point at the documented sentence and at the code span that backs it. Quote the load-bearing token on the code side.

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

   The claim is enforced by default. --verified records that you confirmed the code backs the sentence. Because the code span contains the literal 5, changing it to 50 later trips the claim even if nothing else moves.

   Agents record in batches on stdin:

   echo '[{"doc":"README.md","docQuote":"Retries are capped at 5 attempts",
           "codeFile":"src/retry.ts","codeQuote":"MAX_ATTEMPTS = 5","verified":true}]' \
     | hibi record --from-file -
   
3. Check

   hibi check              # verify every claim
   hibi check --write      # also stamp a banner into each suspect document
   

hibi check exits 0 when clean, 2 when an enforced claim gates (changed, orphaned, or ambiguous on either side, expired, or refuted), and 1 on an operational error. A moved side is a warning and exits 0 unless you pass --fail-on warn.

Everyday commands

hibi check --doc CLAUDE.md         # is this document still current?
hibi check --since origin/main     # what did this change invalidate?
hibi check --overview              # per-document table
hibi list --path src/retry.ts      # which claims depend on this file?
hibi list --state gating           # one row per gating claim
hibi coverage --doc README.md      # which sentences have no claim?
hibi reanchor <claim-id>           # re-resolve and store the new baseline
hibi reanchor <claim-id> --suggest # candidate locations for a lost span
hibi retire <claim-id>             # withdraw a claim
hibi supersede --from v1.md --to v2.md
hibi archive --doc old.md --successor new.md

Every suspect verdict carries a remediation menu: a recommended action id and an ordered actions list, each with a command when Hibi can perform the step.

Output is JSON when piped and human-readable on a TTY. --format human|compact|json|json-pretty overrides; --json is short for --format json. --explain adds the evidence tail; --no-hints drops the remediation menu. hibi <cmd> --help prints that command’s options.

Verdicts

The claim model, the five anchor states, the gates rule, and the exit codes.