remorses/tuistory

TMUX for agents. let agents control & test terminal user interfaces. Like Playwright & agent-browser but for TUIs

tuistory – “面向 AI 代理的 tmux”

它是什么 – 一个 Node‑JS CLI（及库），在受管理的 PTY 会话中运行任意终端命令。会话在后台运行，AI 驱动的代理可以检查、等待、输入或截图，而人类可以随时连接到同一会话，看到代理所看到的内容。

为何对 AI/ML 重要 – 当前基于 LLM 的编码代理通常需要启动开发服务器或 REPL，然后轮询或休眠直到进程就绪。tuistory 为这些代理提供了确定性、事件驱动的控制：

读取日志（tuistory read），
等待特定输出（tuistory wait "ready"），
截取终端屏幕快照或截图，
输入字符或按键到进程，以及
重启/关闭进程 – 所有这些都通过立即返回的快速 CLI 调用完成。

工作原理

tuistory -- <command> 在后台 PTY 中启动命令，并注册一个会话名称（从 cwd 和命令自动生成，例如 myapp-next-dev）。
一个小守护进程将所有会话保存在内存中，并提供一个本地 WebSocket 服务器（绑定到 127.0.0.1），供 CLI 工具和代理与 PTY 通信。
人类可以通过 tuistory attach 连接任何会话，其行为类似于 tmux attach – 他们可以看到实时终端，进行交互，然后按两次 Ctrl+C 分离。
代理使用同一 CLI（或以编程方式 API）来读取输出、等待模式、输入、按键、捕获屏幕截图等。

主要 CLI 命令

命令	用途
`tuistory -- <cmd>`	启动新会话（如果已存在则重新连接）。
`tuistory read -s <name> [--all]`	返回自上次读取以来的新 stdout（或整个缓冲区）。
`tuistory wait -s <name> <pattern>`	阻塞直到给定的文本/正则表达式出现。
`tuistory wait-idle -s <name>`	阻塞直到终端静默一段可配置的时间。
`tuistory snapshot -s <name> [--trim]`	获取当前屏幕的纯文本。
`tuistory screenshot -s <name>`	将屏幕保存为 PNG 图片。
`tuistory type -s <name> "text"`	将字符逐个输入到进程。
`tuistory press -s <name> <key>`	发送一个键或组合键（例如 `ctrl c`）。
`tuistory restart -s <name>`	在同一会话中重启原始命令。
`tuistory close -s <name>`	终止进程并删除会话。
`tuistory attach -s <name>`	仅限人类的交互式连接（类似 tmux）。
`tuistory sessions`	列出所有活动会话。

编程接口 – 相同的功能以 TypeScript 库的形式提供：

import { launchTerminal } from 'tuistory'
const sess = await launchTerminal({ command: 'claude', cols:150, rows:45 })
await sess.waitForText('Claude Code')
await sess.type('what is 2+2?')
await sess.press('enter')
const out = await sess.read()
sess.close()

API 与 CLI 对应：type、press、text、read、waitForText、click、close 等。

基于 LLM 的编码代理的典型工作流

# 1️⃣ 在后台会话中启动工具（例如 Web 开发服务器）
tuistory -s dev -- pnpm dev

# 2️⃣ 等待服务器输出 "ready"
tuistory -s dev wait "ready" --timeout 30000

# 3️⃣ 代理现在可以执行进一步操作，例如打开浏览器、运行测试等
# 4️⃣ 当人类想要查看正在发生的事情时：
#    $ tuistory attach -s dev

所有步骤对代理来说都是非阻塞的，无需任意 sleep 调用。

安装

npm install -g tuistory   # 全局 CLI
# 或作为项目依赖
npm install tuistory

运行 tuistory --help 查看完整选项列表。

适用于谁

构建 LLM 编排自动化（例如 Claude Code、Auto‑GPT 风格代理）并需要可靠终端交互的开发者。
希望无间断睡眠地编写交互式 CLI 工具（REPL、调试器）脚本的测试工程师。
已经在使用 tmux 处理后台进程，但希望获得 机器可读 接口的人。

相关项目 – tuistory 驱动了作者的 termcast（类似 Raycast 的终端 UI）和 kimaki（控制 TUI 的 Discord 机器人代理）。

许可证 – MIT。