Git Notes vs h5i for AI Coding Workflows

Git notes and h5i solve related but different problems. Git notes are a low-level Git feature for attaching extra information to objects without changing those objects. h5i is an AI-aware workflow layer that stores prompts, agent provenance, context traces, risk signals, memory, and messages in Git-sidecar refs.

What Git notes do well

The official Git documentation describes notes as data attached to objects without touching the objects themselves. By default, notes are stored under refs/notes/commits, and git log can display them alongside commit messages. That makes notes a good fit for lightweight commit annotations.

For AI coding, you could store a prompt or test summary in a note. That is simple, Git-native, and compatible with existing repositories.

Where raw notes stop

Git notes do not define an AI provenance schema. They do not decide how to capture a Claude Code prompt, how to summarize a Codex session, how to rank review risk, how to build a PR body, or how to roll back by natural-language intent. Those are workflow problems on top of storage.

Notes also require teams to design conventions: which ref to use, how to serialize metadata, how to merge conflicts, how to share notes, and how to query them. Git supports configurable note refs and merge strategies, but it does not know what an AI agent is.

What h5i adds

h5i treats Git as the durable substrate and adds AI-specific commands:

• h5i capture commit records prompt, model, agent, tokens, tests, and decisions.
• h5i recall log reads commit history with AI provenance.
• h5i recall blame --show-prompt connects lines back to AI-assisted commit context.
• h5i recall context restores goals, milestones, and reasoning traces.
• h5i audit review and related audit commands surface review signals.
• h5i share push and h5i share pull move h5i refs intentionally.

When Git notes are enough

Use raw Git notes if you only need small human-written annotations on commits and your team is comfortable maintaining its own schema. For example: "generated by Claude Code" or "manual review completed".

When h5i is a better fit

Use h5i when you need repeatable capture, queryable provenance, review packets, multi-agent handoff, memory snapshots, or rollback by intent. Those workflows need more than a place to put text. They need commands, conventions, and records that remain useful across sessions.

FAQ

Does h5i replace Git notes?

No. It uses Git-native sidecar storage ideas but adds an AI workflow and command surface around them.

Can teammates ignore h5i?

Yes. The code history remains ordinary Git. Teammates who do not use h5i can still clone, branch, diff, and merge normally.

Why not put everything in commit messages?

Commit messages are user-facing summaries. AI provenance is structured data: prompt, model, tests, decisions, risk, and context often deserve their own queryable record.

Sources and verification

This article avoids vendor-specific claims that were not checked against primary docs or local h5i CLI behavior.

• Git notes documentation
• h5i AI provenance guide