The original title is "Parsing Claude Code's JSONL: patterns for a schema that keeps moving"

Short summary

Claude Code stores conversations in JSONL with no schema stability guarantees. This article covers four hard-learned patterns for parsing internal formats: whitelisting known types to handle schema mutations, preserving unknowns for future re-parsing, fixing UTF-16 surrogates at ingestion, and deduplicating token counts. These turn schema changes from crises into routine maintenance.

• •Claude Code writes JSONL conversation files with an undocumented, frequently-changing schema
• •Whitelist known types and preserve unknown ones to handle schema drift without data loss
• •Normalize at ingestion boundaries (encoding, deduplication) so downstream consumers never see raw messiness

Generated with AI, which can make mistakes.