{"id":51465084,"url":"https://github.com/npupko/hibi","last_synced_at":"2026-07-06T10:01:07.757Z","repository":{"id":365766186,"uuid":"1273547294","full_name":"npupko/hibi","owner":"npupko","description":"Hibi 日々 — a deterministic, agent-facing CLI that keeps documentation and AI-agent-instruction files from silently going stale.","archived":false,"fork":false,"pushed_at":"2026-06-25T20:02:59.000Z","size":28251,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T21:08:45.750Z","etag":null,"topics":["ai-agents","bun","claude-code","cli","docs-drift","documentation","documentation-testing","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npupko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-18T16:21:15.000Z","updated_at":"2026-06-25T20:02:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/npupko/hibi","commit_stats":null,"previous_names":["npupko/hibi"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/npupko/hibi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npupko%2Fhibi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npupko%2Fhibi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npupko%2Fhibi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npupko%2Fhibi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npupko","download_url":"https://codeload.github.com/npupko/hibi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npupko%2Fhibi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35185688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bun","claude-code","cli","docs-drift","documentation","documentation-testing","tree-sitter"],"created_at":"2026-07-06T10:01:06.937Z","updated_at":"2026-07-06T10:01:07.734Z","avatar_url":"https://github.com/npupko.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/npupko/hibi/main/assets/logo/hibi-wordmark-dark.png\"\u003e\n    \u003cimg alt=\"Hibi 日々\" src=\"https://raw.githubusercontent.com/npupko/hibi/main/assets/logo/hibi-wordmark-transparent.png\" width=\"300\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eCatch documentation that no longer matches your code.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://npupko.mintlify.app\"\u003e\u003cstrong\u003eDocumentation\u003c/strong\u003e\u003c/a\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/npupko/hibi/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/npupko/hibi/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@npupko/hibi\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@npupko/hibi.svg\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003c!-- Uncomment once the first OpenSSF Scorecard run has published results:\n  \u003ca href=\"https://securityscorecards.dev/viewer/?uri=github.com/npupko/hibi\"\u003e\u003cimg src=\"https://api.securityscorecards.dev/projects/github.com/npupko/hibi/badge\" alt=\"OpenSSF Scorecard\"\u003e\u003c/a\u003e\n  --\u003e\n\u003c/p\u003e\n\nHibi tracks **claims**: sentences in your docs and AI-agent instructions that assert how the code behaves. You anchor each claim to the code it describes. When that code changes, `hibi check` flags the claim and can stamp a status banner into the doc, so no reader and no agent acts on a page that has fallen out of sync with the source.\n\nRun it in CI, in a git hook, or as a pre-edit lookup an agent makes before it trusts a doc.\n\n## Install\n\n```sh\n# Prebuilt single-file executable (no runtime needed)\ncurl -fsSL https://raw.githubusercontent.com/npupko/hibi/main/scripts/install.sh | sh\n\n# Or, in a Bun/JS project\nbun add @npupko/hibi\n```\n\n## Quick start\n\n```sh\nhibi init                       # create .claims/ (with a per-repo banner nonce)\n\n# Record a claim: anchor the doc sentence to the constant that backs it (span-first)\nhibi record \\\n  --doc README.md --doc-quote \"Retries are capped at 5 attempts\" \\\n  --code-file src/retry.ts --code-quote \"MAX_ATTEMPTS = 5\" --trust verified --owner alice\n\nhibi record --from-file claims.json  # batch-author many claims (a JSON array; - = stdin)\n\nhibi check                      # verify every claim\nhibi check --write              # verify, and stamp status banners into affected docs\nhibi diff --since origin/main   # what did this change invalidate?\nhibi query --path src/retry.ts  # before editing: which claims cover this file?\nhibi coverage --doc README.md   # which blocks of a doc are backed by a claim vs uncovered?\nhibi reanchor \u003cclaim-id\u003e --doc-quote \"…\" --code-file src/retry.ts  # re-resolve a claim\nhibi reanchor \u003cclaim-id\u003e --doc docs/retry.md --doc-quote \"…\"  # relocate it to another file\nhibi relocate --from v1.md --to v2.md  # batch-move every live claim from one doc to another\nhibi supersede --new v2.md --old v1.md --type supersedes\nhibi doctor                     # store-health report (orphans, stale, duplicates; always exits 0)\nhibi status                     # repo-wide document health overview\nhibi status --doc README.md     # is this one doc still current?\n```\n\n**Output is TTY-aware.** Run hibi in a terminal and you get a rich, grouped-by-document\nreport with color and symbols; pipe or redirect it (or run it in CI) and you get compact\nJSON — so the machine contract is unchanged. Override with the flag vocabulary:\n\n| flag | output |\n|------|--------|\n| _(default)_ | rich human view on a TTY, compact JSON when piped/redirected/CI |\n| `--json` | force compact JSON (the machine contract; what agents read) |\n| `--json --pretty` | indented JSON |\n| `--pretty` | force the rich human view, even when piped |\n| `--compact` | one line per claim (human) |\n| `--color auto\\|always\\|never` | color control (also honors `NO_COLOR` / `FORCE_COLOR`) |\n| `--simple` | ASCII symbols instead of unicode |\n\n`hibi completions \u003czsh\\|bash\\|fish\u003e` prints a shell completion script.\n\n### Exit codes\n\n| code | meaning |\n|------|---------|\n| `0`  | all clean |\n| `2`  | gating: `changed` / `orphaned` / `ambiguous` / `expired` / `refuted` on an enforced claim |\n| `3`  | warning: `moved` or `at-risk` (re-anchorable / advisory) |\n| `1`  | operational error |\n\nTune strictness with `--fail-on gating|warn|tamper|never`.\n\n## How it works\n\nEach claim carries a **bidirectional anchor**: a doc-side bundle (the documented sentence) and one or more code-side bundles (the code it describes). Each side bundles several redundant selectors against one file:\n\n- the quoted text, matched fuzzily so it survives small edits and moves;\n- its byte position, as a cheap hint;\n- the enclosing syntax node, parsed with tree-sitter, so reformatting alone does not trip it;\n- any literal value it mentions, so changing `MAX_ATTEMPTS = 5` to `50` flags the claim even when nothing else moves;\n- an optional `path` or `glob` for coarse coverage, used to size blast radius.\n\nOn `hibi check`, Hibi re-finds each side in your current files and grades the result on two independent axes: **anchor resolution** per side (`unchanged` · `moved` · `changed` · `ambiguous` · `orphaned`), and, on behavioral claims, a **behavioral belief** (`unverified` · `at-risk` · `supported` · `refuted`). A verdict reads e.g. `doc:unchanged · code:changed · behavior:at-risk`. When the selectors agree, you get a confident verdict; when they disagree, Hibi asks you to re-verify instead of guessing. Verdicts are computed live and kept out of the store.\n\n## What you can rely on\n\n- **Deterministic.** No model runs in the check loop, so the same working tree yields the same verdicts every time. The optional semantic resolver advises and nothing more.\n- **A flag means re-verify.** Hibi reports that the evidence under a claim moved. It never declares a doc wrong on its own.\n- **Any file format.** Hibi treats docs as text, so Markdown, plain text, AsciiDoc, or anything else works without a per-format parser.\n- **Offline and shallow-clone safe.** The anchor is its own baseline, so `check` reads your files, never git history.\n\n## Extend it\n\nHibi finds drift through an out-of-process resolver protocol (JSONL-RPC over stdio). The built-in code-anchor resolver speaks the same contract, so you can add your own in any language. SDKs ship for [TypeScript](sdk/ts) and [Rust](sdk/rust). Resolvers stay off until you list them in `.claims/resolvers.json`:\n\n```jsonc\n// .claims/resolvers.json: opt in to the optional semantic advisor (it advises, it does not gate)\n{ \"resolvers\": [\n    { \"name\": \"semantic-advisor\", \"command\": \"bun\", \"args\": [\"run\", \"resolvers/semantic-advisor.ts\"] }\n] }\n```\n\n## Use it with Claude Code\n\nHibi ships a [Claude Code](https://claude.com/claude-code) skill that teaches coding\nagents to use it: set up the store in a fresh repo, record well-anchored claims, run\nthe check/diff/query loops, respond to flagged claims, and wire CI. The repo doubles\nas a plugin marketplace, so installing takes two commands:\n\n```\n/plugin marketplace add npupko/hibi\n/plugin install hibi-cli@hibi\n```\n\nClaude loads the skill when you ask it to work with hibi. You can also invoke it as\n`/hibi-cli:hibi`. The source lives in [`plugins/hibi-cli`](plugins/hibi-cli).\n\n## Develop\n\n```sh\nbun install\nbun run build:grammars      # copy official tree-sitter wasm into grammars/\nbun test                    # the full suite\nbun run build               # single-file executable at dist/hibi\n```\n\nThe data model lives once in Zod (`src/core/model.ts`). The JSON Schemas (`schemas/*.v1.json`) and SDK types come from it via `bun run build:schemas`.\n\n## Contributing\n\nIssues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, commit conventions, and PR expectations. Please follow our [Code of Conduct](CODE_OF_CONDUCT.md), and report security issues per [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © Nick Pupko\n\n---\n\nFor the data model, verdict algorithm, and design rationale, read [`docs/PRD.md`](docs/PRD.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpupko%2Fhibi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpupko%2Fhibi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpupko%2Fhibi/lists"}