How It Works

This page explains the mechanics behind the report: what is captured locally, what becomes a git note, and how that data reaches PR Report and Dashboard. You do not need every detail to use Agent Note, but this is the place to check the model when something looks surprising.

Data Flow

1. PromptAsk your coding agent

Hooks capture the prompt and turn id.

→

2. EditAI changes files

Hooks or transcripts record the changed files and the clues used for attribution.

→

3. CommitRecord the note

When recordable session data exists, git commit injects the trailer and writes the git note.

→

4. SharePush notes with the code

git push sends refs/notes/agentnote to the remote.

With the generated git hooks installed, most repos can keep using plain git commit and git push. Cursor can also recover prompt / response pairs from local transcripts, and its shell hooks can keep tracking commits when git hooks are unavailable.

Storage

Layer 1: Local Temp

Session data in .git/agentnote/sessions/. JSONL files for prompts, changes, and blob hashes. Rotated after each commit. Never pushed.

Layer 2: Git Notes

Permanent record in refs/notes/agentnote. One JSON per commit. Pushable, fetchable, shareable with the team.

Session Files

File	Purpose
prompts.jsonl	One prompt per line with turn number
changes.jsonl	Files touched by AI with post-edit blob hashes
pre_blobs.jsonl	File state before each AI edit
heartbeat	Session activity timestamp
turn	Monotonic counter incremented on each prompt

Note Schema

{
  "v": 1,
  "agent": "claude",
  "session_id": "a1b2c3d4-...",
  "timestamp": "2026-04-02T10:30:00Z",
  "model": "claude-sonnet-4-20250514",
  "interactions": [
    {
      "prompt": "Implement JWT auth middleware",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "The previous response explains why this middleware needs to change." }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "I'll create the middleware...",
      "files_touched": ["src/auth.ts"],
      "tools": ["Edit"]
    }
  ],
  "files": [
    { "path": "src/auth.ts", "by_ai": true },
    { "path": "CHANGELOG.md", "by_ai": false }
  ],
  "attribution": {
    "ai_ratio": 73,
    "method": "line",
    "lines": { "ai_added": 146, "total_added": 200, "deleted": 12 }
  }
}

Attribution Modes

Claude Code

Usually line-level. Agent Note compares the file before and after each AI edit, then removes later human edits from the final diff.

Codex CLI

Starts as file-level. It upgrades to line-level only when the transcript patch count matches the final commit diff.

Cursor

Starts as file-level. It upgrades to line-level only when edit counts match and the final file still matches the last AI edit.

Gemini CLI

Records prompt / response and file-level attribution from hooks and transcripts. Line-level attribution is not available yet.

How 📝 Context Is Collected

📝 Context is a display-only note for short prompts such as “continue” or “do the next one”. It helps readers understand the prompt without changing attribution.

• reference context comes from the immediately previous response when it mentions a changed file path, file name, or code identifier from the final diff.
• scope context comes from the current response when its opening lines clearly name the work being done.
• Agent Note does not use approval words such as yes, continue, or お願いします as selection rules. If there is no concrete file or code clue, it skips Context.
• Context never changes files_touched, prompt ownership, AI Ratio, attribution method, or whether a git note is saved.

Agent Note vs Entire

Agent Note and Entire solve related but different problems.

• Agent Note links git commits to the AI conversation that produced them. Entire is a broader checkpoint product with rewind / resume workflows.
• Agent Note stores the permanent record in refs/notes/agentnote; temporary session files stay under .git/agentnote/. Entire centers checkpoint metadata and a hosted web application.
• Agent Note’s Dashboard is optional static GitHub Pages backed by git notes. You can keep using Agent Note without a hosted service.
• Agent Note does not try to restore an old workspace state. It focuses on reviewability: why a commit changed, which prompts were involved, and how much of the diff was AI-authored.

Tip

Prompt lists come from the commit-to-commit conversation window, not the whole session backlog. Agent Note keeps the useful planning, clarification, and review prompts for the current commit, while trimming quoted prompt-history blocks and edit turns that did not survive into this commit.

Note

Common generated artifacts are excluded from the AI Ratio denominator on a best-effort basis using specific signals such as framework/cache paths, generated filenames/suffixes, and committed file headers. Generic directory names like build/, dist/, gen/, generated/, and target/ are not enough by themselves. If your repository commits bundles or generated outputs that should stay visible but not affect AI Ratio, list them in the repository-root .agentnoteignore.

Session Lifecycle

Event	What happens
SessionStart	Creates session directory, writes heartbeat
UserPromptSubmit	Appends prompt, increments turn counter, rotates logs
PreToolUse Edit/Write	Captures pre-edit blob hash (synchronous)
PostToolUse Edit/Write	Captures post-edit blob hash + file path
Stop	Logs stop event (heartbeat stays active — Stop = response end, not session end)

Note

Plain Git hooks require fresh session file evidence before injecting trailers. When the current Agent transcript is trusted, Agent Note can still keep commit-level attribution even if exact per-prompt file touches are unavailable.

Tip

Agent Note is agent-aware. Session metadata stores the active adapter, so show, status, and commit recording can resolve the right transcript format later.

Git Notes

Git notes are invisible to branch listings, GitHub UI, and CI — but pushable and fetchable.

# Share with team
git push origin refs/notes/agentnote

# Fetch from remote
git fetch origin refs/notes/agentnote:refs/notes/agentnote

# View a note
git notes --ref=agentnote show <commit>

Tip

agent-note init configures auto-fetch and the pre-push hook handles auto-push. No manual commands needed.

For storage boundaries, visibility, and what is never uploaded to an Agent Note service, see Data & Privacy.