tmux-sessionctl (tms)

A lightweight CLI helper that snapshots tmux sessions, restores them on demand, and keeps your window/pane layout synchronized with disk. The tool drives tmux directly, classifies panes to decide what to restore, and offers an interactive attach flow through fzf.

Features

• Save/restore individual sessions or the whole tmux server.
• Auto-detect pane types and replay meaningful commands during restore.
• Interactive attach command with fzf picker that restores dead sessions automatically.
• Optional auto-save hooks and key bindings for tmux via tms setup.
• Snapshot inspection (list, show) and lifecycle helpers (delete, purge).

Requirements

• tmux 3.0 or newer.
• python3 3.9+ on your PATH.
• fzf (recommended) for the interactive attach command.

Installation

Quick install (GitHub one-liner)

curl -fsSL https://raw.githubusercontent.com/lingzolabs/tms/main/install.sh | bash

Manual install

mkdir -p "$HOME/.local/bin"
curl -fsSL https://raw.githubusercontent.com/lingzolabs/tms/main/tms -o "$HOME/.local/bin/tms"
chmod +x "$HOME/.local/bin/tms"

The installer copies tms into ${INSTALL_PREFIX:-$HOME/.local/bin}. Override the target directory by setting INSTALL_PREFIX before running the script. Ensure your shell PATH includes $HOME/.local/bin (e.g. export PATH="$HOME/.local/bin:$PATH").

To install from a fork manually, download the tms script from your fork and place it in ~/.local/bin.

Usage

tms save [<session>]        # Save current session or all when omitted
tms restore [<session>]      # Restore snapshot and attach when done
tms restore --all            # Restore every saved snapshot
tms attach [<session>]       # Pick with fzf when omitted; auto-restore if needed
tms list                     # List stored snapshots
tms show <session>           # Inspect snapshot JSON
tms delete <session>         # Remove a specific snapshot
tms purge                    # Remove every snapshot
tms setup                    # Append managed hooks to ~/.tmux.conf
tms unsetup                  # Remove managed hooks from ~/.tmux.conf

Tmux bindings (after tms setup)

• prefix + S → save current session immediately.
• prefix + R → prompt for a session to restore.
• prefix + L → popup view of saved sessions.

tms setup writes a managed block to ~/.tmux.conf; rerun after upgrading. Use tms unsetup to remove the block.

Development

python3 tms list
python3 tms attach project

Files are stored under ~/.local/state/tmux-sessionctl/ (XDG_STATE_HOME respected). Snapshots are JSON for easy inspection.