# tmuxp

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

Stars: 4.6k · Language: Python · License: MIT · Categories: Shell

- Repository: https://github.com/tmux-python/tmuxp
- Website: https://tmuxp.git-pull.com/
- Page: https://www.trmn.sh/tools/tmuxp

## Install

- Homebrew: `brew install tmuxp`
- apt: `sudo apt install tmuxp`
- pip: `pip install --user tmuxp`

## Overview

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

```bash
# via Homebrew
brew install tmuxp
```

```bash
# via apt
sudo apt install tmuxp
```

```bash
# via pip
pip install --user tmuxp
```

## Alternatives

- [thefuck](https://www.trmn.sh/tools/thefuck.md): Command-line error correction tool that suggests and fixes typos in previously executed shell commands (Python, 98.0k stars)
- [HSTR](https://www.trmn.sh/tools/hstr.md): Shell history TUI suggest box for bash and zsh that searches, navigates, and manages command history, with bookmarking of favorite commands. (C, 4.5k stars)
- [X-CMD](https://www.trmn.sh/tools/x-cmd.md): Shell toolkit with command modules, on-demand CLI packages, completions, themes, and AI service integrations. (Awk, 4.8k stars)
- [pet](https://www.trmn.sh/tools/pet.md): Command-line snippet manager written in Go. Save, tag, search, and run shell command snippets with parameters, stored in TOML and synced via Gist or GitLab. (Go, 5.4k stars)
- [vivid](https://www.trmn.sh/tools/vivid.md): Generates LS_COLORS values from YAML filetype databases and color themes, for ls, tree, fd, bfs, dust and other tools. (Rust, 2.3k stars)

---

Canonical: https://www.trmn.sh/tools/tmuxp
