tmuxp is a session manager for tmux that lets you save and load tmux sessions through declarative workspace files written in YAML or JSON.
The tool solves the problem of manually recreating tmux layouts and configurations by allowing developers to define their session structure declaratively and restore it with a single command. It works by reading configuration files that specify windows, panes, and their properties, then using libtmux to programmatically construct the corresponding tmux session. The tool can also freeze an existing session to capture its current layout and state as a configuration file.
tmuxp suits developers who work with complex tmux setups and want to version control their session configurations or share them across machines. It is particularly useful for teams that need consistent development environments. The tool supports loading configurations from standard locations like XDG_CONFIG_HOME and can load multiple sessions at once. It is compatible with configuration formats from tmuxinator and teamocil, making it a viable alternative if you are already using those tools. The project includes a shell mode that launches a Python console with the current tmux server, session, and window preloaded as libtmux objects, and supports running custom startup scripts before session creation.
The project maintains active engagement with its issue tracker and welcomes community contributions to triage and code review. Development includes support for modern Python tooling through integration with uv and pipx for installation. The tool offers a plugin system allowing custom behavior extensions. Documentation is comprehensive, covering configuration examples from simple to elaborate setups, and includes debugging helpers for troubleshooting.
