Native tmux session snapshot format for reliable cross-version restoration

Answer the question first

To get a lossless, cross‑version restore of a tmux session, a native snapshot must serialize the following minimal set of public data:

• Session metadata: name, global options that affect layout (e.g., remain-on-exit, history-limit), and attached‑client count.
• Window hierarchy: for each window – index, name, layout string (the printable layout token that tmux emits), and any window‑specific options.
• Pane details: pane‑id, title, working directory, the command that started it (including arguments), environment variables that influence the command, and size hints (rows/cols).
• Scrollable content: the pane’s scrollback buffer, captured via capture-pane or persisted with a history-file.

Process state (open file descriptors, in‑memory data, signal state) is owned by the OS kernel and cannot be restored by tmux alone; external checkpoint/restore tools are required for that.

Designing a version‑agnostic schema

Serialize only the stable public API surface: layout strings, cwd, command, env, pane titles, and scrollback. Avoid internal struct layouts or opaque binary blobs that change with each release. Include a schema-version header so newer tmux binaries can migrate older snapshots. A simple JSON or YAML format is sufficient and human‑readable.

Built‑in vs. pluggable approach

• Built‑in commands (e.g., snapshot-save/snapshot-load) give a single documented format, atomic operations, and reduce the need for external tooling. They require minimal code changes to tmux and a versioned format.
• Pluggable hook (e.g., hook-snapshot) preserves extensibility and lets the community supply the format. It keeps tmux lean but relies on third‑party scripts.
• Hybrid – expose built‑in commands that emit the stable format and provide a hook for external tools to read/write the same file. This is the most flexible path.

Practical steps for a minimal snapshot on your system

1. Enable history persistence so scrollback survives a server kill:

   tmux set-option -g history-file ~/.tmux/history
   

2. Run a short script that dumps the public API into a JSON file:

   #!/usr/bin/env bash
   SESSION=$1
   OUT=$2
   
   # Session options
   opts=$(tmux list-options -t $SESSION -a | sed 's/^[^ ]* //')
   
   # Build JSON
   cat > $OUT <

3. Restore by recreating the session from the JSON (either via a companion script or by feeding the file to tmux source-file if the format is a valid tmux script).

Missing diagnostic detail

To fine‑tune the snapshot format, could you let me know which tmux version you plan to target for both save and load? Features like remain-on-exit and history-file have subtle differences across releases.