mux

A tmux session manager with persistent pane layouts.

Caution

Not yet released. See the issue tracker for status.

What it does

mux is a single command that opens or returns to the tmux session for your current project directory.

• cd ~/Code/aniftyco/mux && mux creates a session named mux and attaches
• Running mux again from the same directory re-attaches
• Inside an existing mux session, mux from a different project directory opens that project as a tab on the current session
• Pane layouts, splits, and the commands running in each pane are saved to a TOML registry and restored on next attach

Names are derived from the directory's basename. Collisions across different paths (~/Code/aniftyco/mux and ~/Code/joshmanders/mux) auto-disambiguate by walking up the path (joshmanders-mux).

Install

brew install aniftyco/tap/mux

tmux is a declared dependency and will be installed automatically.

Usage

Open or attach

mux                  # derive name from current directory
mux my-session       # override the derived name

Inspect

mux list             # list every registered session
mux show             # pane details for the current directory's session
mux show foo:bar     # pane details for a specific session (parent:base form accepted)
mux tab:show         # tabs registered to the current session

Manage

mux title "Pretty Name"   # set @title on the session (read by status-line formats)
mux title                 # print the current title
mux copy source-session   # copy layout from another session into this one
mux delete                # kill session + drop from registry
mux kill                  # kill the running tmux session without touching the registry

Tabs

mux tab logs                # create/switch to a tab named "logs" in current session
mux tab logs /var/log       # ...with that working directory
mux tab:at /var/log         # name derived from basename of the path
mux tab:kill logs           # remove tab from registry; kills the window if running
mux tab:kill                # inside tmux: kills the current window (refuses the primary)

Registry

mux stores everything in ~/.config/mux/sessions.toml. The path can be overridden with MUX_REGISTRY. The file is rewritten atomically (temp-file + rename) so concurrent invocations can't corrupt it.

[[entries]]
path = "/Users/josh/Code/aniftyco/mux"
session = "mux"
window = "mux"
layout = "b25d,200x50,0,0,1"

[[entries.panes]]
dir = "/Users/josh/Code/aniftyco/mux"
cmd = "nvim"

[[entries.panes]]
dir = "/Users/josh/Code/aniftyco/mux"
cmd = ""

[[entries.tabs]]
name = "logs"
path = "/var/log"

tmux hook integration

mux --save walks the registry, captures the current layout and running commands for any session that's actually running, and writes them back. The binary is fast and safe to invoke from hooks. Add to your tmux.conf:

set-hook -g after-split-window 'run-shell -b "sleep 3 && mux --save >/dev/null 2>&1 || true"'
set-hook -g pane-exited        'run-shell -b "mux --save >/dev/null 2>&1 || true"'
set-hook -g client-detached    'run-shell -b "mux --save >/dev/null 2>&1 || true"'

Optional bindings for tab creation/removal from inside tmux:

bind t command-prompt -p "tab:" -I "#{pane_current_path}" "run-shell -b 'mux tab:at \"%%\"'"
bind W run-shell -b "mux tab:kill"

Requirements

• macOS (Apple Silicon or Intel)
• tmux — declared Homebrew dependency

License

mux is open-source software licensed under the MIT license.