MANDATORY gate BEFORE running jq on any .jsonl under ~/.claude/ or reading past CC sessions. Invoke FIRST when introspecting conversations, searching session history, parsing transcripts, or building tools that read ~/.claude/projects/ data. Provides the CC JSONL schema reference and `deglacer` CLI tool — prevents the 54-attempt fumble pattern where Claudes guess at field names. Triggers on 'what happened last session', 'find when we discussed', 'parse session', 'read conversation', 'session history', 'token usage', 'deglacer'. Do NOT use for git history (use git log) or your own current-session context. (user)
MANDATORY gate BEFORE running jq on any .jsonl under ~/.claude/ or reading past CC sessions. Invoke FIRST when introspecting conversations, searching session history, parsing transcripts, or building tools that read ~/.claude/projects/ data. Provides the CC JSONL schema reference and `deglacer` CLI tool — prevents the 54-attempt fumble pattern where Claudes guess at field names. Triggers on 'what happened last session', 'find when we discussed', 'parse session', 'read conversation', 'session history', 'token usage', 'deglacer'. Do NOT use for git history (use git log) or your own current-session context. (user)
allowed-tools
["Bash","Read","Grep","Glob"]
Déglacer — CC Session JSONL Reference
Deglazing the pan to lift the fond — extracting the good bits from past sessions.
When to Use This Skill
You are working with Claude Code session data. This includes:
Introspecting past conversations — "what did we discuss last session?", "when did we first talk about X?"
Searching session history — finding sessions that mention a topic, tool, or file
Building tooling — anything that reads ~/.claude/projects/ session data
Debugging session format — understanding why a jq query returns nothing
Do NOT guess at the schema. The CC JSONL format has multiple entry types, triple-duty user entries, streaming-duplicated message.ids, and inconsistent field presence across versions. This reference is the source of truth.
When NOT to Use
Git history — use git log / git blame for code change history
Current conversation state — you already have context, no need to parse your own session
Non-CC JSONL files — this schema is specific to Claude Code sessions
deglacer — The CLI Tool
deglacer is the CC JSONL extraction CLI, installed as a uv tool. Use it instead of raw jq for structured extraction.
DRAGON: Multiple entries share the same message.id. CC streams
incremental updates. Merge content blocks by message.id, dedup
tool_use blocks by their id field. deglacer handles this automatically.
DRAGON: stop_reason is null in older sessions (pre-v2.1.79).
user entries (TRIPLE DUTY)
The user type serves three purposes. Discriminate with:
Subtype
How to detect
Content shape
Human message
typeof content === "string", has permissionMode
String
Tool result
Has toolUseResult
Array of {type: "tool_result"}
Skill/system injection
isMeta: true
Array of {type: "text"}
Human message:
{"type":"user","message":{"role":"user","content":"the actual human text"},"permissionMode":"default","promptId":"..."}
Tool result:
{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_...","content":"output text"}]},"toolUseResult":{/* shape varies by tool */},"sourceToolAssistantUUID":"..."}
