Back to Details

tmux-mastery

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

tmux Mastery

tmux 精通指南

Covers two domains: process management (running/monitoring processes) and ricing (visual customization and UX plugins).
涵盖两大领域：进程管理（运行/监控进程）和视觉定制（ricing）（视觉自定义与UX插件）。

Process Management

进程管理

Interactive Shell Pattern

交互式Shell模式

Always use 
send-keys
- never inline commands in 
new-session
. This ensures PATH, direnv, and shell init run correctly.
bash
undefined
始终使用
send-keys
——切勿在
new-session
中直接嵌入命令。这样可以确保PATH、direnv和Shell初始化脚本正确运行。
bash
undefined

WRONG

WRONG

tmux new-session -d -s myapp -n main 'npm run dev'
tmux new-session -d -s myapp -n main 'npm run dev'

CORRECT

CORRECT

tmux new-session -d -s myapp -n main tmux send-keys -t myapp:main 'npm run dev' Enter
undefined
tmux new-session -d -s myapp -n main tmux send-keys -t myapp:main 'npm run dev' Enter
undefined

Session Naming

会话命名

Derive from git root:
bash
SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
Use windows, not separate sessions, for multiple processes in one project.
从Git仓库根目录自动生成会话名称：
bash
SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
对于单个项目中的多个进程，使用窗口而非独立会话。

Idempotent Start

幂等启动脚本

bash
SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)

if ! tmux has-session -t "$SESSION" 2>/dev/null; then
  tmux new-session -d -s "$SESSION" -n server
  tmux send-keys -t "$SESSION:server" 'npm run dev' Enter
else
  echo "Session $SESSION already exists"
fi
bash
SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)

if ! tmux has-session -t "$SESSION" 2>/dev/null; then
  tmux new-session -d -s "$SESSION" -n server
  tmux send-keys -t "$SESSION:server" 'npm run dev' Enter
else
  echo "Session $SESSION already exists"
fi

Multiple Processes (Windows)

多进程管理（窗口）

bash
SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)

tmux new-session -d -s "$SESSION" -n server
tmux send-keys -t "$SESSION:server" 'npm run dev' Enter

tmux new-window -t "$SESSION" -n tests
tmux send-keys -t "$SESSION:tests" 'npm run test:watch' Enter

tmux new-window -t "$SESSION" -n logs
tmux send-keys -t "$SESSION:logs" 'tail -f logs/app.log' Enter
bash
SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)

tmux new-session -d -s "$SESSION" -n server
tmux send-keys -t "$SESSION:server" 'npm run dev' Enter

tmux new-window -t "$SESSION" -n tests
tmux send-keys -t "$SESSION:tests" 'npm run test:watch' Enter

tmux new-window -t "$SESSION" -n logs
tmux send-keys -t "$SESSION:logs" 'tail -f logs/app.log' Enter

Monitoring Output

输出监控

bash
undefined
bash
undefined

Last 50 lines from a window

Last 50 lines from a window

tmux capture-pane -p -t "$SESSION:server" -S -50
tmux capture-pane -p -t "$SESSION:server" -S -50

Check for errors

Check for errors

tmux capture-pane -p -t "$SESSION" -S -100 | rg -i "error|fail|exception"
tmux capture-pane -p -t "$SESSION" -S -100 | rg -i "error|fail|exception"

Poll until ready

Poll until ready

for i in {1..30}; do tmux capture-pane -p -t "$SESSION:server" -S -20 | rg -q "listening|ready" && break sleep 1 done
undefined
for i in {1..30}; do tmux capture-pane -p -t "$SESSION:server" -S -20 | rg -q "listening|ready" && break sleep 1 done
undefined

Lifecycle Commands

生命周期命令

bash
tmux ls                                      # list sessions
tmux list-windows -t "$SESSION"              # list windows
tmux kill-session -t "$SESSION"             # kill session
tmux send-keys -t "$SESSION:server" C-c     # send Ctrl+C
bash
tmux ls                                      # list sessions
tmux list-windows -t "$SESSION"              # list windows
tmux kill-session -t "$SESSION"             # kill session
tmux send-keys -t "$SESSION:server" C-c     # send Ctrl+C

Isolation Rules

隔离规则

  • Never 
    tmux kill-server
  • Never kill sessions not matching current project
  • Always verify session name before destructive ops
  • 切勿使用
    tmux kill-server
  • 切勿终止与当前项目不匹配的会话
  • 始终在执行破坏性操作前验证会话名称

When to Use tmux

何时使用tmux

ScenarioUse tmux?
Dev server / file watcherYes
Long-running background processYes
One-shot build (
npm run build
)		No
Quick command (<10s)No
Need stdout directly in conversationNo
场景是否使用tmux？
开发服务器 / 文件监视器是
长时间运行的后台进程是
一次性构建（
npm run build
）		否
快速命令（<10秒）否
需要直接在对话中获取标准输出否

Ricing - Visual Customization

视觉定制（Ricing）

Plugin Manager (TPM)

插件管理器（TPM）

Install TPM first:
bash
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
Add to 
~/.config/tmux/tmux.conf
(or 
~/.tmux.conf
):
conf
set -g @plugin 'tmux-plugins/tpm'
run '~/.tmux/plugins/tpm/tpm'
Install plugins: 
prefix + I
| Reload: 
prefix + r
| Update: 
prefix + U
首先安装TPM：
bash
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
将以下内容添加到
~/.config/tmux/tmux.conf
（或
~/.tmux.conf
）：
conf
set -g @plugin 'tmux-plugins/tpm'
run '~/.tmux/plugins/tpm/tpm'
安装插件：
prefix + I
| 重载配置：
prefix + r
| 更新插件：
prefix + U

Essential Base Settings (omerxx-style)

基础配置（omerxx风格）

conf
set-option -g default-terminal 'screen-256color'
set-option -g terminal-overrides ',xterm-256color:RGB'

set -g prefix ^A                   # Ctrl+A prefix (like screen)
set -g base-index 1                # windows start at 1
set -g detach-on-destroy off       # don't exit tmux when closing a session
set -g escape-time 0               # zero escape time delay
set -g history-limit 1000000       # large scrollback
set -g renumber-windows on         # auto-renumber after close
set -g set-clipboard on            # use system clipboard
set -g status-position top         # status bar at top (macOS style)

setw -g mode-keys vi               # vi keys in copy mode
set -g pane-active-border-style 'fg=magenta,bg=default'
set -g pane-border-style 'fg=brightblack,bg=default'
conf
set-option -g default-terminal 'screen-256color'
set-option -g terminal-overrides ',xterm-256color:RGB'

set -g prefix ^A                   # Ctrl+A prefix (like screen)
set -g base-index 1                # windows start at 1
set -g detach-on-destroy off       # don't exit tmux when closing a session
set -g escape-time 0               # zero escape time delay
set -g history-limit 1000000       # large scrollback
set -g renumber-windows on         # auto-renumber after close
set -g set-clipboard on            # use system clipboard
set -g status-position top         # status bar at top (macOS style)

setw -g mode-keys vi               # vi keys in copy mode
set -g pane-active-border-style 'fg=magenta,bg=default'
set -g pane-border-style 'fg=brightblack,bg=default'

Catppuccin Theme

Catppuccin主题

conf
set -g @plugin 'omerxx/catppuccin-tmux'   # omerxx fork with extras
conf
set -g @plugin 'omerxx/catppuccin-tmux'   # omerxx fork with extras

Window styling

Window styling

set -g @catppuccin_window_left_separator "" set -g @catppuccin_window_right_separator " " set -g @catppuccin_window_middle_separator " █" set -g @catppuccin_window_number_position "right" set -g @catppuccin_window_default_fill "number" set -g @catppuccin_window_default_text "#W" set -g @catppuccin_window_current_fill "number" set -g @catppuccin_window_current_text "#W#{?window_zoomed_flag,(),}"
set -g @catppuccin_window_left_separator "" set -g @catppuccin_window_right_separator " " set -g @catppuccin_window_middle_separator " █" set -g @catppuccin_window_number_position "right" set -g @catppuccin_window_default_fill "number" set -g @catppuccin_window_default_text "#W" set -g @catppuccin_window_current_fill "number" set -g @catppuccin_window_current_text "#W#{?window_zoomed_flag,(),}"

Status bar modules

Status bar modules

set -g @catppuccin_status_modules_right "directory" set -g @catppuccin_status_modules_left "session" set -g @catppuccin_status_left_separator " " set -g @catppuccin_status_right_separator " " set -g @catppuccin_status_fill "icon" set -g @catppuccin_status_connect_separator "no" set -g @catppuccin_directory_text "#{b:pane_current_path}"
undefined
set -g @catppuccin_status_modules_right "directory" set -g @catppuccin_status_modules_left "session" set -g @catppuccin_status_left_separator " " set -g @catppuccin_status_right_separator " " set -g @catppuccin_status_fill "icon" set -g @catppuccin_status_connect_separator "no" set -g @catppuccin_directory_text "#{b:pane_current_path}"
undefined

tmux-sessionx - Fuzzy Session Manager

tmux-sessionx - 模糊会话管理器

conf
set -g @plugin 'omerxx/tmux-sessionx'

set -g @sessionx-bind 'o'                        # launch with prefix+o
set -g @sessionx-auto-accept 'off'
set -g @sessionx-window-height '85%'
set -g @sessionx-window-width '75%'
set -g @sessionx-zoxide-mode 'on'               # requires zoxide
set -g @sessionx-filter-current 'false'
set -g @sessionx-custom-paths '~/projects'       # always-visible paths
set -g @sessionx-custom-paths-subdirectories 'false'
set -g @sessionx-git-branch 'on'                # show git branch next to session
Key bindings inside sessionx:
  • alt+backspace
    - delete session
  • Ctrl-r
    - rename session
  • Ctrl-w
    - switch to window mode
  • Ctrl-e
    - expand PWD for local dirs
  • Ctrl-x
    - browse 
    ~/.config
    or custom path
  • ?
    - toggle preview
conf
set -g @plugin 'omerxx/tmux-sessionx'

set -g @sessionx-bind 'o'                        # launch with prefix+o
set -g @sessionx-auto-accept 'off'
set -g @sessionx-window-height '85%'
set -g @sessionx-window-width '75%'
set -g @sessionx-zoxide-mode 'on'               # requires zoxide
set -g @sessionx-filter-current 'false'
set -g @sessionx-custom-paths '~/projects'       # always-visible paths
set -g @sessionx-custom-paths-subdirectories 'false'
set -g @sessionx-git-branch 'on'                # show git branch next to session
sessionx内的快捷键：
  • alt+backspace
    - 删除会话
  • Ctrl-r
    - 重命名会话
  • Ctrl-w
    - 切换到窗口模式
  • Ctrl-e
    - 展开本地目录的PWD
  • Ctrl-x
    - 浏览
    ~/.config
    或自定义路径
  • ?
    - 切换预览

tmux-floax - Floating Scratch Pane

tmux-floax - 浮动临时窗格

conf
set -g @plugin 'omerxx/tmux-floax'

set -g @floax-bind 'p'              # prefix+p to toggle
set -g @floax-bind-menu 'P'         # prefix+P for resize/fullscreen menu
set -g @floax-width '80%'
set -g @floax-height '80%'
set -g @floax-border-color 'magenta'
set -g @floax-text-color 'blue'
set -g @floax-change-path 'true'    # float follows session path
conf
set -g @plugin 'omerxx/tmux-floax'

set -g @floax-bind 'p'              # prefix+p to toggle
set -g @floax-bind-menu 'P'         # prefix+P for resize/fullscreen menu
set -g @floax-width '80%'
set -g @floax-height '80%'
set -g @floax-border-color 'magenta'
set -g @floax-text-color 'blue'
set -g @floax-change-path 'true'    # float follows session path

set -g @floax-session-name 'scratch' # default session name

set -g @floax-session-name 'scratch' # default session name


Floating pane menu options: size down/up, fullscreen, reset, embed.

浮动窗格菜单选项：缩小/放大尺寸、全屏、重置、嵌入。

Full Recommended Plugin Stack

推荐完整插件栈

conf
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-yank'
set -g @plugin 'tmux-plugins/tmux-resurrect'    # save/restore sessions
set -g @plugin 'tmux-plugins/tmux-continuum'    # auto-save
set -g @plugin 'fcsonline/tmux-thumbs'          # hint-based copy
set -g @plugin 'sainnhe/tmux-fzf'
set -g @plugin 'wfxr/tmux-fzf-url'
set -g @plugin 'omerxx/catppuccin-tmux'
set -g @plugin 'omerxx/tmux-sessionx'
set -g @plugin 'omerxx/tmux-floax'
conf
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-yank'
set -g @plugin 'tmux-plugins/tmux-resurrect'    # save/restore sessions
set -g @plugin 'tmux-plugins/tmux-continuum'    # auto-save
set -g @plugin 'fcsonline/tmux-thumbs'          # hint-based copy
set -g @plugin 'sainnhe/tmux-fzf'
set -g @plugin 'wfxr/tmux-fzf-url'
set -g @plugin 'omerxx/catppuccin-tmux'
set -g @plugin 'omerxx/tmux-sessionx'
set -g @plugin 'omerxx/tmux-floax'

Session persistence

Session persistence

set -g @continuum-restore 'on' set -g @resurrect-strategy-nvim 'session'
run '~/.tmux/plugins/tpm/tpm'
undefined
set -g @continuum-restore 'on' set -g @resurrect-strategy-nvim 'session'
run '~/.tmux/plugins/tpm/tpm'
undefined

Minimal Config Quickstart

极简配置快速上手

For a clean starting config:
conf
undefined
如需干净的初始配置：
conf
undefined

~/.config/tmux/tmux.conf

~/.config/tmux/tmux.conf

source-file ~/.config/tmux/tmux.reset.conf # optional keybind resets
set-option -g default-terminal 'screen-256color' set-option -g terminal-overrides ',xterm-256color:RGB'
set -g prefix ^A set -g base-index 1 set -g detach-on-destroy off set -g escape-time 0 set -g history-limit 1000000 set -g renumber-windows on set -g set-clipboard on set -g status-position top setw -g mode-keys vi
set -g pane-active-border-style 'fg=magenta,bg=default' set -g pane-border-style 'fg=brightblack,bg=default'
set -g @plugin 'tmux-plugins/tpm' set -g @plugin 'tmux-plugins/tmux-sensible' set -g @plugin 'omerxx/catppuccin-tmux' set -g @plugin 'omerxx/tmux-sessionx' set -g @plugin 'omerxx/tmux-floax'
set -g @sessionx-bind 'o' set -g @floax-bind 'p' set -g @floax-border-color 'magenta'
run '~/.tmux/plugins/tpm/tpm'

---
source-file ~/.config/tmux/tmux.reset.conf # optional keybind resets
set-option -g default-terminal 'screen-256color' set-option -g terminal-overrides ',xterm-256color:RGB'
set -g prefix ^A set -g base-index 1 set -g detach-on-destroy off set -g escape-time 0 set -g history-limit 1000000 set -g renumber-windows on set -g set-clipboard on set -g status-position top setw -g mode-keys vi
set -g pane-active-border-style 'fg=magenta,bg=default' set -g pane-border-style 'fg=brightblack,bg=default'
set -g @plugin 'tmux-plugins/tpm' set -g @plugin 'tmux-plugins/tmux-sensible' set -g @plugin 'omerxx/catppuccin-tmux' set -g @plugin 'omerxx/tmux-sessionx' set -g @plugin 'omerxx/tmux-floax'
set -g @sessionx-bind 'o' set -g @floax-bind 'p' set -g @floax-border-color 'magenta'
run '~/.tmux/plugins/tpm/tpm'

---

Additional Resources

额外资源