Use h5i as shared versioned context for AI coding agents

Install and initialize

h5i stores sidecar data under Git-owned state and pushable refs/h5i/* refs. Run h5i init once per repository.

$ curl -fsSL https://raw.githubusercontent.com/Koukyosyumei/h5i/main/install.sh | sh
# or build directly from source
$ cargo install --git https://github.com/Koukyosyumei/h5i h5i-core

$ cd your-project
$ h5i init

Claude Code workflow

Claude Code gets the richest automation path. h5i hook setup prints the local hook and MCP configuration. Hooks trace file reads and edits, session start restores context, stop checkpoints progress, and MCP exposes h5i commands as native tools.

$ h5i hook setup
$ h5i recall context init --goal "ship OAuth login safely"

# Before editing a non-trivial file:
$ h5i recall context relevant src/auth.rs

# Record a reusable fact when the agent just established one:
$ h5i capture claim "OAuth token refresh only src/auth.rs + src/session.rs" \
  --path src/auth.rs --path src/session.rs

Codex workflow

Codex does not need a hook API. h5i reads the active Codex JSONL session and backfills file reads, searches, listings, and patch edits into the context trace.

$ h5i codex prelude
# work normally
$ h5i codex sync
$ h5i codex finish --summary "implemented retry-aware API client"

Commit with provenance

Use h5i capture commit when staged changes are ready. It records the prompt, model, agent, decisions, tests, causal links, and audit output with the Git commit.

$ git add src/auth.rs tests/auth.rs
$ h5i capture commit -m "add token refresh flow" \
  --agent codex \
  --model gpt-5 \
  --prompt "finish OAuth token refresh with tests" \
  --test-cmd "cargo test" \
  --audit

Recall what happened

Reviewers and follow-up agents use recall commands to recover the history Git cannot show by itself.

$ h5i recall log --limit 10
$ h5i recall blame src/auth.rs --show-prompt
$ h5i recall context show --depth 2
$ h5i recall notes coverage --commit HEAD
$ h5i recall resume

Audit risk before merge

audit commands split high-precision quality signals from informational shape signals. A large diff alone should not block review; a large diff with blind edits, secrets, test regression, or code execution deserves attention.

$ h5i audit review --limit 50
$ h5i audit scan
$ h5i audit policy check
$ h5i audit compliance --since 2026-01-01 --format html --output audit.html

Publish context into the PR

The shared context is useful before, during, and after review. h5i share pr post is one UI for it: a sticky comment containing review-focus files, goal, evidence, checklist, audit signals, THINK/NOTE highlights, and per-commit provenance.

$ h5i share pr post --style review
$ h5i share pr body --style review
$ h5i share pr post --style replay --dry-run

# Sync sidecar refs with teammates:
$ h5i share push
$ h5i share pull

PR styles

Use --style review when reviewers need a triage-oriented view of the context. Use receipt for a screenshot-friendly summary, detective for a narrative brief, replay when the reasoning DAG should be the hero, and minimal for quiet internal provenance.