imprint
Lets AI agents control a terminal and see what's on screen via MCP, allowing precise TUI testing.
概述
Imprint提供了一个AI代理可以编程控制的真实终端。代理可以随时请求终端的屏幕截图，让他们能够精确地看到用户会看到什么。
这让代理可以像真实用户一样进行测试——与终端交互，查看屏幕上的实际内容，而不管应用程序是如何构建的。TUI测试变得与框架无关，允许您测试任何终端应用程序，而无需学习或使用其内部测试策略。
它是如何工作的：
- ttyd：Web终端守护进程通过WebSocket暴露真实的PTY
- 终端复用器：终端多路复用器支持AI和用户之间的会话共享
- 加油杆：用于键盘输入和屏幕截图的无头Chrome自动化
- xterm.js：在Chrome中运行的终端模拟器，用于像素完美渲染
特性
- MCP本地：通过stdio协议直接集成Claude代码
- 真实终端：实际的shell执行，而不是模拟
- 像素完美截图：这正是你在真实终端中看到的
- 框架不可知：在没有框架特定工具的情况下测试任何TUI应用程序
- 实时会话共享：通过浏览器观看AI实时控制终端
安装
curl -fsSL https://raw.githubusercontent.com/kessler-frost/imprint/main/install.sh | sh这将安装印记及其依赖项（ttyd和tmux）（如果尚未安装）。
卸载
curl -fsSL https://raw.githubusercontent.com/kessler-frost/imprint/main/install.sh | sh -s -- --uninstall手动安装
如果您更喜欢手动安装：
- 安装ttyd和tmux：
# macOS
brew install ttyd tmux
# Ubuntu/Debian
sudo apt install ttyd tmux
# Arch Linux
sudo pacman -S ttyd tmux- 从下载印记 发布 或者：
go install github.com/kessler-frost/imprint/cmd/imprint@latest用法
Imprint旨在由Claude Code作为MCP服务器启动。请参阅下面的配置。
手动测试
# Run imprint directly (MCP on stdio)
imprint
# Options
imprint --help
--shell Shell to run (default: $SHELL)
--rows Terminal rows (default: 24)
--cols Terminal columns (default: 80)
--version Print version and exitMCP服务器（克劳德代码）
添加印记作为MCP服务器：
claude mcp add imprint -- ~/.local/bin/imprint使用自定义终端尺寸：
claude mcp add imprint -- ~/.local/bin/imprint --rows 30 --cols 120可用工具
send_keystrokes-发送按键（例如。，["enter"],["up", "up", "enter"])type_text-键入字符串get_screenshot-以base64 JPEG格式获取屏幕get_screen_text-以纯文本形式获取屏幕get_status-获取终端状态get_ttyd_url-获取web URL和tmux附加命令以查看代理正在使用的终端resize_terminal-调整终端大小restart_terminal-重新启动终端（可选地使用新命令）wait_for_text-等待文本出现在屏幕上（默认超时5秒）wait_for_stable-等待屏幕停止变化（500毫秒稳定持续时间）
实时观看AI
imprint的一个独特功能是能够在浏览器中实时观看AI代理对终端的控制。您和AI共享相同的tmux会话。
要查看终端：
- 让AI打电话
get_ttyd_url - 通过以下任一方法连接：
- 浏览器：打开网络URL（例如。， http://127.0.0.1:55529) - 终端：运行tmux附加命令（例如。， tmux attach -t imprint_55529)
- 观察AI键入命令并导航终端
您还可以通过浏览器与终端进行交互，人工智能将实时看到您的更改。这有助于：
- 调试：看看AI到底看到了什么
- 协作：当AI陷入困境时帮助它
- 德莫斯：向其他人展示AI代理如何与终端交互
例子
这 examples/ 目录包含用于测试印记的演示应用程序：
屏幕截图演示
泡泡茶TUI 需要屏幕截图分析的视觉元素:
- 随机颜色：启动时随机选择彩色方块-显示文本提取
████但屏幕截图显示了实际颜色 - 视觉缺陷：只能通过屏幕截图检测到的故意渲染问题（标题错位、颜色渗出、对比度差）
这说明了为什么 get_screenshot 有价值——有些东西只能通过实际操作来验证 *看见* 终端。
文本演示
一个使用ASCII字符的简单的基于文本的TUI。适合测试 get_screen_text 以及基本的键盘导航。
发生了什么变化
一款视觉记忆游戏，旨在展示印记的截图功能。游戏显示了一个彩色单元格网格，然后更改了一个单元格——玩家必须确定更改了哪个单元格。非常适合测试AI代理检测屏幕截图之间视觉差异的能力。
测试
单元测试（Go）
go test ./...端到端测试（Python）
这 tests/ 该目录包含端到端测试，用于验证印记是否与真实的AI代理正常工作。这些测试使用 Claude 代码 SDK 生成Claude，然后Claude使用imprint的MCP工具与示例TUI进行交互。
为什么是Python？ Claude Code SDK仅在Python和TypeScript中可用。由于目标是从AI代理的角度测试印记（而不仅仅是Go代码的单元测试），我们使用SDK让Claude实际控制终端，并验证它是否可以完成导航菜单、切换复选框和识别视觉错误等任务。
cd tests
uv sync # Install dependencies
uv run pytest # Run all tests单个测试文件：
test_text_demo.py-测试基于文本的导航和交互test_screenshot_demo.py-通过屏幕截图测试视觉错误检测test_what_changed.py-测试内存游戏的屏幕截图比较
建筑
flowchart TB
subgraph imprint
MCP["MCP Server
(stdio)"]
TM["Terminal Manager
(go-rod + ttyd)"]
TMUX["tmux session
(shared terminal)"]
TTY["ttyd + Chrome/xterm
(real PTY + render)"]
MCP --> TM
TM --> TTY
TTY --> TMUX
end
Claude["Claude Code"] -->|"JSON-RPC over stdio"| MCP
Browser["Your Browser"] -->|"WebSocket via ttyd"| TMUXAI和浏览器连接到同一个tmux会话，实现实时协作。
贡献
欢迎投稿！我在空闲时间处理印记，所以回复可能需要一段时间，但我很感激所有的公关和问题。
许可证
Apache 2.0