mcpField
T
tmux

tmux

github.com/mitsuhiko开发3.2k411 次安装5 周前更新
代码仓库

关于 tmux

此 Skill 指导 Agent 使用 tmux 管理交互式终端任务，涵盖隔离 socket、窗格交互、轮询和清理流程，适用于运行及监控命令行工具。

主要功能

  1. 01使用隔离的 tmux socket
  2. 02创建并定位会话与窗格
  3. 03发送输入并捕获输出
  4. 04轮询提示符或完成状态
  5. 05查找并清理会话

适用场景

  1. 01运行交互式 Python REPL
  2. 02检查调试器会话
  3. 03监控长时间运行的命令
  4. 04隔离 Agent 的终端会话

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mitsuhiko/agent-stuff --skill tmux

安装后在 Claude Code 中输入/tmux确认已加载。

附带文件scripts/find-sessions.shscripts/wait-for-text.sh

详细介绍

tmux 技能

将 tmux 用作可编程终端复用器，处理交互式工作。适用于使用原版 tmux 的 Linux 和 macOS；使用私有套接字，避免自定义配置。

快速入门（隔离套接字）

SOCKET_DIR=${TMPDIR:-/tmp}/claude-tmux-sockets  # well-known dir for all agent sockets
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/claude.sock"                # keep agent sessions separate from your personal tmux
SESSION=claude-python                           # slug-like names; avoid spaces
tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'python3 -q' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200  # watch output
tmux -S "$SOCKET" kill-session -t "$SESSION"                   # clean up

启动会话后，务必告知用户如何监控会话，并提供一条可供复制粘贴的命令：

To monitor this session yourself:
  tmux -S "$SOCKET" attach -t claude-lldb

Or to capture the output once:
  tmux -S "$SOCKET" capture-pane -p -J -t claude-lldb:0.0 -S -200

必须在会话启动后立即打印这条命令，并在工具调用循环结束时再打印一次。不过，越早发送，用户就越满意。

套接字约定

  • Agent 必须将 tmux 套接字放在 CLAUDE_TMUX_SOCKET_DIR 下（默认为 ${TMPDIR:-/tmp}/claude-tmux-sockets），并使用 tmux -S "$SOCKET"，以便我们枚举和清理套接字。先创建目录：mkdir -p "$CLAUDE_TMUX_SOCKET_DIR"。
  • 除非需要进一步隔离，否则使用默认套接字路径：SOCKET="$CLAUDE_TMUX_SOCKET_DIR/claude.sock"。

定位窗格和命名

  • 目标格式：{session}:{window}.{pane}；省略时默认为 :0.0。名称应简短（例如 claude-py、claude-gdb）。
  • 始终使用 -S "$SOCKET"，确保使用私有套接字路径。如果需要用户配置，请去掉 -f /dev/null；否则，-f /dev/null 会提供干净的配置。
  • 检查：tmux -S "$SOCKET" list-sessions、tmux -S "$SOCKET" list-panes -a。

查找会话

  • 使用元数据列出活动套接字上的会话：./scripts/find-sessions.sh -S "$SOCKET"；添加 -q partial-name 可进行筛选。
  • 扫描共享目录下的所有套接字：./scripts/find-sessions.sh --all（使用 CLAUDE_TMUX_SOCKET_DIR 或 ${TMPDIR:-/tmp}/claude-tmux-sockets）。

安全发送输入

  • 优先使用字面量发送，避免 shell 拆分：tmux -L "$SOCKET" send-keys -t target -l -- "$cmd"
  • 组合内联命令时，使用单引号或 ANSI C 引号，避免展开：tmux ... send-keys -t target -- $'python3 -m http.server 8000'。
  • 发送控制键：tmux ... send-keys -t target C-c、C-d、C-z、Escape 等。

查看输出

  • 捕获最近的历史记录（合并行以避免换行造成的显示问题）：tmux -L "$SOCKET" capture-pane -p -J -t target -S -200。
  • 持续监控时，使用下方的辅助脚本轮询，而不是使用 tmux wait-for（它不会监控窗格输出）。
  • 也可以临时附加到会话以进行观察：tmux -L "$SOCKET" attach -t "$SESSION"；按 Ctrl+b d 分离。
  • 向用户提供说明时，务必明确打印可供复制粘贴的监控命令，并将其与操作说明一起提供；不要假设他们记得这条命令。

启动进程

针对进程的一些特殊规则：

  • 用户要求调试时，默认使用 lldb
  • 启动 Python 交互式 shell 时，始终设置 PYTHON_BASIC_REPL=1 环境变量。这非常重要，因为非基础控制台会干扰 send-keys。

同步／等待提示符

  • 使用定时轮询，避免与交互式工具发生竞态。例如，在发送代码前等待 Python 提示符： 
    ./scripts/wait-for-text.sh -t "$SESSION":0.0 -p '^>>>' -T 15 -l 4000
  • 对于长时间运行的命令，在继续操作前轮询其完成文本（"Type quit to exit"、"Program exited" 等）。

交互式工具操作示例

  • Python REPL：tmux ... send-keys -- 'python3 -q' Enter；等待 ^>>>；使用 -l 发送代码；使用 C-c 中断。始终设置 PYTHON_BASIC_REPL。
  • gdb：tmux ... send-keys -- 'gdb --quiet ./a.out' Enter；使用 tmux ... send-keys -- 'set pagination off' Enter 禁用分页；使用 C-c 中断；执行 bt、info locals 等命令；通过 quit 退出，然后确认 y。
  • 其他 TTY 应用（ipdb、psql、mysql、node、bash）：采用相同模式——启动程序，轮询等待提示符，然后发送字面文本并按 Enter。

清理

  • 完成后终止会话：tmux -S "$SOCKET" kill-session -t "$SESSION"。
  • 终止套接字上的所有会话：tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t。
  • 清除私有套接字上的所有内容：tmux -S "$SOCKET" kill-server。

辅助脚本：wait-for-text.sh

./scripts/wait-for-text.sh 会轮询窗格，等待匹配正则表达式（或固定字符串），并在超时后退出。适用于安装了 bash、tmux 和 grep 的 Linux/macOS。

./scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]
  • -t/--target 窗格目标（必填）
  • -p/--pattern 要匹配的正则表达式（必填）；添加 -F 可匹配固定字符串
  • -T 超时时间（秒，整数，默认值为 15）
  • -i 轮询间隔（秒，默认值为 0.5）
  • -l 要从窗格搜索的历史行数（整数，默认值为 1000）
  • 首次匹配时以状态码 0 退出，超时时以状态码 1 退出。失败时，会将最后捕获的文本打印到 stderr，以帮助调试。

评论

支持 Markdown