⌨️ Tmux 速查手册

Prefix = Ctrl + s

基于 ~/.tmux.conf 实际配置生成。自定义键位与 tmux 默认有较大差异，以本文档为准。

🔍 没有匹配的内容

0 新手先看 概念 + 记法

三层模型

📦
Session
一组工作空间
一个项目一个 session
🪟
Window
Session 里的标签页
类似浏览器 Tab
🔲
Pane
Window 里的分屏
每个 Pane 是独立终端
tmux server └── session 1：project-a ├── window 1：editor │ ├── pane 1：nvim │ └── pane 2：shell └── window 2：server └── pane 1：pnpm dev

按键记法

写法含义举例
C-sControl + sC-s 就是 Ctrl+S
M-sMeta + s，Mac 上通常是 Option + sM-o = Option+O
M-SOption + Shift + sM-L = Option+Shift+L
prefix x先按 C-s，松开后再按 xprefix d = Ctrl+S → d
bind -n不需要 prefix，直接按就触发M-o 直接新建 window
⚠ M- 不生效？

检查终端是否启用了 Option as Meta / Alt sends escape。

这台电脑的配置特点

  • Prefix 改成了 C-s，默认 C-b 已禁用
  • 很多高频操作是 Option 直连，不需要先按 prefix
  • n/e/u/i 被当作方向键使用：左/下/上/右（Colemak 风格）
  • Session 会被自动编号成 1-xxx、2-xxx，方便用 C-1 / F1 切换
  • 状态栏会显示 Agent 任务、未读、失败、等待问题等状态
  • 配了 tmux-resurrect 和 tmux-continuum，每 5 分钟自动保存状态，但自动恢复已关闭
自定义绑定（.tmux.conf）
tmux 默认（未被覆盖）

1 启动 / 进入 / 退出 最先学会

# 新建默认 session
tmux

# 新建命名 session
tmux new -s demo

# 查看已有 session
tmux ls

# 进入第一个 session
tmux a

# 进入指定 session
tmux a -t demo
prefix d
Session默认 Detach — 离开 tmux，里面的命令继续跑
prefix :
Session默认 进入命令行模式 可输入 kill-server 等命令
# 关闭指定 session
tmux kill-session -t demo

# 关闭整个 tmux server（所有 session 都会没）
tmux kill-server

2 Session 管理

M-S
Session自定义 在当前路径新建 session
C-1 ~ C-9
Session自定义 按编号切换 session F1~F5 也可以
prefix C-c
Session自定义 新建 session
prefix .
Session自定义 重命名 session 覆盖了默认的 move-window
prefix l / y
Session自定义 左 / 右移动当前 session 顺序
prefix 1~0
Session自定义 把当前 window 移动到第 N 个 session 覆盖了默认的 select-window
prefix s
Session默认 列出 / 切换 session x 可关闭选中项
prefix $
Session默认 重命名 session 默认绑定仍可用，但习惯上用 prefix . 代替
prefix D
Session默认 选择要断开的会话

3 Window 管理

M-o
Window自定义 在当前路径新建 window
M-1 ~ M-9
Window自定义 切换到当前 session 第 N 个 window
M-l / M-y
Window自定义 上一个 / 下一个 window
M-L / M-Y
Window自定义 当前 session 内左右交换 window 顺序
M-! ~ M-(
Window自定义 把当前 pane 合并到 window 1~9 M-! = :1, M-@ = :2, M-# = :3 …
prefix ,
Window自定义 重命名 window
prefix C-p / C-n
Window自定义 上一个 / 下一个 window 默认 p/n 已被重绑
prefix W
Window自定义 打开 choose-tree
prefix c
Window默认 新建 window
prefix &
Window默认 关闭当前 window（需确认）
prefix w
Window默认 Window / Session 列表选择

4 Pane 管理

⚠ 分屏键已重绑

默认的 prefix "（上下分屏）和 prefix %（左右分屏）仍可用，但自定义的 prefix u/e/n/i 会继承当前路径，更推荐使用。

prefix u
Pane自定义 上下分屏 — 新 pane 在上方（继承路径）
prefix e
Pane自定义 上下分屏 — 新 pane 在下方（继承路径）
prefix n
Pane自定义 左右分屏 — 新 pane 在左侧（继承路径）
prefix i
Pane自定义 左右分屏 — 新 pane 在右侧（继承路径）
M-n M-e M-u M-i
Pane自定义 按 左/下/上/右 移动焦点
M-a
Pane自定义 跳到最左 pane
M-g
Pane自定义 跳到右上 pane
M-r
Pane自定义 跳到右下 pane
M-N M-E M-U M-I
Pane自定义 按 左/下/上/右 调整大小（步进 3）
M-f
Pane自定义 最大化 / 还原
M-O
Pane自定义 当前 pane 拆成独立 window
M-Q
Pane自定义 关闭当前 pane
prefix > / <
Pane自定义 向后 / 向前交换 pane
prefix |
Pane自定义 Swap pane
prefix S / V
Pane自定义 从 choose-tree 选 pane 垂直/水平移入当前 window
prefix Space
Pane自定义 2-pane 场景切换横向 / 纵向布局
prefix I N U E
Pane自定义 2-pane 基础上向 右/左/上/下 扩展布局
prefix C-g
Pane自定义 Synchronize-panes 开关 开启时 pane border 变红
prefix x
Pane默认 关闭当前 pane（需确认）
prefix z
Pane默认 最大化 / 还原（与 M-f 效果相同）
prefix ;
Pane默认 切换到上一个 pane
prefix o
Pane默认 切换到下一个 pane
prefix q
Pane默认 显示 pane 编号，按数字跳转
prefix !
Pane默认 将当前 pane 移到新 window
prefix { / }
Pane默认 向前 / 向后置换 pane
prefix t
Pane默认 显示时钟

5 Copy Mode & 剪贴板 vi key table

💡 进入与退出
  • M-v 进入 copy-mode（无需 prefix）
  • q 或 Escape 退出 copy-mode

选择 & 复制

v
Copy 开始选择
C-v
Copy 矩形选择
y
Copy 复制并退出 → tmux buffer + 系统剪贴板
Y
Copy 复制到行尾

光标移动（Colemak 风格）

n i u e
Copy 左 / 右 / 上 / 下 移动光标
N / I
Copy 行首 / 行尾
h
Copy 跳到下一个词尾
U / E
Copy 向上 / 向下移动 5 行
C-u / C-e
Copy 向上 / 向下滚动 5 行
=
Copy 反向搜索

粘贴

C-S-v / M-V
剪贴板自定义 从系统剪贴板粘贴 无需 prefix，任何模式下可用
prefix p
Buffer自定义 粘贴 tmux buffer 小写 p，覆盖了默认 previous-window
prefix b
Buffer自定义 列出所有 buffer

6 Agent 工作流 AI 工作台

M-s
Agent 打开 Agent palette（弹窗）
M-w
Agent Watch 当前 pane 命令 再按一次取消 watch
M-b
Agent 切换当前 window 的 unread 标记
M-m
Agent 跳到最新通知来源
M-M
Agent 跳回上一个 origin
prefix O
Agent 重启当前 opencode pane
prefix P
Agent 切换 agent tracker 通知开关

7 插件 & 会话恢复 tmux-resurrect + continuum

📦 TPM (tmux-plugins/tpm)

  • 插件管理器
  • 安装/更新/清理快捷键被统一改成 M-F12
  • 基本禁用了默认 TPM 快捷键，避免误触

💾 tmux-resurrect

  • 保存和恢复 tmux session/window/pane
  • 开启了 pane 内容保存
  • 存档位置：~/.local/share/tmux/resurrect/

♻️ tmux-continuum

  • 每 5 分钟自动保存 resurrect 状态
  • 自动恢复已关闭（@continuum-restore off）
  • 启动 tmux 时不会自动恢复
💡 手动保存 / 恢复会话
  • prefix C-s — 保存当前 tmux 状态（即 Ctrl+S → Ctrl+S）
  • prefix C-r — 恢复上次保存的状态（即 Ctrl+S → Ctrl+R）

注意：Prefix 是 C-s，所以 prefix C-s 实际上是按两次 Ctrl+S。

8 被覆盖 / 移除的默认键 避免踩坑

🚫 这些 tmux 默认键已被重绑或禁用

按下去不会得到预期的默认行为。

prefix n
默认：next-window → 现在是左侧分屏
prefix p
默认：previous-window → 现在是paste-buffer
prefix l
默认：last-window → 现在是session 左移
prefix .
默认：move-window → 现在是重命名 session
prefix 1~0
默认：select-window N → 现在是移 window 到 session N 用 M-1~M-9 替代 select-window
prefix Space
默认：next-layout → 现在是2-pane 横竖切换
M-p / M-P
已被 unbind → 无功能

9 较少用快捷键备忘 按需查阅

prefix ?
帮助默认 显示快捷键帮助文档
prefix ~
帮助默认 列出提示信息缓存
prefix C-z
Session默认 挂起当前会话
prefix r
Pane默认 强制重绘（刷新）
prefix C-o
Pane默认 旋转 pane

10 常用命令 终端直接执行

📦 Session 管理

# 新建名为 demo 的会话
tmux new -s demo

# 进入/附加会话（默认进入第一个）
tmux a

# 附加到指定会话
tmux a -t demo

# 查看所有会话
tmux ls

# 关闭指定会话
tmux kill-session -t demo

# 关闭服务器：所有会话都将关闭
tmux kill-server

🪟 Window / Pane 管理

tmux kill-pane        # 关闭 pane
tmux kill-window      # 关闭 window

ℹ️ 帮助 / 调试

tmux list-keys        # 列出所有快捷键及对应命令
tmux list-commands    # 列出所有 tmux 命令及参数
tmux info              # 输出 session/window/pane 信息
tmux show-hooks -g    # 查看全局 hook 绑定

⚙️ 配置

# 重新加载 tmux 配置
tmux source-file ~/.tmux.conf

# 进入命令行模式（在 tmux 内）
<prefix> :

🔍 排查配置冲突

# 查看某个键实际绑定了什么
tmux list-keys | grep 'prefix.*Space'

# 查看所有自定义脚本绑定
tmux list-keys | grep 'config/tmux'

# 查看 status line 配置
tmux show -g status-left
tmux show -g status-right

✅ 验证配置是否加载

# 查看主配置是否 source 了自定义脚本
rg -n '\.config/tmux|fzf_panes|tmux-status|session_manager' ~/.tmux.conf

# 查看当前 tmux 已绑定的自定义快捷键
tmux list-keys | rg 'config/tmux|fzf|agent|session_manager|watch_pane'

# 查看 hook 是否正常
tmux show-hooks -g | rg 'config/tmux|agent|resurrect|watch'

11 配置架构 ~/.config/tmux/

~/.config/tmux/ ├── fzf_panes.tmux # fzf 管理所有 pane ├── scripts/ # session/window/pane/AI Agent 脚本 └── tmux-status/ # 状态栏左右两侧 + 图标脚本
💡 基础设置一览
  • Prefix：C-s（替换默认 C-b）
  • 默认 shell：/bin/zsh
  • Mouse 始终开启（无 toggle 键）
  • Session / window / pane 编号从 1 开始，window 自动重编号
  • history-limit：10000
  • 状态栏每 1s 刷新
  • detach-on-destroy off：关闭最后一个 window 不会退出 tmux
  • TPM 插件：tmux-resurrect + tmux-continuum（每 5 分钟自动保存）

🔍 fzf_panes.tmux

  • fzf 列出所有 pane，支持预览
  • 跳转、kill、移动、交换 pane
  • 维护最近使用 pane 列表 @mru_pane_ids

📋 session_manager.py

  • Session 统一命名 数字-label
  • 按编号切换、重命名
  • 左右移动 session 顺序
  • 移动 window 到指定 session

📊 left.sh (Status)

  • 渲染左侧 session 列表
  • 当前 session 高亮
  • 窄屏时只显示编号
  • 显示问题/失败/未读/执行中图标

🤖 right.sh (Status)

  • 调用 agent-tracker 生成右侧状态
  • 显示 AI Agent 运行状态

⭐ pane_starship_title.sh

  • 用 starship 生成 pane title
  • 叠加 opencode 任务状态
  • 问题 pending / watching 等指示

👀 watch_pane.sh

  • 监控当前 pane 中的命令
  • 命令结束后设置 unread/failed 状态
  • 通过 agent-tracker 发送通知

12 Hook 行为 自动触发

client-attached
Ack agent-tracker 通知，刷新状态栏
pane-focus-in
更新 fzf pane MRU → 通知 agent focus → ack 通知 → 清除 unread/fail → 刷新状态栏
pane-died
删除对应 agent-tracker task
after-select-window
执行 on-tmux-window-activate.sh → ack 通知 → 清除 unread/fail → 刷新状态栏
client-session-changed
切换 session 时通知 agent focus → ack → 清除 unread/fail → 刷新
session-created
调用 session_created.sh，保证 session 编号连续
session-renamed
刷新状态栏
session-closed
刷新状态栏

13 依赖项

🔧
tmux
必需 · 核心
🐚
bash + python3
必需 · 脚本运行
🔍
fzf
可选 · pane 管理
📝
jq
可选 · JSON 处理
🚀
starship
可选 · pane title
📋
pbcopy / pbpaste
可选 · macOS 剪贴板
🤖
agent-tracker
可选 · AI 工作流
💾
tmux-resurrect
TPM · 会话恢复
♻️
tmux-continuum
TPM · 每 5 分钟自动保存

14 新手排查 常见问题

修改配置后没生效

重新加载配置：

tmux source-file ~/.tmux.conf

如果还是异常，重启 tmux server：

tmux kill-server
tmux
M- 快捷键（Option 系列）没反应

M 是 Meta，Mac 上通常是 Option。需要在终端里启用：

  • iTerm2：Profiles → Keys → Left/Right Option key → Esc+
  • Terminal.app：Profiles → Keyboard → Use Option as Meta key
  • Kitty / Ghostty：检查 Option/Alt 是否发送 Meta/Escape
状态栏右侧为空

右侧依赖 agent-tracker。检查：

# 检查 agent 可执行文件
test -x ~/.config/agent-tracker/bin/agent && echo "OK" || echo "MISSING"

# 检查 agent-tracker-server 服务
brew services list | rg agent-tracker
fzf pane 选择器不可用

确认 fzf 已安装：

command -v fzf

当前 .tmux.conf 没有显式绑定打开 fzf_panes.tmux new_window 的快捷键；如果要用，需要额外绑定一个键。

opencode 恢复失败

脚本里恢复命令是 op -s <session_id>。目前 op 已链接到 opencode，如果以后失效，检查：

command -v op
op --help

15 设计理念

🎯 这不只是一份 tmux 配置 — 它是一个 AI Coding 工作台
  • Session 有稳定编号，便于快速跳转和重排
  • Status line 显示各 session/window 的任务状态
  • Pane title 结合 starship 和 opencode 展示上下文
  • 长命令或 Agent 任务结束后能显示未读、失败、等待确认
  • 通过 tmux-resurrect + continuum 自动保存和恢复 agent 相关 pane
  • Colemak 风格的方向键映射（n/e/u/i = 左/下/上/右）贯穿所有模式

最小接入：只保留 fzf_panes.tmux、剪贴板脚本、session 编号脚本。
完整复刻：还需安装 agent-tracker、opencode、tmux-resurrect、starship。