# Pi Tmux

> 指导 agent 正确使用 pi-tmux 扩展管理后台 tmux 进程。涵盖 run/peek/send/kill/list 五个 action 的使用时机与参数选择、silenceTimeout 与 watchInterval 的配置策略、completion/silence/watchdog 三种自动通知的响应方式，以及常见工作流模式（dev server、build、交互式程序、长时间训练）。适用于 agent 需要在后台运行命令、监控进程输出、与交互式程序通信时。

- Skill: `justcyl/pi-tmux-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add justcyl/pi-tmux-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justcyl/pi-tmux-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: justcyl (https://skillmd.com/u/justcyl)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/justcyl/pi-tmux-2

---


# pi-tmux

pi-tmux 是一个 pi 扩展，提供 `tmux` tool，将长时间运行的命令放到后台 tmux window 中。命令完成、进程安静、定时快照三种场景会自动向对话注入通知。

## When To Use

**用 tmux run**（而不是 bash）的场景：
- Dev server（`npm run dev`, `python manage.py runserver`）
- Build / compile（`cargo build`, `make -j8`）
- Test suite（`pytest`, `npm test`，尤其是可能跑几分钟以上的）
- File watcher（`tsc --watch`, `nodemon`）
- 训练任务（`python train.py`）
- 任何预期超过 10 秒的命令

**继续用 bash** 的场景：
- 快速查询命令（`ls`, `cat`, `grep`, `git status`, `git diff`）
- 一次性修改命令（`git commit`, `npm install`, `mkdir`）
- 预期秒级完成的短命令

**判断标准**：如果你不确定命令要跑多久，默认用 bash。只有明确知道会长时间运行时才用 tmux。

## Tool API Quick Reference

```
tmux run    command="npm run dev" name="dev-server" [cwd] [silenceTimeout] [watchInterval] [watchIntervalMax]
tmux peek   [window="dev-server" | window="all"]
tmux send   window="dev-server" [text="Y"] [keys="Enter"]
tmux kill   window="dev-server"
tmux list
tmux wait   window="build" [timeout=300]
```

## Core Principles

### 1. Run 之后立刻继续工作

`tmux run` 是非阻塞的。发出 run 后，**不要等待输出**，立刻做下一件事。命令完成后你会自动收到 `tmux-completion` 通知。

### 2. 给每个 window 起语义化的 name

```
✓ name="dev-server"     name="test-suite"     name="build"
✗ 不提供 name（自动从命令提取，不够清晰）
```

之后所有操作（peek/send/kill）都用 name 引用 window，不要用 index。

### 3. 不要主动轮询——等通知

三种通知会自动来：
- **tmux-completion**：命令退出（带 exit code + 最后 20 行输出）→ **需要你响应**
- **tmux-silence**：窗口安静超过阈值 → **需要你响应**（可能在等 input）
- **tmux-watchdog**：定时快照 → **仅供参考**，不需要响应

收到 completion 通知后，根据 exit code 判断下一步：
- exit 0 → 成功，继续后续任务
- exit 非 0 → peek 查看完整输出，诊断问题

## Parameter Strategy

### silenceTimeout

**什么时候用**：命令可能弹出交互式提示（Y/n、密码、确认）时。

```
tmux run command="npm init" name="init" silenceTimeout=10
```

收到 silence 通知后的决策树：

1. **peek** 查看输出
2. 如果是简单提示（Y/n, Enter to continue）→ **send** 回复
3. 如果是复杂交互（多步向导、需要大量输入）→ **kill** 并用非交互方式重跑
4. 如果只是命令运行慢（还在产出但偶尔停顿）→ 忽略，silence 会自动退避

**不需要用的场景**：`npm run dev`、`cargo build` 等不会提示交互的命令。

### watchInterval

**什么时候用**：长时间任务，你想看中间进度但不想手动 peek。

watchdog 内置指数回退（×1.5）和内容去重：
- 间隔从 `watchInterval` 开始，逐次增长，上限为 `watchIntervalMax`（默认 5 倍）
- 如果两次快照输出完全相同，跳过注入，不浪费上下文
- send 操作后自动重置回初始间隔

```
tmux run command="python train.py --epochs 100" name="training" watchInterval=60
```

典型配置：

| 场景 | watchInterval | watchIntervalMax | 效果 |
|------|--------------|-----------------|------|
| Build（1-5 分钟） | 30 | 省略（默认 150） | 30→45→68→102→150→150... |
| 训练（几十分钟） | 60 | 300 | 60→90→135→203→300→300... |
| 训练（几小时） | 60 | 600 | 更疏的长尾快照 |
| 不需要中间状态 | 不设 | — | — |

### silenceTimeout 与 watchInterval 的选择

**不要同时设置这两个参数。** 它们面向不同场景：

| | silenceTimeout | watchInterval |
|---|---|---|
| **目的** | 检测交互提示 | 观察长任务进度 |
| **适用** | 可能弹 Y/n 的命令 | 确定不交互的长任务 |
| **通知** | triggerTurn: true（要你响应） | triggerTurn: false（仅供参考） |

如果你不确定命令是否会交互，**只设 silenceTimeout**。
如果你确定命令不会交互、只是跑得久，**只设 watchInterval**。

## Workflow Patterns

### Pattern 1: Dev Server

```
tmux run command="npm run dev" name="dev-server"
→ 继续编辑代码
→ 需要看输出时: tmux peek window="dev-server"
→ 不再需要时: tmux kill window="dev-server"
```

Dev server 通常不会退出，所以不需要 silenceTimeout 也不需要 watchInterval。

### Pattern 2: Build + 后续任务（异步）

```
tmux run command="cargo build --release" name="build" watchInterval=30
→ 继续做其他事
→ 收到 tmux-completion (exit 0) → 继续部署/测试
→ 收到 tmux-completion (exit 非 0) → peek 查看错误，修复代码
```

### Pattern 2b: Build + 后续任务（同步等待）

当后续步骤**必须等 build 完成**才能开始时，用 `wait` 替代被动等通知：

```
tmux run command="cargo build --release" name="build"
tmux wait window="build" timeout=600
→ 阻塞直到 build 完成，拿到 exit code + 输出
→ exit 0 → 立刻继续部署
→ exit 非 0 → 立刻处理错误
```

**wait vs 等 completion 通知的区别**：
- `wait` 是同步阻塞——tool 调用不返回直到命令完成，agent 不能做别的
- completion 通知是异步——agent 可以继续做别的事，完成后才被通知

用 `wait` 的场景：明确需要结果才能继续（build → deploy、test → report）
不用 `wait` 的场景：不需要结果就能继续（dev server、file watcher）

### Pattern 3: 可能需要交互的命令

```
tmux run command="npx create-next-app my-app" name="create-app" silenceTimeout=15
→ 收到 tmux-silence → peek
→ 看到 "Would you like to use TypeScript? (Y/n)"
→ tmux send window="create-app" text="Y" keys="Enter"
→ 等下一次 silence 或 completion
```

### Pattern 4: 并行多任务

```
tmux run command="npm run dev" name="dev-server"
tmux run command="npm test -- --watch" name="test-watch"
tmux run command="tsc --watch" name="type-check"
→ tmux list 查看所有窗口状态
→ tmux peek window="all" 一次看全部输出
```

### Pattern 5: 长时间训练

```
tmux run command="python train.py" name="training" watchInterval=60 watchIntervalMax=300
→ 快照频率: 60s→90s→135s→203s→300s→300s...
→ 输出没变化时自动跳过
→ 训练结束收到 completion 通知
```

## Responding to Notifications

### tmux-completion（triggerTurn: true）

**你必须响应**。看到此通知时：

1. 检查 exit code
2. 如果成功，继续下一步工作流
3. 如果失败，peek 查看详细输出后诊断

### tmux-silence（triggerTurn: true）

**你必须响应**。看到此通知时：

1. peek 查看当前输出
2. 判断是否需要交互
3. send 回复 或 kill 重跑 或 忽略（silence 会自动退避）

### tmux-watchdog（triggerTurn: false）

**仅供参考**，不需要专门响应。快照会出现在对话历史中，当你后续做决策时可以参考。

## Anti-Patterns

❌ **run 之后立刻 peek** — 浪费一轮调用，等通知即可

❌ **用 bash 跑 dev server** — 会阻塞 agent

❌ **忘了 kill 不再需要的 window** — tmux list 检查，及时清理

❌ **对简单短命令用 tmux** — `git status` 不需要放后台

❌ **同一个 name 反复 run** — 先 kill 旧的再创建新的

❌ **设了 silenceTimeout 却不响应 silence 通知** — 这会让程序一直等

❌ **同时设 silenceTimeout 和 watchInterval** — 选一个，不要混用

## Slash Commands (User-facing)

用户可以使用的斜杠命令：
- `/tmux` — 在新终端标签页 attach 到 session
- `/tmux:cat` — 选择一个 window，将输出注入对话
- `/tmux:clear` — 杀掉所有空闲 window