> ## 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.

# Integrating Hibi into CI, Git Hooks, and Agent Loops

> Run hibi check in GitHub Actions, a git hook, or an agent session, and act on its exit code: 0 clean, 2 gating, 1 error.

Hibi is one command with one exit-code contract, so it fits anywhere a non-zero exit can block: CI, a git hook, or an agent's session hooks. `hibi check` flags; a person or agent decides what the prose should now say.

| Code | Meaning                                                                                                                               |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | clean, or only `moved` warnings                                                                                                       |
| `2`  | a gating verdict on an enforced claim (`changed`, `orphaned`, `ambiguous`, `expired`, `refuted`); or a warning under `--fail-on warn` |
| `1`  | operational error (no store, unknown flag, unknown `--since` ref)                                                                     |

## GitHub Action

The repository is itself a composite action. It installs Bun and runs `hibi check` (falling back to `bunx @npupko/hibi` when no binary is on PATH).

```yaml theme={null}
name: docs-drift
on: [push, pull_request]

jobs:
  hibi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # needed when `since` compares refs
      - uses: npupko/hibi@v0
        with:
          fail-on: gating
          since: origin/${{ github.base_ref }}
```

### Inputs

<ParamField path="fail-on" type="string" default="gating">
  `gating`, `warn`, or `never`. Same vocabulary as the CLI's `--fail-on`.
</ParamField>

<ParamField path="since" type="string">
  A git ref. When set, the action runs `check --since <ref>` and evaluates only the claims that touch a file changed since that ref.
</ParamField>

<ParamField path="write" type="boolean" default="false">
  When `true`, passes `--write` so banners are stamped into suspect documents. Commit the result separately.
</ParamField>

<ParamField path="run-verifiers" type="boolean" default="false">
  When `true`, passes `--run-verifiers`. Verifiers execute repo-committed commands, so this stays off unless you opt in.
</ParamField>

<ParamField path="working-directory" type="string" default=".">
  The directory holding the `.claims/` store.
</ParamField>

A ready-made workflow file ships with the Claude Code plugin at `plugins/hibi-cli/skills/hibi/assets/hibi-ci.yml`.

### Strictness

| `fail-on` | Build fails when                                |
| --------- | ----------------------------------------------- |
| `gating`  | any enforced claim gates. The default.          |
| `warn`    | any enforced claim gates or has a `moved` side. |
| `never`   | never. The JSON still reports everything.       |

## Gating a plan with `coverage --fail-uncovered`

```sh theme={null}
hibi coverage --doc plan.md --fail-uncovered   # exit 2 while any sentence is uncovered
```

An uncovered region is a sentence no claim backs. Hibi does not judge whether code implements a sentence; the author anchors each promise to its code, and `--fail-uncovered` checks that the anchoring is complete.

## git hooks

<CodeGroup>
  ```bash pre-push theme={null}
  #!/bin/sh
  hibi check --since origin/main || {
    echo "hibi: documentation drift detected; re-verify before pushing." >&2
    exit 1
  }
  ```

  ```bash pre-commit theme={null}
  #!/bin/sh
  hibi check || {
    echo "hibi: documentation drift detected; re-verify before committing." >&2
    exit 1
  }
  ```
</CodeGroup>

`check --since <ref>` suits a pre-push hook; plain `check` suits pre-commit. Register the same command in lefthook or husky if you use one. Leave `--write` off in a hook unless you want each developer to re-stamp banners locally.

## Agent sessions

An agent reads an instruction file and trusts it. Two moments close the gap:

<Steps>
  <Step title="Before trusting a document">
    `hibi check --doc CLAUDE.md`. Exit 2 means a sentence in that file no longer matches the code. The agent reads the verdicts and does not act on the flagged sentences as written.
  </Step>

  <Step title="After editing code">
    `hibi check --since origin/main`. The `documents` array names the files whose sentences the edit invalidated. The agent fixes the prose and runs the `command` from each verdict's remediation menu.
  </Step>
</Steps>

Both commands are read-only. For instruction files the stamped banner is one line, `STALE — N claim(s); run hibi check --doc <path>`, so the always-loaded file stays short (see [Banners](/banners)). The Claude Code skill that teaches these loops is on the [Claude Code](/claude-code) page.

An MCP shim that serves verdicts must recompute them on every request. A cached index would itself drift.

<Tip>
  Add `--no-hints` (or `HIBI_ADVICE=0`) for shorter CI logs. Add `--explain` when you need the evidence behind a verdict.
</Tip>

## Where to go next

<CardGroup cols={2}>
  <Card title="CLI reference" icon="terminal" href="/cli-reference">
    Every flag on `check` and `coverage`.
  </Card>

  <Card title="Verdicts" icon="scale-balanced" href="/verdicts">
    The gates rule behind the exit codes.
  </Card>

  <Card title="Banners" icon="stamp" href="/banners">
    What `--write` stamps into a document.
  </Card>

  <Card title="Claude Code skill" icon="wand-magic-sparkles" href="/claude-code">
    The Agent Skill that teaches the two moments above.
  </Card>
</CardGroup>