Flatten a Claude Code or OpenAI Codex CLI session: move bulky tool results (large text output and, for Claude, 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. Choose the store with agent ("claude" default, or "codex"). Reports diskBytesSaved and contextTokensSaved out of contextTokensTotal. For claude these are estimated locally, or exact when FLATTEN_COUNT_EXACT=1 and ANTHROPIC_API_KEY are both set; for codex the token savings are ALWAYS a local estimate (Anthropic count_tokens does not measure the GPT-5 tokenizer) and contextTokensTotal comes from Codex's own token_count events. With no session_id, flattens the current live session (claude); under codex "current" falls back to "last" (Codex has no live-session linkage). Also accepts a UUID, "last", "last N", or "current"; under codex a UUID reaches any rollout in the tree, while "last"/"last N"/keyword are scoped to the project dir. After flattening, /resume the session (claude) or codex resume the rollout (codex) 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, and set agent to match the session ("claude" default, or "codex"). Returns the original text output, or — for flattened screenshots (claude) — the actual image so you can view it again.

Reverse a flatten: re-inline every flattened tool result 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. Choose the store with agent ("claude" default, or "codex"). Under codex a UUID reaches any rollout in the tree; "last"/"current" are scoped to the project dir ("current" falls back to "last").

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.