List Claude Code sessions for a project with metadata (sessionId, branch, message count, file size, first user message).

Search past sessions by keyword, date range, or git branch. Scans prose, tool I/O, and flatten sidecars; returns matching sessions with a match count and a text preview.

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.

Retrieve original tool result content from a flattened session. 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 its sidecar, restoring the session to its pre-flatten state. Snapshots the flattened file to .preunflatten.bak first.

Reclaim disk by deleting leftover flatten artifacts (.bak, .preunflatten.bak, and stale .tmp- files) for a project. By default keeps .flat.jsonl sidecars (retrieve_flattened needs them) and runs dry. Set include_sidecars=true only when you no longer need to retrieve/unflatten those sessions.