tmuxp

Session manager for tmux that loads and freezes sessions from YAML or JSON workspace files, built on libtmux.

install

tmuxp is a session manager for tmux. It builds tmux sessions from declarative workspace files written in YAML or JSON, including tmuxinator and teamocil style configs. A file defines the session name, windows, layouts, panes, and the commands each pane runs, plus a shell_command_before entry that runs first in every pane. It is built on the libtmux Python library and supports tmux 3.2+ and Python 3.10+.

The main command is tmuxp load, which accepts a file path, a project directory containing .tmuxp.yaml or .tmuxp.json, or a bare name resolved against user config directories ($TMUXP_CONFIGDIR, $XDG_CONFIG_HOME, or ~/.tmuxp/). It can load several sessions at once in the background and offer to attach to the last one. Other options include -s to name a session, -d to load detached, and --log-file to write debug output. A before_script hook can run a startup script, such as installing project dependencies, before the session loads.

Other commands cover the rest of the workflow. tmuxp freeze snapshots a running session's layout, pane paths, and window and session names. tmuxp convert converts a workspace file between YAML and JSON. tmuxp shell opens a Python console preloaded with the libtmux server, session, window, and pane objects. It supports breakpoint() and one-off commands via -c. tmuxp debug-info collects system details for bug reports, and a plugin system allows custom behavior. It suits developers who want reproducible tmux project environments, and Python users who want to script tmux.

Installation

# via Homebrew
brew install tmuxp
# via apt
sudo apt install tmuxp
# via pip
pip install --user tmuxp

Alternatives & related tools

add a badge to your README

Maintain tmuxp? Show that it's featured on trmn. The badge links back to this page.

Featured on trmn
Markdown
[![Featured on trmn](https://www.trmn.sh/badge/tmuxp.svg)](https://www.trmn.sh/tools/tmuxp?utm_source=badge)
HTML
<a href="https://www.trmn.sh/tools/tmuxp?utm_source=badge"><img src="https://www.trmn.sh/badge/tmuxp.svg" alt="Featured on trmn" height="20"></a>