> ## Documentation Index
> Fetch the complete documentation index at: https://hibi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```sh Prebuilt binary theme={null}
  curl -fsSL https://raw.githubusercontent.com/npupko/hibi/main/scripts/install.sh | sh
  ```

  ```sh Bun theme={null}
  bun add @npupko/hibi        # then: bunx hibi …
  bunx @npupko/hibi --help    # or run it once without installing
  ```
</CodeGroup>

<Note>
  The npm package targets [Bun](https://bun.sh). For a machine with no JS runtime, use the prebuilt binary.
</Note>

## Record and check a claim

<Steps>
  <Step title="Initialize the store">
    `hibi init` creates a `.claims/` directory with a per-repo banner nonce. One file per claim. Commit it.

    ```sh theme={null}
    hibi init
    ```
  </Step>

  <Step title="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.

    ```sh theme={null}
    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:

    ```sh theme={null}
    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 -
    ```
  </Step>

  <Step title="Check">
    ```sh theme={null}
    hibi check              # verify every claim
    hibi check --write      # also stamp a banner into each suspect document
    ```
  </Step>
</Steps>

`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

```sh theme={null}
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.

<Note>
  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.
</Note>

<Card title="Verdicts" icon="scale-balanced" href="/verdicts">
  The claim model, the five anchor states, the gates rule, and the exit codes.
</Card>