Wie es funktioniert

Diese Seite erklärt die Mechanik hinter dem Report: was lokal erfasst wird, was als git note gespeichert wird und wie diese Daten in PR Report und Dashboard landen. Du musst nicht jedes Detail kennen, um Agent Note zu nutzen; hier findest du aber das Modell, wenn etwas unerwartet aussieht.

Datenfluss

1. PromptFrag deinen Coding-Agent

Hooks erfassen den Prompt und die Turn-ID.

→

2. EditDie KI ändert Dateien

Hooks oder Transcripts protokollieren berührte Dateien und Attribution-Signale.

→

3. CommitDie Note wird geschrieben

git commit fügt den Trailer ein und schreibt die Git-Note.

→

4. ShareMit dem Code teilen

git push sendet refs/notes/agentnote an das Remote.

Wenn die generierten Git-Hooks installiert sind, kannst du in den meisten Repositories einfach weiter git commit und git push verwenden. Cursor stellt Prompt-/Response-Paare auch aus lokalen Transcripts wieder her und kann Commits weiter verfolgen, wenn Git-Hooks nicht verfügbar sind.

Speicher

Ebene 1: Lokale temporäre Daten

Sitzungsdaten in .git/agentnote/sessions/. JSONL-Dateien für Prompts, Änderungen und Blob-Hashes. Werden nach jedem Commit rotiert. Werden nie gepusht.

Ebene 2: Git Notes

Dauerhafte Aufzeichnung in refs/notes/agentnote. Ein JSON pro Commit. Push-, fetch- und teamfähig.

Sitzungsdateien

Datei	Zweck
prompts.jsonl	Ein Prompt pro Zeile mit Turn-Nummer
changes.jsonl	Von der KI berührte Dateien mit Post-Edit-Blob-Hashes
pre_blobs.jsonl	Dateistand vor jeder KI-Bearbeitung
heartbeat	Zeitstempel der Sitzungsaktivität
turn	Monotoner Zähler, der bei jedem Prompt erhöht wird

Note Schema

{
  "v": 1,
  "agent": "claude",
  "session_id": "a1b2c3d4-...",
  "timestamp": "2026-04-02T10:30:00Z",
  "model": "claude-sonnet-4-20250514",
  "interactions": [
    {
      "prompt": "JWT-Auth-Middleware implementieren",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "Die vorherige Antwort erklärt, warum diese Middleware geändert werden muss." }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "Ich erstelle die 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 }
  }
}

Attributionsmodi

Claude Code

Meist line-level. Agent Note vergleicht den Dateistand vor und nach jedem KI-Edit und zieht spätere menschliche Änderungen wieder vom finalen Diff ab.

Codex CLI

Startet als file-level. Auf line-level wechselt es nur, wenn die Patch-Zahlen im Transcript zum finalen Commit-Diff passen.

Cursor

Startet als file-level. Auf line-level wechselt es nur, wenn die Edit-Zahlen passen und die finale Datei noch dem letzten KI-Edit entspricht.

Gemini CLI

Zeichnet Prompt / Response und file-level Attribution über Hooks und Transcript-Parsing auf. Ein line-level Upgrade gibt es noch nicht.

Wie 📝 Context gesammelt wird

📝 Context ist ein reiner Anzeigehinweis für kurze Prompts wie “continue” oder “mach den nächsten Schritt”. Er macht den Prompt verständlicher, ohne die Attribution zu ändern.

• reference context kommt aus der unmittelbar vorherigen Response, wenn sie einen geänderten Dateipfad, Dateinamen oder Code-Bezeichner aus dem finalen Diff erwähnt.
• scope context kommt aus der aktuellen Response, wenn die ersten Zeilen den Arbeitsumfang klar beschreiben.
• Agent Note nutzt Zustimmungswörter wie yes, continue oder お願いします nicht als Auswahlregel. Ohne konkreten Datei- oder Code-Hinweis wird Context ausgelassen.
• Context ändert nie files_touched, prompt ownership, AI Ratio, attribution method oder ob eine git note gespeichert wird.

Agent Note vs Entire

Agent Note und Entire lösen verwandte, aber unterschiedliche Probleme.

• Agent Note verbindet git commits mit dem Gespräch mit der KI, das sie erzeugt hat. Entire ist ein breiteres checkpoint product mit rewind / resume workflows.
• Agent Note speichert den permanenten Record in refs/notes/agentnote; temporäre Session-Dateien bleiben unter .git/agentnote/. Entire stellt checkpoint metadata und eine hosted web application in den Mittelpunkt.
• Das Agent Note Dashboard ist optionales static GitHub Pages, gestützt auf git notes. Agent Note kann ohne hosted service genutzt werden.
• Agent Note stellt keinen alten workspace state wieder her. Es optimiert reviewability: warum ein commit geändert wurde, welche prompts beteiligt waren und wie viel diff AI-authored ist.

Tipp

Prompt-Listen stammen aus dem Gesprächsfenster von Commit zu Commit, nicht aus dem gesamten Sitzungsverlauf. Agent Note behält nützliche Planungs-, Klärungs- und Review-Prompts für den aktuellen Commit und entfernt zitierte Prompt-Historie sowie Edit-Turns, die in diesem Commit nicht überlebt haben.

Hinweis

Häufige generated artifacts werden nach bestem Wissen aus dem Nenner von AI Ratio ausgeschlossen, wenn konkrete Signale vorliegen, etwa Framework-/Cache-Pfade, generated Dateinamen oder -suffixe und Header in committeten Dateien. Generische Verzeichnisnamen wie build/, dist/, gen/, generated/ und target/ reichen allein nicht aus. Wenn dein Repository Bundles oder generated outputs committet, die sichtbar bleiben, aber die AI Ratio nicht beeinflussen sollen, liste sie in der .agentnoteignore im Repository-Root.

Sitzungslebenszyklus

Ereignis	Was passiert
SessionStart	Erstellt das Sitzungsverzeichnis und schreibt den Heartbeat
UserPromptSubmit	Hängt den Prompt an, erhöht den Turn-Zähler und rotiert Logs
PreToolUse Edit/Write	Erfasst synchron den Pre-Edit-Blob-Hash
PostToolUse Edit/Write	Erfasst den Post-Edit-Blob-Hash und den Dateipfad
Stop	Protokolliert das Stop-Ereignis (Heartbeat bleibt aktiv — Stop = Ende der Antwort, nicht Ende der Sitzung)

Hinweis

Plain Git hooks verlangen eine frische Session mit file evidence, bevor sie Trailer einfügen. Wenn der aktuelle Agent transcript vertrauenswürdig ist, kann Agent Note trotzdem commit-level attribution speichern, auch wenn exakte per-prompt file touches fehlen.

Tipp

Agent Note merkt sich, welcher Agent die Sitzung geführt hat. Sitzungsmetadaten speichern den aktiven Adapter, damit show, status und die Commit-Aufzeichnung später das richtige Transcript-Format auflösen können.

Git Notes

Git Notes erscheinen nicht in Branch-Listen, in der GitHub-Oberfläche oder in CI — sie sind aber push- und fetchbar.

# Mit dem Team teilen
git push origin refs/notes/agentnote

# Vom Remote holen
git fetch origin refs/notes/agentnote:refs/notes/agentnote

# Note anzeigen
git notes --ref=agentnote show <commit>

Tipp

agent-note init konfiguriert den Auto-Fetch, und der pre-push Hook übernimmt den Auto-Push. Manuelle Befehle sind nicht nötig.