Flatten a Claude Code session: move bulky tool results (large text output and base64 image/screenshot blocks) out of the session JSONL into a backup copy, leaving a compact [FLATTENED ...] marker. The conversation reads identically — every prompt and event stays verbatim — but resumes with far fewer context tokens. Crash-safe (atomic rewrite + a single backup holding the complete session) and reversible via unflatten_session. Reports diskBytesSaved and contextTokensSaved out of contextTokensTotal (estimated locally, or exact when FLATTEN_COUNT_EXACT=1 and ANTHROPIC_API_KEY are both set). With no session_id, flattens the current live session; also accepts a UUID, "last", "last N", or "current". After flattening, /resume the session to load the lighter copy.

Retrieve original tool result content from a flattened session, read straight from its backup. When you see [FLATTENED id=XXX tool=Read ... | text NNNB/NNL | session=YYY | ...] in the conversation, call this with the value after "id=" as tool_use_id and the value after "session=" as session_id. Returns the original text output, or — for flattened screenshots — the actual image so you can view it again.

Reverse a flatten: re-inline every flattened tool result (text and images) back into the session JSONL from the backup, restoring the session to its pre-flatten state, then delete the backup so nothing is left behind.

Flatten a raw Anthropic Messages API messages[] array in memory: every bulky tool_result block (large text or base64 image) larger than min_size bytes is swapped for a compact [FLATTENED id=...] marker, and the originals are returned in "extracted". Persist "extracted" yourself — you are the store — and feed it back to unflatten_messages to restore the conversation byte-for-byte. Purely functional: no session file, no disk, no network; the input is never mutated. This is the same engine as the flatten-mcp library export; for production use inside your own process, prefer importing the library so the conversation does not travel over a transport.

Restore a conversation flattened by flatten_messages: re-inlines every tool_result whose content is a [FLATTENED id=...] marker from the matching entry in "extracted", byte-for-byte. Markers with no matching entry are left in place. Purely functional — no disk, no network, input never mutated.