Flatten Claude Code or Codex session
flatten_sessionFlatten a Claude Code or OpenAI Codex CLI session by moving large tool results into a backup, reducing context tokens while preserving conversation integrity. Resume with a lighter copy.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | Which agent's session store to target: "claude" (default) or "codex". | claude |
| dry_run | No | Report what would be flattened without modifying files | |
| min_size | No | Only flatten tool results larger than N bytes | |
| breakdown | No | Include the per-tool/resource breakdown of what was flattened. false, true, or "summary" = the aggregated adaptive rows plus byKind/bySlot groupings; "deep" ALSO lists every individual block under its row (tool + arg summary + bytes + per-block token estimate), groups sorted by context tokens then blocks by bytes. Dry runs always include at least the summary; set true/"summary"/"deep" to also get it on a real flatten. | |
| sessionId | No | camelCase alias for session_id (accepted so a camelCase call does not fail validation). | |
| claude_dir | No | Absolute path (or ~/...) to the Claude config dir whose sessions to target — the dir holding projects/. Default: $CLAUDE_CONFIG_DIR if set, else ~/.claude. Applies to agent "claude" only. | |
| codex_home | No | Absolute path (or ~/...) to the Codex home whose sessions to target — the dir holding sessions/. Default: $CODEX_HOME if set, else ~/.codex. Applies to agent "codex" only. | |
| session_id | No | Session UUID, "last", "last N", or "current". Omit to flatten the current live session (claude); under codex "current" falls back to "last". | |
| project_dir | No | Absolute path to project. Default: the project the CLI runs in (cwd). Under codex, scopes "last"/"last N"/keyword to rollouts whose cwd equals this dir. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sessions | Yes | One entry per session flattened (a single entry for one session_id, or several for "last N"). |