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

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

fail-on · string · default: "gating"

gating, warn, or never. Same vocabulary as the CLI’s --fail-on.

since · 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.

write · boolean · default: "false"

When true, passes --write so banners are stamped into suspect documents. Commit the result separately.

run-verifiers · boolean · default: "false"

When true, passes --run-verifiers. Verifiers execute repo-committed commands, so this stays off unless you opt in.

working-directory · string · default: "."

The directory holding the .claims/ store.

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

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

pre-push

#!/bin/sh
hibi check --since origin/main || {
  echo "hibi: documentation drift detected; re-verify before pushing." >&2
  exit 1
}

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:

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

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

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). The Claude Code skill that teaches these loops is on the Claude Code page.

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

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

Where to go next

CLI reference

Every flag on check and coverage.

Verdicts

The gates rule behind the exit codes.

Banners

What --write stamps into a document.

Claude Code skill

The Agent Skill that teaches the two moments above.