终端UI控制工具

tui-pilot

Give your AI agent eyes and hands inside any terminal UI.

中文文档

思考 剧作家，但适用于终端应用程序而不是浏览器。

tui-pilot 是一个 主控程序 允许AI代理在macOS上启动、观察和与真实终端应用程序交互的服务器。它在内部运行目标应用程序 tmux，在真实的终端窗口中渲染，通过macOS原生API捕获像素完美的PNG屏幕截图，并通过一套干净的MCP工具公开所有内容。

没有ANSI重新渲染。没有虚假的终端模拟。你的代理人所看到的正是人类所看到的。

建筑

三个平面在统一的MCP接口下协同工作：

|飞机|以责任为后盾| |---|---|---| | 控制 |tmux |会话生命周期、密钥分发、文本捕获| | 渲染 |WezTerm/GGhostty | GPU加速的真实终端渲染| | 截图 |Swift+CoreGraphics |原生窗口发现和像素完美的PNG捕获|

工作流程

A real session: OpenCode drives cc-switch through tui-pilot, with the agent trace on the left and the live terminal window on the right.

步骤3-4形成一个 观察动作循环：快照当前状态，决定输入，发送它，然后再次快照——根据需要多次。

工具

[！提示] 跑 tui_doctor 首先如果 tui_start 或 tui_snapshot 失败。它会告诉您选择了哪个后端，并提醒您授予屏幕录制权限。

需求

• macOS 具有活动的GUI会话
• Node.js 20.19+
• 子速率复用器
• WezTerm 或 幽灵
• Swiftc （Xcode命令行工具附带）
• 屏幕录制 启动应用程序的权限 tui-pilot

[！注意] 如果屏幕截图因权限错误而失败，请将屏幕录制授予生成服务器的任何应用程序——终端、iTerm或您的MCP客户端。

入门

1.让你的AI安装它（推荐）

如果您使用Claude Code、OpenCode或其他支持MCP的代理，请粘贴其中一个提示。

仅限MCP

Install `tui-pilot` into my MCP client. Use `/absolute/path/to/tui-pilot` as the project path, build anything that is needed, register it as a local stdio MCP server, and then run `tui_doctor`. Do not install the optional skill.

MCP+可选技能

Install `tui-pilot` into my MCP client. Use `/absolute/path/to/tui-pilot` as the project path, build anything that is needed, register it as a local stdio MCP server, and also install the optional local skill `tui-pilot-visual-check` if my client supports skills. After setup, run `tui_doctor` and tell me what still needs manual approval.

仅当您的客户支持本地技能时，才安装可选技能。

npm install
./scripts/build-window-helper.sh
npm run build

node /absolute/path/to/tui-pilot/dist/index.js

{
  "mcp": {
    "tui-pilot": {
      "type": "local",
      "enabled": true,
      "command": ["node", "/absolute/path/to/tui-pilot/dist/index.js"],
      "timeout": 30000
    }
  }
}

{
  "mcpServers": {
    "tui-pilot": {
      "command": "node",
      "args": ["/absolute/path/to/tui-pilot/dist/index.js"]
    }
  }
}

mkdir -p ~/.config/opencode/skills
cp -R .agents/skills/tui-pilot-visual-check ~/.config/opencode/skills/

用法

开发模式 （保存时自动重新加载）：

npm run dev

生产模式:

npm run build
node dist/index.js

后端选择

tui-pilot 自动按以下顺序检测渲染后端：WezTerm→ 幽灵。

用环境变量覆盖：

TUI_PILOT_TERMINAL_BACKEND=ghostty npm run dev

支持的值： auto, wezterm, ghostty.

快速示例

回购包括 fixtures/mini-tui.ts，用于测试的键盘驱动菜单：

1. tui_doctor      → confirm automaticChecksPassed is true
2. tui_start       → launch the fixture app
3. tui_snapshot    → read textView + inspect the PNG
4. tui_send_keys   → send "Down"
5. tui_snapshot    → confirm the selection moved
6. tui_stop        → clean up

屏幕截图和辅助二进制文件位于 .tui-pilot/.

测试

npm test              # run all tests
npm run typecheck     # type-check without emitting

路线图

• [x] macOS支持（WezTerm/GGhostty）
• []Linux支持（X11/Wayland截图后端）
• []Windows支持（Windows终端+本机捕获）

[！注意] 计划为Linux和Windows提供跨平台支持。敬请期待！

进一步阅读

• 建筑深度挖掘
• 手动测试指南