flatten_session
Reduce session file size and context tokens by moving bulky tool results to a sidecar file, preserving the full conversation for lossless restoration.
Instructions
Flatten a session: move bulky tool results (large text output and base64 image/screenshot blocks) out of the session JSONL into a sidecar file, leaving a lightweight [FLATTENED ...] marker in their place. The conversation reads identically — every prompt and event stays verbatim — but resumes with far fewer context tokens. Crash-safe (atomic rewrite + idempotent sidecar) and fully reversible via unflatten_session. Reports diskBytesSaved (file shrink, affects --resume parse speed) and contextTokensSaved out of contextTokensTotal (the number that matters for compaction); token savings are estimated locally, or exact when ANTHROPIC_API_KEY is set. Accepts a UUID, "last", "last N", or "current". Refuses to rewrite a session edited in the last 10s (likely live) unless force=true.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No | Session UUID, "last", "last N", or "current" (most recent). Any other value is treated as a keyword matched against first messages and branch names, and may flatten MULTIPLE matching sessions — prefer a UUID here. | |
| sessionId | No | camelCase alias for session_id (the list_sessions output uses this name). Use session_id; this is accepted so a camelCase call does not fail validation. | |
| project_dir | No | Absolute path to project. Default: the project the CLI runs in (cwd) | |
| min_size | No | Only flatten tool results larger than N bytes | |
| dry_run | No | Report what would be flattened without modifying files | |
| force | No | Flatten even if the session was modified seconds ago (may be live). Use only when the session is idle. | |
| include_tool_use_result | No | Also flatten the top-level toolUseResult mirror Claude Code keeps per result line (roughly doubles disk savings; lossless & restorable). Set false to only touch message.content. |