claude-code - 💡(How to fix) Fix Docs: publish JSONL session schema for ~/.claude/projects/ [1 participants]

TL;DR

Documenting the schema for session transcripts at ~/.claude/projects/**/*.jsonl would provide a reliable foundation for building performance tooling, analytics, and introspection scripts.

Guidance

• Identify and document the top-level record types and their structures, including user, assistant, tool_result, tool_error, and queue-operation, to establish a clear understanding of the data.
• Focus on documenting the assistant records, including message.model, message.content[] blocks, and message.usage with cache token fields, as these seem to be crucial for performance and usage analysis.
• Consider creating a CHANGELOG entry whenever the schema evolves to notify users of changes and help them adapt their tools and scripts accordingly.
• Develop a process for maintaining and updating the schema documentation to ensure it remains accurate and reliable over time.

Example

No specific code snippet can be provided without more context, but an example of how the schema documentation could be structured might look like a JSON schema definition or a table outlining the fields and their descriptions for each record type.

Notes

The lack of a published schema currently forces developers to reverse-engineer the structure from live session files, which is error-prone and breaks when the schema changes. Documenting the schema would significantly improve the reliability and maintainability of tools and scripts built on top of these session transcripts.

Recommendation

Apply a workaround by starting to document the schema based on current understanding and known record types, and request that a CHANGELOG entry be made for any future schema changes to ensure that all users can adapt their tools and scripts accordingly. This approach allows for immediate progress while acknowledging the need for ongoing maintenance and updates to the schema documentation.