iterm2

Iterm2

macOS 上 iTerm2 终端模拟器和 tmux 终端复用器的完整参考。涵盖键盘快捷键、配置、tmux 集成和效率工作流。

工作流路由

执行工作流时，请同时完成以下两项：

1. 调用通知脚本（用于可观测性跟踪）：

   ~/.claude/Tools/SkillWorkflowNotification WORKFLOWNAME Iterm2
   

2. 输出文本通知（便于用户查看）：

   Running the **WorkflowName** workflow from the **Iterm2** skill...
   

工作流	触发条件	文件
SetupTmux	“setup tmux”、“configure tmux”	workflows/SetupTmux.md
TmuxSession	“tmux session”、“attach session”、“detach”	workflows/TmuxSession.md
TroubleshootTmux	“tmux not working”、“fix tmux”	workflows/TroubleshootTmux.md

示例

示例 1：将终端拆分为多个窗格

User: "How do I split my terminal in iTerm2?"
→ References Shortcuts.md
→ Explains Cmd+D (vertical) and Cmd+Shift+D (horizontal)
→ Shows navigation with Cmd+Option+Arrow

示例 2：设置 tmux 并与 iTerm2 集成

User: "How do I use tmux with iTerm2?"
→ Invokes SetupTmux workflow
→ Explains tmux -CC control mode
→ Shows native window integration benefits

示例 3：通过 SSH 管理持久会话

User: "Keep my terminal running after disconnect"
→ Invokes TmuxSession workflow
→ Creates named session with tmux new -s
→ Shows how to reattach after disconnect

快速参考

iTerm2 基础功能

操作	快捷键
垂直拆分	Cmd+D
水平拆分	Cmd+Shift+D
切换窗格	Cmd+Option+Arrow
最大化窗格	Cmd+Shift+Enter
下一个/上一个标签页	Cmd+{ / Cmd+}
查找	Cmd+F
自动补全	Cmd+;
粘贴历史记录	Cmd+Shift+H
即时回放	Cmd+Option+B
查找光标	Cmd+/

tmux 基础功能

默认前缀：Ctrl+b

操作	快捷键
新建会话	tmux new -s name
列出会话	tmux ls 或 Ctrl+b s
附加会话	tmux attach -t name
分离	Ctrl+b d
新建窗口	Ctrl+b c
垂直拆分	Ctrl+b %
水平拆分	Ctrl+b "
切换窗格	Ctrl+b Arrow
缩放窗格	Ctrl+b z
关闭窗格	Ctrl+b x
复制模式	Ctrl+b [

iTerm2 + tmux 集成

运行 tmux -CC 以使用 iTerm2 原生集成：

• tmux 窗口会显示为 iTerm2 原生窗口
• 使用 iTerm2 快捷键，而非 tmux 前缀
• 会话在断开连接后仍会保留
• 可通过 Shell > tmux > Dashboard 打开仪表板

文档索引

文档	用途
Shortcuts.md	完整键盘快捷键参考
TmuxConfig.md	tmux 配置（.tmux.conf）指南
TmuxCommands.md	完整 tmux 命令参考

---

注意事项

• “重用上一个会话的目录”按配置文件和上下文分别设置： 使用 Cmd-N 新建窗口时会采用配置文件的窗口设置；使用 Cmd-T 新建标签页时会采用标签页设置。两者并不相同——当提示符在意外的目录中打开时，很容易让人困惑。
• tmux -CC 需要安装并启动 tmux 服务端： 如果 tmux 位于远程主机而 iTerm2 在本地，只有在 iTerm2 本身启动 SSH 时，tmux -CC attach 才能通过 SSH 工作；由生成子 shell 的脚本启动 SSH 则不行。
• Cmd-D 拆分会使用当前窗格的配置文件，而不是窗口默认配置： 如果会话期间配置文件发生变化（通过 shell 集成），新拆分的窗格会继承修改后的配置文件，可能带上不需要的环境变量或 PATH。
• Ctrl+b 前缀会与 readline 的 transpose-words 冲突： 使用 Vi 模式的用户若重新绑定它（set -g prefix C-a），要记住 Ctrl+a 也会与 screen 和 shell 的行首快捷键冲突——请选择 C-Space 之类未占用的组合键。
• Shell 集成会注入 OSC 1337 转义码： 捕获终端输出的管道（script、asciinema）最终会出现乱码控制序列；除非通过 Edit Session > Disable Shell Integration 按窗格禁用集成。
• 状态栏更新在主线程上运行： 运行耗时较长的自定义状态栏脚本（例如运行较慢的 git status 或云 CLI）会冻结整个终端——请将状态回调控制在 100ms 以内，或让其异步运行。