Claude Code sessie-jsonl schema

Definitie

Claude Code slaat elke sessie op als één .jsonl-bestand onder ~/.claude/projects/<cwd-slug>/<sessionId>.jsonl. Elke regel is een JSON-record dat één gebeurtenis (turn, snapshot of metadata) representeert. Dit artikel beschrijft het record-schema zoals geverifieerd op 2026-05-09.

Context

Voor backfill-imports van bestaande Claude Code history naar een knowledge vault is parsing van dit jsonl-formaat noodzakelijk. Het schema is niet officieel gedocumenteerd door Anthropic; deze beschrijving is afgeleid uit directe inspectie van 70+ jsonl-bestanden tijdens de bouw van import-cc-history.py voor LLmWiki-KennisBank v0.2.0.

Kernpunten

Bestandslocatie en naamgeving

Elke project-directory onder ~/.claude/projects/ correspondeert met één Claude Code working-directory. De directory-naam is een slug-encoding van het absolute pad, met slashes vervangen door koppeltekens (bijv. -Users-jvdbreemen-Claude-projects-foo). Binnen elke project-directory staat één jsonl-bestand per sessie. De filename-stem matcht de sessionId UUID die in elke record terugkomt: het bestand IS de sessie, geen verdere groepering nodig.

Record-typen

Elke regel is een JSON-object met een type veld. Geverifieerde waarden:

• permission-mode: instelling van permission-mode aan begin van sessie
• attachment: bestandsbijlage geplaatst in de conversatie
• file-history-snapshot: snapshot van bestand-state op een bepaald moment
• user: gebruiker-turn
• assistant: assistant-turn
• last-prompt: marker voor laatste user-prompt

Schema van conversation-turns

user en assistant records hebben deze velden:

{
  "type": "user" | "assistant",
  "message": {
    "role": "user" | "assistant",
    "content": string | array,
    "model": "claude-opus-4-7" | ...   // alleen op assistant-records
  },
  "timestamp": "2026-05-09T14:32:01.123Z",
  "cwd": "/Users/jvdbreemen/...",
  "sessionId": "uuid-...",
  "version": "1.x.x",
  "gitBranch": "main"
}

Content-veld varianten

message.content is óf:

• Een string: directe user-message in plain text
• Een array van typed blocks: elk block heeft type met waarden text, thinking, tool_use, tool_result. Tool-blocks hebben extra velden zoals name, input, output, is_error.

Bot-generated user-turns

Een belangrijke parsing-valkuil: user-turns met content die alleen tool_result blocks bevat, zijn bot-generated tool replies, geen echte user-prompts. Een importer die op de “eerste user-message” zoekt voor een topic-slug moet doorlopen tot de eerste user-turn met non-empty extracted text. Anders krijg je tool-result-payloads als topic.

Geen sessie-boundaries binnen één file

Elk jsonl-bestand bevat exact één sessie. De sessionId in alle records is identiek aan de filename-stem. Geen extra grouping-logica nodig zoals bij sommige andere CC-versies of vendor-formaten.

Verbanden

• Zie ook: wiki-karpathy-llm-wiki (gebruikt dit schema in /import cc)
• Zie ook: wiki-claude-data-locaties (waar dit jsonl staat tov Cowork-data)
• Zie ook: wiki-ingest-pipeline-pattern

Bronnen

van den Breemen, J. (2026). LLmWiki-KennisBank v0.2.0: import-cc-history.py [GitHub]. https://github.com/Jvdbreemen/LLmWiki-KennisBank/blob/v0.2.0/scripts/import-cc-history.py

Directe inspectie 70+ jsonl-bestanden onder ~/.claude/projects/ op 2026-05-09 (Claude Code v1.x op macOS Darwin 25.0).

Sessie-herkomst

• raw-sessie-2026-05-09-llmwiki-kennisbank-v020-publicatie