Reference/Note Schema Structures

Note Schema Structures

The raw composition of ghost and ghost-verified notes

Attribution data lives in Git notes under two refs: refs/notes/ghost and refs/notes/ghost-verified. Each note is attached to a specific commit and travels with it on push.

1. Ghost Note (`ghost/1.0.0`)

Written when at least one agent session was active during the commit. Uses a hybrid format: a plain-text index section (parsed in microseconds, no JSON library needed) separated from the JSON metadata by ---.

Source Code

src/main.cpp
  sess_a1b2c3 5-12,18,22-30
  sess_d4e5f6 30-45
src/utils.cpp
  sess_a1b2c3 1-80
---
{
  "schema": "ghost/1.0.0",
  "commit": "<sha>",
  "sessions": {
    "sess_a1b2c3": {
      "agent":      "claude-code",
      "model":      "claude-sonnet-4-5",
      "author":     "alice <alice@example.com>",
      "ts_start":   1710000000,
      "ts_end":     1710000033,
      "additions":  85,
      "deletions":  3,
      "session_id": "sess_a1b2c3"
    },
    "sess_d4e5f6": {
      "agent":      "cursor",
      "model":      "gpt-4o",
      "author":     "alice <alice@example.com>",
      "ts_start":   1710000040,
      "ts_end":     1710000055,
      "additions":  16,
      "deletions":  2,
      "session_id": "sess_d4e5f6"
    }
  }
}

Plain-text index section

Maps files to session IDs and line ranges. Each line starts with a file path, followed by indented session entries showing which lines that session touched. Line ranges use compact notation: 5-12,18,22-30 means lines 5 through 12, line 18, and lines 22 through 30. The hook binary reads only this section at commit time — parsing is just a fast string scan with no JSON dependency.

JSON metadata section

Field	Meaning
schema	Always `ghost/1.0.0`. Enables forward compatibility if the format evolves.
commit	Full SHA of the commit this note is attached to. Redundant with the note's attachment point but useful for integrity checks.
sessions	Map of session IDs to session metadata. Each entry records the agent, model, author identity, timestamps, and line counts.

Session entry fields

Field	Meaning
agent	Tool name: `claude-code`, `cursor`, etc.
model	The specific LLM model that wrote these lines.
author	Git identity of the developer who ran the agent, in `name <email>` format.
ts_start / ts_end	Unix epoch timestamps for when the session began and ended. Used for ordering concurrent sessions and drift resolution.
additions / deletions	Line count changes attributed to this session. The blamer uses these to calculate AI percentage per commit.
session_id	Random 6-byte hex string. Not linked to the prompt content — keeps the schema simple and avoids leaking sensitive information.

2. Verified Witness Note (`ghost-verified/1.0.0`)

Written unconditionally by the post-commit hook on every commit, regardless of agent activity. This is the note that proves ghost was installed and running during development.

Source Code

{
  "schema":        "ghost-verified/1.0.0",
  "ghost_version": "1.2.0",
  "commit":        "<sha>",
  "ts":            1710000042,
  "author":        "alice <alice@example.com>",
  "sessions":      2
}

Field	Meaning
schema	Always `ghost-verified/1.0.0`.
ghost_version	The exact ghost version that wrote this note. Useful for debugging schema migration issues.
commit	Commit SHA this note is attached to.
ts	Unix timestamp of when the note was written (when the commit happened).
author	The Git author identity from `git config user.name` and `user.email`.
sessions	Number of agent sessions in this commit. `0` means fully human-authored. Should match the count in the ghost note if one exists.

This note is intentionally minimal. It answers one question: was ghost running when this commit was made? Everything else lives in the ghost note.

previousConfiguration

nextAgent Integrations