tmuxp

tmuxp — 一个用YAML/JSON配置文件批量管理tmux会话的CLI工具，告别手动开窗口。

tmux 是终端复用器里的老大哥，但它的学习曲线和手动管理会话的繁琐程度，一直是很多人的痛点。你可能会遇到这样的场景：每次启动开发环境，都要手动敲 tmux new -s myproject、split-window -h、send-keys 'cd ~/project && nvim' Enter…… 一套流程下来，手指都快抽筋了。而 tmuxp 就是来解决这个问题的——它把 tmux 会话的窗口、面板布局、启动命令等全部写进一个配置文件里，然后一条命令就能还原整个工作环境。

简单说，tmuxp 就像 tmux 的“一键还原脚本”。它不替换 tmux，而是让 tmux 更听话。你可以在家目录下放一堆 .yaml 文件，每个文件对应一个项目的工作区。想切项目？tmuxp load project.yaml，所有窗口和面板自动打开，连光标位置都给你摆好。想保存当前布局？tmuxp freeze，直接把当前会话的窗口结构导出为配置文件，下次直接用。

下载与安装

tmuxp 官方推荐用 pip 安装，因为它就是纯 Python 写的。不过别担心，你不需要懂 Python 就能用。

官网链接：tmuxp 官网
GitHub 仓库：tmuxp 源码

安装方式很简单，根据你的包管理器选一个：

# 用 pip（最推荐，跨平台）
pip install --user tmuxp

# 如果你用 macOS 且装了 Homebrew
brew install tmuxp

# 如果你用 Arch Linux
yay -S tmuxp  # 或者从 AUR 手动安装

# 如果你用 NixOS
nix-env -iA nixos.tmuxp

安装完验证一下：tmuxp --version。如果输出版本号，就搞定了。

基础使用教程

1. 创建你的第一个配置文件

tmuxp 的配置默认放在 ~/.tmuxp/ 目录下。你可以手动创建这个目录，然后写一个 YAML 文件：

mkdir -p ~/.tmuxp
vim ~/.tmuxp/dev.yaml

内容如下：

session_name: dev
windows:
  - window_name: editor
    panes:
      - nvim
  - window_name: server
    panes:
      - cd ~/myproject && npm run dev
  - window_name: shell
    panes:
      - 

这个配置定义了一个叫 dev 的 tmux 会话，包含三个窗口：第一个窗口打开 nvim，第二个窗口启动开发服务器，第三个窗口留一个干净的 shell。注意第三个窗口的 panes 里写了一个空列表项 -，表示只开一个空面板。

2. 加载配置

保存文件后，在终端运行：

tmuxp load dev

或者指定完整路径：

tmuxp load ~/.tmuxp/dev.yaml

如果 tmux 还没启动，tmuxp 会自动创建一个新的 tmux 会话；如果 tmux 已经在运行，它会尝试在当前会话里创建新窗口（取决于你的设置）。默认行为是在一个新会话中打开。

3. 保存当前会话

假如你手动调整了一个 tmux 会话的布局，想把当前状态保存成配置文件，可以用 freeze 命令：

tmuxp freeze my-session-name

这会生成一个 YAML 文件，默认放在当前目录下，文件名是 my-session-name.yaml。你可以把它拷贝到 ~/.tmuxp/ 里，以后直接加载。

4. 其他常用命令

# 列出所有可用的配置文件
tmuxp ls

# 编辑配置文件（用默认编辑器打开）
tmuxp edit dev

# 导入一个已有的 tmux 会话（类似 freeze，但更精细）
tmuxp import dev

进阶技巧

1. 利用环境变量和动态路径

如果你的项目路径经常变，可以在配置里用 $HOME 或 ~。tmuxp 支持 shell 变量展开：

session_name: project
start_directory: ~/projects/{{ project_name }}
windows:
  - window_name: code
    panes:
      - nvim

然后用 tmuxp load project --project_name=myapp 来动态指定路径。

2. 布局控制与面板拆分

tmuxp 支持显式指定面板布局，比如横向拆分、纵向拆分、甚至百分比：

session_name: multi-panel
windows:
  - window_name: dev
    layout: main-vertical  # 主面板在左，右侧垂直拆分
    panes:
      - nvim
      - top
      - tail -f /var/log/syslog

如果你想要更精细的控制，可以用 layout 字段指定 tmux 的 layout 字符串（比如 2e2e,135x55,0,0{67x55,0,0,0,67x55,68,0,1}）。这串东西可以在 tmux 里用 tmux list-windows -a 看到。

3. 启动前执行脚本

你可以让 tmuxp 在创建会话前先跑一段脚本，比如检查 git 仓库状态、拉取最新代码：

session_name: auto-pull
before_script:
  - cd ~/myproject && git pull
windows:
  - window_name: main
    panes:
      - nvim

before_script 里的命令会在所有窗口创建之前执行。如果脚本返回非零退出码，tmuxp 会报错并停止加载。

4. 与 zsh/fish 的 aliases 配合

如果你常用 tmuxp，可以给 shell 加个 alias：

alias tload='tmuxp load'
alias tfreeze='tmuxp freeze'
alias tls='tmuxp ls'

或者写个函数，自动补全配置文件名称：

_tmuxp_load() {
  local files=($(ls ~/.tmuxp/*.yaml 2>/dev/null | xargs -n1 basename | sed 's/\.yaml//'))
  compadd -a files
}
compdef _tmuxp_load tmuxp

5. 跨机器同步配置

把你的 ~/.tmuxp/ 目录加入 dotfiles 仓库（比如用 git）。这样换了电脑后，只要同步 dotfiles，再装个 tmuxp，所有工作区配置就自动就位。配合 tmuxp load 的自动补全，切换项目就像切换桌面一样快。

6. 调试配置错误

如果配置文件写错了，tmuxp 会报错。但有时候错误信息不够直观。你可以用 tmuxp load --dry-run dev 来模拟加载，看看它会执行哪些命令，而不实际创建会话。或者用 yq 工具验证 YAML 语法：

yq eval ~/.tmuxp/dev.yaml

如果 YAML 格式有问题，会直接报错。

写在最后

tmuxp 不是必需品，但如果你每天要和 tmux 打交道，它绝对能帮你节省大量重复操作的时间。尤其适合那些需要同时启动多个终端窗口的项目——比如前端开发（webpack + nvim + 日志窗口）、后端调试（数据库客户端 + API 服务 + 测试脚本）、甚至运维管理（多台服务器同时监控）。把配置写好，每天开工就一句 tmuxp load project，世界清净了。

另外，tmuxp 背后还有一个 Python 库叫 libtmux，如果你喜欢写脚本自动操作 tmux，也可以直接 import 这个库来编程控制。不过对大部分用户来说，YAML 配置已经够用了。

最后提醒一句：tmuxp 的配置文件和 tmux 本身一样，需要一点学习成本。但一旦上手，你就会觉得——以前手动敲 tmux 命令的日子，简直是在用手摇发电机。