Tui Pilot

tui-pilot

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

= 20.19" />

中文文档

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

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

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

建筑

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

工作流程

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.

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

Other installation options

构建服务器

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

注册MCP服务器

将MCP客户端指向内置服务器：

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

对于开发，您可以将客户指向 npm run dev 相反。在分别存储命令和参数的客户端中，将其作为命令输入 npm 带args run 和 dev.

OpenCode示例：

{
  "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"]
    }
  }
}

如果要强制此服务器进程使用渲染后端，请设置 TUI_PILOT_TERMINAL_BACKEND 到 wezterm 或 ghostty 在您的客户端配置中。

可选技能

回购包括一项本地技能 .agents/skills/tui-pilot-visual-check.

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

重新启动MCP客户端，或打开一个新会话，以便重新加载MCP配置和可选技能。

验证安装

跑 tui_doctor 没有争论。

确认：

• automaticChecksPassed 是 true
• backend.selected 是您期望的终端后端吗
• manualChecksRequired 包括 screen-recording

tui_doctor 不会自动验证屏幕录制权限，因此请与进行一次实时检查 tui_snapshot 设置后。

用法

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

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提供跨平台支持。敬请期待！

进一步阅读

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