Flatten Claude Code or Codex session

Added value: +{
+  "default": "claude",
+  "description": "Which agent's session store to target: \"claude\" (default) or \"codex\".",
+  "enum": [
+    "claude",
+    "codex"
+  ],
+  "type": "string"
+}

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "enum": [
+        "summary",
+        "deep"
+      ],
+      "type": "string"
+    }
+  ],
+  "default": false,
+  "description": "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."
+}

Previous value: -"Absolute path (or ~/...) to the Claude config dir whose sessions to target — the dir holding projects/. Default: $CLAUDE_CONFIG_DIR if set, else ~/.claude."New value: +"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."

Added value: +{
+  "description": "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.",
+  "type": "string"
+}

Previous value: -"Absolute path to project. Default: the project the CLI runs in (cwd)"New value: +"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."

Previous value: -"Session UUID, \"last\", \"last N\", or \"current\". Omit to flatten the current live session."New value: +"Session UUID, \"last\", \"last N\", or \"current\". Omit to flatten the current live session (claude); under codex \"current\" falls back to \"last\"."

Added value: +{
+  "additionalProperties": false,
+  "description": "X-ray of what was flattened: adaptive tool/resource rows plus byKind and bySlot groupings, each with the bytes and context tokens freed. Present on every dry run with at least one qualifying block, and on a real flatten only when breakdown=true. contextTokens are exact when tokensExact (per-group count_tokens, requiring the FLATTEN_COUNT_EXACT=1 + ANTHROPIC_API_KEY opt-in), otherwise a local estimate; they are always 0 for the toolUseResult slot (the mirror is disk-only and never in model context).",
+  "properties": {
+    "byKind": {
+      "description": "Grouped by block kind.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "bytes": {
+            "description": "Disk bytes this group frees.",
+            "type": "number"
+          },
+          "contextTokens": {
+            "description": "Context tokens this group frees — exact when tokensExact, else estimated; 0 for toolUseResult-slot blocks.",
+            "type": "number"
+          },
+          "count": {
+            "description": "How many blocks this group holds.",
+            "type": "number"
+          },
+          "key": {
+            "description": "Block kind: \"text\", \"image\", or \"mixed\" (the group key).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "key",
+          "count",
+          "bytes",
+          "contextTokens"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "bySlot": {
+      "description": "Grouped by storage slot.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "bytes": {
+            "description": "Disk bytes this group frees.",
+            "type": "number"
+          },
+          "contextTokens": {
+            "description": "Context tokens this group frees — the full contextTokensSaved on the content row, 0 on the disk-only toolUseResult row.",
+            "type": "number"
+          },
+          "count": {
+            "description": "How many blocks this group holds.",
+            "type": "number"
+          },
+          "key": {
+            "description": "Slot: \"content\" (message.content, in model context) or \"toolUseResult\" (the disk-only mirror).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "key",
+          "count",
+          "bytes",
+          "contextTokens"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "rows": {
+      "description": "Adaptive tool/resource rows: MCP tools collapse per server, heavyweight resources get their own row, and the light tail folds into a single \"other\" row (at most 9 rows). Partitions the flattened blocks exactly. In deep mode each row also carries its individual blocks in .entries.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "bytes": {
+            "description": "Disk bytes this row frees.",
+            "type": "number"
+          },
+          "contextTokens": {
+            "description": "Context tokens this row frees — exact when tokensExact, else estimated; 0 for toolUseResult-slot blocks.",
+            "type": "number"
+          },
+          "count": {
+            "description": "How many blocks this row holds.",
+            "type": "number"
+          },
+          "entries": {
+            "description": "Deep mode only (breakdown=\"deep\"): the individual blocks this row aggregates, sorted by bytes desc — the per-command attribution. Absent in summary mode.",
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "args": {
+                  "description": "Short arg summary (command=…, file_path=…); \"\" when none.",
+                  "type": "string"
+                },
+                "bytes": {
+                  "description": "Disk bytes this block frees.",
+                  "type": "number"
+                },
+                "contextTokens": {
+                  "description": "Per-block net context-token estimate (local; never reconciled to the exact per-group total).",
+                  "type": "number"
+                },
+                "kind": {
+                  "description": "\"text\", \"image\", or \"mixed\".",
+                  "type": "string"
+                },
+                "lineCount": {
+                  "description": "Line count of the block's text projection.",
+                  "type": "number"
+                },
+                "name": {
+                  "description": "Originating tool name of this block.",
+                  "type": "string"
+                },
+                "slot": {
+                  "description": "\"content\" (in model context) or \"toolUseResult\" (disk-only mirror, 0 context tokens).",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "name",
+                "args",
+                "bytes",
+                "kind",
+                "slot",
+                "contextTokens",
+                "lineCount"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "key": {
+            "description": "Row key: a tool family (\"<server> (MCP)\" for MCP tools, else the built-in tool name), or \"other\" for the tail-collapsed row.",
+            "type": "string"
+          },
+          "resource": {
+            "description": "Present only on a resource-promoted row: the raw file_path/path/url value that earned this tool family its own line.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "key",
+          "count",
+          "bytes",
+          "contextTokens"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "tokensExact": {
+      "description": "True when the rows' contextTokens are exact (per-group count_tokens), false when locally estimated.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "tokensExact",
+    "rows",
+    "byKind",
+    "bySlot"
+  ],
+  "type": "object"
+}

Previous value: -"One row per flattened block (id, originating tool name, size, kind, and slot)."New value: +"One row per flattened block — id, originating tool name, arg summary, size, kind, slot, per-block token estimate, and line count. The machine-readable per-command attribution the breakdown aggregates."

Added value: +{
+  "description": "Short arg summary of the originating call (e.g. command=…, file_path=…), same grammar as the marker; \"\" when none.",
+  "type": "string"
+}

Added value: +{
+  "description": "Per-block net context-token estimate (local; not reconciled to the exact per-group total).",
+  "type": "number"
+}

Added value: +{
+  "description": "Line count of the block's text projection.",
+  "type": "number"
+}

Previous value: -[
-  "id",
-  "name",
-  "size",
-  "kind",
-  "slot"
-]New value: +[
+  "id",
+  "name",
+  "args",
+  "size",
+  "kind",
+  "slot",
+  "contextTokens",
+  "lineCount"
+]

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "sessions": {
+      "description": "One entry per session flattened (a single entry for one session_id, or several for \"last N\").",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "backupPath": {
+            "description": "Path to the single self-syncing backup holding the complete inlined session.",
+            "type": "string"
+          },
+          "contextSavingsPercent": {
+            "description": "contextTokensSaved as a percent of contextTokensTotal, or \"n/a\".",
+            "type": "string"
+          },
+          "contextTokensExact": {
+            "description": "True if counted via count_tokens, false if estimated locally.",
+            "type": "boolean"
+          },
+          "contextTokensSaved": {
+            "description": "Context tokens removed from the model context (the number that matters for --resume/compaction).",
+            "type": "number"
+          },
+          "contextTokensTotal": {
+            "description": "Real context size from the last turn API usage, or null if unknown.",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "diskBytesSaved": {
+            "description": "Bytes removed from the .jsonl on disk (speeds --resume parsing).",
+            "type": "number"
+          },
+          "diskSavingsPercent": {
+            "description": "diskBytesSaved as a percent of the original file size.",
+            "type": "string"
+          },
+          "dryRun": {
+            "description": "True when dry_run was set — no files were modified.",
+            "type": "boolean"
+          },
+          "entries": {
+            "description": "One row per flattened block (id, originating tool name, size, kind, and slot).",
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "kind": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "size": {
+                  "type": "number"
+                },
+                "slot": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "name",
+                "size",
+                "kind",
+                "slot"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "flattenedCount": {
+            "description": "How many tool results were flattened (0 on a no-op or dry run with nothing to do).",
+            "type": "number"
+          },
+          "imageBlocksFlattened": {
+            "description": "How many image/screenshot blocks were among them.",
+            "type": "number"
+          },
+          "newSize": {
+            "description": "Session file size after flattening, in bytes.",
+            "type": "number"
+          },
+          "originalSize": {
+            "description": "Session file size before flattening, in bytes.",
+            "type": "number"
+          },
+          "resumeHint": {
+            "description": "Present only when a live session was actually rewritten — reminds you to /resume to load the lighter copy.",
+            "type": "string"
+          },
+          "sessionId": {
+            "description": "The session UUID that was processed.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "sessionId",
+          "dryRun",
+          "flattenedCount",
+          "imageBlocksFlattened",
+          "diskBytesSaved",
+          "diskSavingsPercent",
+          "contextTokensTotal",
+          "contextTokensSaved",
+          "contextSavingsPercent",
+          "contextTokensExact",
+          "originalSize",
+          "newSize",
+          "backupPath",
+          "entries"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "sessions"
+  ],
+  "type": "object"
+}

Previous value: -"Absolute path (or ~/...) to the Claude config dir whose sessions to target — the dir holding projects/, e.g. ~/.claude-2 for a second profile. Default: $CLAUDE_CONFIG_DIR if set (so a server running inside an alternate profile targets it), else ~/.claude."New value: +"Absolute path (or ~/...) to the Claude config dir whose sessions to target — the dir holding projects/. Default: $CLAUDE_CONFIG_DIR if set, else ~/.claude."

Removed value: -{
-  "default": false,
-  "description": "Flatten even if the session was modified seconds ago (may be live). Use only when the session is idle.",
-  "type": "boolean"
-}

Previous value: -"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."New value: +"camelCase alias for session_id (accepted so a camelCase call does not fail validation)."

Previous value: -"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."New value: +"Session UUID, \"last\", \"last N\", or \"current\". Omit to flatten the current live session."

Added value: +{
+  "description": "Absolute path (or ~/...) to the Claude config dir whose sessions to target — the dir holding projects/, e.g. ~/.claude-2 for a second profile. Default: $CLAUDE_CONFIG_DIR if set (so a server running inside an alternate profile targets it), else ~/.claude.",
+  "type": "string"
+}