Skip to main content

Interoperability

git-byline can exchange committed attribution with two public formats:

  • Git AI Standard v3.0.0, stored in refs/notes/ai.
  • Agent Trace 0.1.0, emitted as a JSON record.

All conversion is local. The binary does not fetch conversations, prompts, models, or other remote resources.

Git AI Standard v3​

The implementation targets Git AI Standard v3.0.0. The note contains the standard attestation section followed by the JSON metadata section. Export writes authorship/3.0.0 and the selected commit SHA as base_commit_sha.

The mapping is:

Git AI recordgit-byline attribution
s_<14hex>::t_<14hex> with a sessions recordai, with agent from agent_id.tool, plus model and the s_ session ID
h_<14hex> with a humans recordhuman
Bare 16-hex or 7-hex key with a prompts recordai, with agent and model from the prompt record and the bare key as session
human-override rangehuman, using the deterministic synthetic human identity
No attestation for a committed lineuntracked

Import resolves each path against the committed blob. It rejects missing, invalid, overlapping, or out-of-bounds ranges. Lines not present in the Git AI attestation are added as untracked, so the resulting byline note keeps full ordered coverage.

Git AI v3.0.0 implementations SHOULD accept 7-character legacy hash keys for backward compatibility with versions before v1.0. git-byline accepts both 7-hex and 16-hex legacy keys.

When exporting, git-byline always derives a session ID as:

s_ + first 14 hex characters of SHA-256(tool + ":" + conversation_id)

An input conversation ID already having the s_ form is hashed again. Git AI trace IDs use t_ plus the first 14 hex characters of SHA-256("git-byline:checkpoint:" + checkpoint_sequence). This replaces the Git AI specification's random trace ID so identical local state produces identical output. Trace IDs are emitted only when the AI range matches a real checkpoint sequence. An unmatched AI range is omitted from the Git AI attestation and therefore imports as untracked. Human records use a deterministic git-byline author identity. Attribution notes do store a human identity token per range, but it is deliberately not exported: the Git AI author field is a free-form author string, and mapping a reduced token into it would publish a person under a name the note never recorded. Import likewise leaves the identity empty rather than inventing one from a foreign author string.

Git AI export quotes paths containing spaces, tabs, or newlines. It also quotes paths beginning with a double quote so export and import preserve the path.

Agent Trace 0.1​

The writer targets Agent Trace 0.1.0. It records:

  • vcs.type as git;
  • vcs.revision as the exported commit SHA;
  • line ranges grouped into conversations by attribution;
  • ai, human, and unknown contributors for AI, human, and untracked byline ranges;
  • human-override ranges are exported as human because committed content is human-authored;
  • deterministic UUID and commit timestamp values.

Agent Trace has no required storage location. The export keeps local agent and session values in the optional comarch.git-byline metadata member. It never stores prompts, transcripts, raw hook payloads, or file contents in the trace.

Commands​

Export HEAD to stdout:

git byline export --format gitai
git byline export --format agent-trace

Select a revision:

git byline export --format gitai --commit <rev>

Write a private, new file. Existing files are never replaced:

git byline export --format agent-trace --output trace.json

Import the Git AI note on HEAD:

git byline import --format gitai

Import a first-parent revision range without writing:

git byline import --format gitai --range <rev-range> --dry-run

Import writes only to refs/notes/byline. A different existing byline note is never overwritten. The commit is skipped and a warning is written to stderr. An identical existing note is left unchanged without a warning. Malformed or incompatible Git AI notes are skipped with a warning.