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)
theme           = "dark"                       # TUI picker theme: dark or light
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. Each entry is a regular
# expression matched against the full command, anchored to the whole line.
# Omit this key to restore every command (default). Provide a list to restore
# only matching commands; 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. Each entry is a regular
# expression matched against the full command (anchored). Use this 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

Breaking change

Allow/denylist entries are now regular expressions matched against the full command, not program names. A bare nvim used to match nvim main.go; it now matches only the exact command nvim. Rewrite name-based lists as patterns (e.g. nvim → nvim( .*)?). An invalid regex fails at config load.

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 commands matching a pattern are replayed; any other pane is left at the shell.
empty list [] → no commands are restored at all.

Each entry is a regular expression matched against the full command, anchored end to end. So nvim( .*)? matches nvim with or without arguments, while a bare nvim matches only the exact command nvim. Write a literal command to allow exactly that command, or wildcard the arguments with .*.

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). Each entry is a regular expression matched against the full command, 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.