sessionsnap documentation

Install

You need macOS with cmux 0.64 or newer, and the agents you want to restore on your PATH.

One command installs the latest release:

$ curl -fsSL https://sessionsnap.pawanpaudel.com.np/install.sh | sh

The installer:

1. Picks the build for your system: one universal binary for macOS (Apple Silicon and Intel), or a static binary for Linux x86_64 or arm64. It needs curl, tar, and shasum or sha256sum.
2. Finds the latest release on GitHub, or uses SESSIONSNAP_VERSION.
3. Downloads the archive and its .sha256 file, and stops if the checksum does not match.
4. Installs sessionsnap into ~/.local/bin (copy, then rename, so a running sessionsnap keeps its old file). Running it again upgrades in place.
5. Adds that folder to PATH in your shell's startup file (.zshrc, .bash_profile on macOS or .bashrc on Linux, fish's config.fish, else .profile) if it is not there yet.
6. On macOS, if cmux is on your PATH and a terminal is attached, runs sessionsnap install-cmux, which asks before adding the palette commands; otherwise it says how to run that later. The palette is macOS-only, so on Linux this step is skipped.
7. Prints the installed version and the next steps.

$ curl -fsSL https://sessionsnap.pawanpaudel.com.np/install.sh | SESSIONSNAP_NO_CMUX=1 sh

Manual download

Each release has one archive per platform, each with a .sha256 file next to it. The archive holds the sessionsnap binary.

• sessionsnap-X.Y.Z-universal-apple-darwin.tar.gz (macOS, Apple Silicon and Intel)
• sessionsnap-X.Y.Z-x86_64-unknown-linux-musl.tar.gz (Linux x86_64)
• sessionsnap-X.Y.Z-aarch64-unknown-linux-musl.tar.gz (Linux ARM64)

From source

With Rust 1.96 or newer:

$ cargo install --git https://github.com/pawanpaudel93/sessionsnap

Quick start

$ sessionsnap save work                 # snapshot everything open (new version if "work" exists)
$ sessionsnap show work                 # workspaces and tabs
$ sessionsnap restore work --plan       # what would be reopened
$ sessionsnap restore work              # plan, confirm, reopen what is missing
$ sessionsnap recent                    # agent sessions from the last 24h not open in cmux
$ sessionsnap ui                        # the web UI in the cmux Dock

Every command takes --json (machine-readable output, never prompts) and -y/--yes (answer yes to confirmations). Snapshot names use letters, digits, ., _ and -. A version is written <name>@<v>, for example work@3; without @ it means the latest.

Example output:

$ sessionsnap save work
Saved work v3: 9 workspaces, 29 tabs (+2 tabs, 1 tab moved)
$ sessionsnap restore work --plan
+ create workspace Cascadia (3 tabs)
    + Fix login redirect
    + Review payments PR
    + dev server
~ add to api:
    + Migrate billing tables
= 25 tab(s) already open or skipped
To apply: sessionsnap apply p20261012094107123

Snapshots

Editing

Edits change a saved snapshot, not cmux, and each one is a new version. A tab is <workspace>#<position> (1-based) or <workspace>:"<part of the title>"; a workspace is its name or a unique part of it.

$ sessionsnap tab work Cascadia#4 --move "Cascadia Community"
$ sessionsnap tab work Cascadia --add-session <session-id>
$ sessionsnap tab work Cascadia --add-session <id> --agent opencode
$ echo '[{"op":"tab-move","tab":"Alpha#2","to":"Beta"}]' | sessionsnap edit work --batch -

Batch operations: ws-rename {ws,to}, ws-color {ws,color}, ws-index {ws,index}, ws-remove {ws}, ws-add-live {ws}, ws-from {from,ws}, tab-remove {tab}, tab-rename {tab,to}, tab-index {tab,index}, tab-move {tab,to}, tab-add-session {ws,sessionId,agent?,title?}, tab-add-terminal {ws,cwd,command?,title?}, tab-set-cwd {tab,cwd}, tab-set-session {tab,sessionId,agent?}.

Restoring

A restore compares the snapshot with what is open in cmux and makes a plan: workspaces to create, and tabs to add to workspaces that are already open. Tabs that are already open are skipped. You see the plan before anything opens.

How flags are restored

A restored agent tab runs the agent's resume command with the flags it was started with, from cmux's record (which holds only flags, never the prompt). Flags are kept as saved, except the exact tokens that would pick another session:

• the agent's own resume words and resume flags with the old ID (for example --session <id>, -s <id>, rovodev run, threads continue <id>);
• its continue flag where -c/--continue means that (Claude Code, OpenCode);
• for Claude Code also --session-id <id>, --fork-session and --print/-p;
• for Codex resume <uuid|--last>, fork <uuid|--last>, and a leading exec run.

A tab with an invalid session ID, or an agent sessionsnap does not know, reopens as a plain shell in its folder, with a warning.

Sessions and agents

Claude Code and Codex are fully supported and tested; 15 more agents are resume-only and untested. See the supported agents table.

JSON and exit codes

With --json every command prints one JSON object and never prompts, so scripts and agents should always pass it and read the result rather than the text output. A failure prints an error object:

{"error": {"code": "not-found", "exit": 7, "message": "…"}}

When some restore steps fail, restore and apply exit 1 with the normal result (failed and steps[].error), not the error object. Argument errors print plain text and exit 1.

Web UI

sessionsnap ui serves a small page on http://127.0.0.1:47317/ and shows it in the cmux Dock (the right sidebar). The page runs the same commands as the CLI.

• Snapshots: save what is open, update a snapshot from what is open, delete one.
• Workspaces: rename (double-click), reorder, remove, drag tabs to reorder or move them, add an agent session or a shell tab, add a workspace from cmux or from another snapshot. Edits are previewed and saved together as one version.
• History: compare two versions; restore an older one.
• Restore: tick workspaces and tabs, see what would open, then restore.
• Recent: agent sessions (Claude Code, Codex) from the last days that are not open in cmux.

It runs while its terminal is open and stops after 30 minutes without use; nothing starts at login. Stop it with Ctrl-C, or close the “sessionsnap UI” workspace. Flags: --port <n> (default 47317), --idle-minutes <n> (default 30), --no-open (serve without showing the page).

The link carries a one-time key after # (…/#t=<key>), which browsers never send to a server. A new start makes a new key. If the page has no key or an old one, click Reconnect or run sessionsnap ui again. In cmux 0.64 the Dock is a beta feature (Settings → Beta Features → Dock); without it the page opens as a normal browser tab.

Palette and skill

$ sessionsnap install-cmux     # palette commands in cmux (asks first, backs up cmux.json)
$ sessionsnap install-skill    # teaches Claude Code to use sessionsnap

install-cmux adds these commands to ~/.config/cmux/cmux.json; run cmux reload-config to load them. --print prints them instead. The palette is for cmux on macOS: on Linux, install-cmux refuses (exit 4) and changes nothing.

• sessionsnap: Save / update snapshot
• sessionsnap: Restore snapshot
• sessionsnap: Recent sessions not open
• sessionsnap: List snapshots
• sessionsnap: Open UI

install-skill installs a Claude Code skill at ~/.claude/skills/sessionsnap. It tells Claude to use --json, to show you a restore plan before applying it, and never to schedule saves on its own.

Files and env vars

sessionsnap also reads cmux's state file and cmux --json tree. Snapshots are format 2 ("sessionsnap": 2), plain JSON you can read and edit. Files from pre-release builds (format 1) show as “unreadable” until converted; the README says how.

Security

Snapshots are user-editable files whose contents end up as commands in a shell, so:

• Every word of a restore command is shell-quoted, and session IDs are validated first (UUIDs for Claude Code and Codex).
• A tab whose flags, ID, folder or command hold a control character (newline, ^C, ESC …) is never run, and an agent record with one is not saved. A resume command with a backslash is not typed into an already open workspace.
• Environment variables from cmux's state are never stored, nor flags that look like credentials (a flag name or -c key ending in token, secret, password, credential(s), auth, or holding an API key, and values that look like tokens). They are dropped with their values, and save says so.
• Snapshot files are readable only by you (folder 0700, files 0600).
• The web UI listens on 127.0.0.1 only and needs the one-time key from its link.

Updating

$ sessionsnap update --check   # only say whether a newer release exists
$ sessionsnap update           # replace this binary with the latest release

update asks GitHub for the latest release. If you already have it, it prints sessionsnap X.Y.Z is the latest release. Otherwise it downloads the archive for your system into a private temporary folder, verifies its SHA-256, checks that the new binary reports the expected version, then copies it next to the running binary and renames it into place, so a running web UI keeps its old file until you restart it. If any check fails, nothing is changed. --check only reports, for example sessionsnap 0.2.0 is available (you have 0.1.0); run: sessionsnap update.

• Installed with cargo: update does not replace a binary under cargo's bin folder (exit 1). Run cargo install --git https://github.com/pawanpaudel93/sessionsnap --force, or switch to the installer.
• No release found (none published yet, or the repository is private): exit 7. If GitHub can't be reached: exit 1. Both messages name the installer and cargo install instead.
• A folder you can't write to: it suggests running the update as the folder's owner, or reinstalling there with SESSIONSNAP_INSTALL_DIR.

With --json it prints current, latest, updateAvailable and updated, plus run (with --check) or path (after an update). Running the installer again also upgrades in place.

Uninstall

$ sessionsnap uninstall               # lists what it removes and asks first
$ sessionsnap uninstall --keep-data   # keep your snapshots in ~/.sessionsnap

After you confirm (or with -y), uninstall removes:

• the “sessionsnap: …” palette commands from cmux's cmux.json, after backing the file up next to itself; your other commands and comments stay (if its "commands" array holds comments, this step is skipped and you remove those entries by hand);
• the Claude Code skill at ~/.claude/skills/sessionsnap, only if sessionsnap wrote it;
• ~/.sessionsnap (or SESSIONSNAP_HOME) unless you pass --keep-data; a symlink, or a folder holding files sessionsnap did not make, is left alone;
• the sessionsnap binary. One installed with cargo is left; run cargo uninstall sessionsnap afterwards.

Anything already gone is reported, not an error. It leaves the PATH line the installer added (other tools may use ~/.local/bin) and lists it. Under --json, or without a terminal, it needs --yes; otherwise it refuses with exit 4.