[DOCS] Cowork/Claude Code `audit.jsonl` session format — no public documentation exists

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://docs.anthropic.com/en/docs/claude-code

Section/Topic

Session storage format: audit.jsonl in local-agent-mode-sessions/

Current Documentation

No documentation exists for the Cowork/Claude Code session storage format.

Sessions are written as JSONL to:

• Windows: %APPDATA%\Claude\local-agent-mode-sessions\<uuid>\audit.jsonl
• macOS: ~/Library/Application Support/Claude/local-agent-mode-sessions/<uuid>/audit.jsonl

The format includes conversation turns, tool use, signatures, token usage, cost fields, and session metadata. None of this is documented anywhere — not in the Claude Code docs, the cookbook, or release notes.

What's Wrong or Missing?

Multiple community efforts depend on understanding this format, and each has had to reverse-engineer it independently:

• #27140 — memory-bridge plugin PR: structured context consolidation at session boundaries. Requires parsing session JSONL to extract learnings for MEMORY.md/CLAUDE.md persistence.
• #20367 — Session files growing unboundedly to multi-GB sizes, causing OOM on startup. Users need to understand the format to build rotation/compaction tooling, since none is provided.
• unified-cowork (https://github.com/yjjoeathome-byte/unified-cowork) — External pipeline that archives, distills, and indexes Cowork sessions for cross-session context restoration.

The format includes fields with no explanation:

• signature / parentSignature — chain-of-integrity validation, undocumented
• input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens — cost-relevant, no formula documented
• sessionId, projectPath, init block structure — metadata extraction requires guesswork
• Content polymorphism: message.content can be a string or an array, parsers must handle both

The format also changes silently between releases with no changelog entry.

Suggested Improvement

1. Publish official documentation for the audit.jsonl schema — or confirm/correct the community-produced spec:

https://github.com/yjjoeathome-byte/unified-cowork/blob/main/cowork-audit-jsonl-format-reference.md
(388 lines, covers message types, field semantics, signature chain logic, cost formulas, edge cases — built from 83 MB of raw transcripts, 744 sessions)

1. Document format changes in release notes when the schema evolves.

1. Define a stability contract — even "this format is internal and may change without notice" is more useful than silence, since it lets tooling authors make informed decisions about how defensively to parse.

Impact

High - Prevents users from using a feature

Additional Context

The community spec linked above was reverse-engineered from 744 Cowork sessions (Opus 4.6, 10 days of usage, 83 MB of raw JSONL). It covers:

• All known entry types (system/init, user, assistant, tool_use_summary, result, rate_limit_event)
• Field semantics and content polymorphism
• Signature chain validation logic
• Cost computation formulas from token fields
• Known edge cases and parser gotchas

The tooling built on it (unified-cowork) includes format validation that detects and surfaces schema changes rather than silently breaking — something the official product does not provide.

Related: #27140, #20367

!Image