Configuration

lazy-tmux reads an optional TOML config file. Every key is optional — without a file, built-in defaults are used. Settings are layered, so the most specific source wins:

built-in defaults → config file → command-line flags

The file is looked up in this order (first match wins):

• env: $LAZY_TMUX_CONFIG (explicit path)
• $XDG_CONFIG_HOME/lazy-tmux/lazy-tmux.toml
• ~/.config/lazy-tmux/lazy-tmux.toml

A missing file is fine; a malformed file or an unknown key fails loudly so typos don't go unnoticed.

# ~/.config/lazy-tmux/lazy-tmux.toml — all keys are optional

tmux_bin        = "tmux"                       # tmux binary to use
data_dir        = "~/.local/share/lazy-tmux"   # where snapshots are stored (~ is expanded)
save_interval   = "5m"                         # daemon autosave interval (Go duration)
restore_timeout = "5s"                         # max wait for restored pane commands to start (0 disables)

# Allowlist of commands lazy-tmux may replay on restore, matched by program name.
# Omit this key to restore every command (default). Provide a list to restore
# only those programs; use an empty list [] to restore no commands at all.
restore_allowlist = ["nvim", "vim", "htop", "less", "tail", "ssh"]

# Denylist of commands lazy-tmux must never replay, matched by program name.
# Use this instead of an allowlist when you trust most commands and only want to
# exclude a few. The denylist wins over the allowlist. Omit or leave empty to
# block nothing (default).
restore_denylist = ["npm", "node"]

[scrollback]
enabled = false   # capture shell pane scrollback
lines   = 5000    # max scrollback lines per pane

Restore command allowlist

Like tmux-resurrect, you can restrict which commands are replayed on restore, so lazy-tmux never re-runs an arbitrary program that happened to be active at save time:

• key omitted → every command is restored (default).
• list given → only those programs are replayed; any other pane is left at the shell.
• empty list [] → no commands are restored at all.

Matching is by program name, so nvim also matches /usr/bin/nvim main.go.

Restore command denylist

The inverse of the allowlist: rather than enumerating everything you trust, list only the few programs to block with restore_denylist. Handy when you trust almost everything and just want to stop a long-running server or a program that re-prompts from being replayed. It composes with the allowlist and wins over it — a command is replayed only when it is not denied and (no allowlist is set or it is allowed). Matching is by program name, and an omitted or empty list blocks nothing.

Restore settle timeout

On restore, lazy-tmux waits until each pane's command has actually started before returning (bounded by restore_timeout / --restore-timeout), so automation can trust the session is fully restored once the command exits. Set it to 0 to opt out and return immediately.