iTerm2 Control
Drive the user's iTerm2 terminal on macOS from the assistant. This is distinct from the assistant's own Bash/shell tool: commands run in a visible iTerm2 window the user can see and interact with.
When to use
- The user wants a command executed in their visible iTerm2 (e.g. "在 iTerm2 里跑一下", "让我看到终端输出").
- You want to open a dedicated tab/window/pane for a long-running process (dev server, watcher, build) so it stays visible and separate.
- You need to capture the output of a command that ran in iTerm2.
触发词（自动命中）
当用户的指令出现以下任一表述时，应优先调用本 skill（而非助手的沙箱 Bash）：
- 「在 iTerm2 里跑 / 执行 / 看一下」「让我看到终端输出」「在可见终端执行」
- 「开个新标签 / 新窗口 / 分屏跑」「iTerm2 里跑个 dev server / 构建 / 监听」
- 「抓取 / 捕获 iTerm2 当前输出」「把 iTerm2 里的内容导出来」
- 用户明确要求命令必须发生在他们肉眼可见的终端（演示、需交互、需长期驻留的进程）
Prerequisites
- iTerm2 installed at
/Applications/iTerm2.app(or running). The skill launches it if not running. osascript(built into macOS). No other dependencies.
Permissions (macOS, one-time)
Controlling iTerm2 via AppleScript requires macOS Automation permission. This is a security gate, not a skill bug:
capture/ read works without it.send/write/run/tab/window/split-*(anything that sends a command) requires it. You'll see error-10004(权限违例) if missing.
Grant it (one time):
1. The first time a write text command runs, macOS may pop a dialog: "[App] 想要控制 iTerm2" → click 允许 (Allow).
2. If no dialog appears (e.g. command runs from a background/non-GUI context), grant manually:
- 系统设置 → 隐私与安全性 → 自动化 (Automation)
- Find the app that runs your commands (the terminal app, or the app hosting WorkBuddy's shell) → enable iTerm2.
3. If you want the assistant to drive iTerm2, the permission must be granted to whatever app hosts the assistant's shell — approve the dialog the first time the assistant attempts it, then it persists.
Usage
Run the bundled helper:
"$HOME/.workbuddy/skills/iterm2-control/iterm2_ctl.sh" <subcommand> [args]
| Subcommand | Arg | Effect |
|---|---|---|
launch |
— | Ensure iTerm2 is running (opens it if needed). |
send |
COMMAND |
Run COMMAND in the current session. |
tab |
COMMAND |
Open a new tab and run COMMAND there. |
window |
COMMAND |
Open a new window and run COMMAND there. |
split-v |
COMMAND |
Split pane vertically (right) and run COMMAND. |
split-h |
COMMAND |
Split pane horizontally (bottom) and run COMMAND. |
run |
COMMAND [secs] |
send + wait secs (default 3) + capture. |
capture |
— | Dump the current session's scrollback to a temp file; prints the file path. |
Examples
S="$HOME/.workbuddy/skills/iterm2-control/iterm2_ctl.sh"
# Run a build in a fresh tab so it stays visible
"$S" tab "npm run dev"
# Run a long task in a new window and grab its output after 5s
"$S" run "python train.py" 5 # prints /tmp/iterm2_capture.XXXXXX.txt
# Multi-pane: split current pane and run two watchers
"$S" split-v "npm run watch:css"
"$S" split-h "npm run watch:js"
# Read what the current session shows
"$S" capture # prints path; then Read that file
Important rules
- Quote commands properly. Pass
COMMANDin single quotes so the user's shell does not expand$, backticks, or!before the helper sees it:
bash "$S" send 'export FOO="bar"; echo "$FOO"' - Capture writes to a temp file, not stdout. This keeps large scrollback out of the assistant's context (token-efficient). Read the printed path only when you need the output.
runwaits a fixed time, not for a prompt. Increasesecsfor slow commands, or usesendthencaptureafter the user confirms completion.- Never use this to run destructive commands the user hasn't approved — it acts on their live, visible terminal.
- If iTerm2 has no open window,
send/capture/split-*auto-create one (harmless).
常见问题（FAQ）
-
Q：
$、反引号、感叹号被吞或提前展开？
A：必须用单引号包裹COMMAND（见规则 #1），让 shell 原样传给脚本，避免助手侧先展开。 -
Q：报
-10004 权限违例？
A：macOS 自动化（Automation） 未授权。按「Permissions」一节给宿主 App 开启控制 iTerm2 的权限即可。 -
Q：
capture的输出去哪了？
A：写入/tmp/iterm2_capture.XXXXXX.txt并打印路径，不在 stdout——这是为省 token 的设计。用 Read 读该路径即可。 -
Q：
run还没跑完就 capture 了？
A：run只固定等待 N 秒（默认 3）。慢命令把秒数调大（如run "python train.py" 30），或改用send+ 用户确认后再capture。 -
Q：命令里内嵌的双引号被截断？
A：脚本escape_as已把"转义为\"；若仍异常，尽量改用单引号包裹内部字符串，避免命令内嵌双引号。 -
Q：没有开着的 iTerm2 窗口会报错吗？
A：不会。send/capture/split-*在窗口缺失时会自动创建一个（无害）。
How it works
iterm2_ctl.sh calls osascript with iTerm2's AppleScript dictionary:
write text sends a command to a session; create tab/window and split vertically/horizontally manage layout; get contents reads the full scrollback. Command strings are escaped for AppleScript (\ → \\, " → \").
