govijr/terminal-mac

项目用途

traceslm 是一个 macOS 应用，用 Apple Virtualization 框架运行真正的 macOS 虚拟机。安装在 guest 内的辅助程序负责截屏和发送输入事件，宿主侧 CLI 把 guest 画面流式显示到 Ghostty、Kitty 或 iTerm2，并转发智能体操作，不会移动物理 Mac 的鼠标指针或修改剪贴板。它面向想让 computer-use 智能体在隔离 Mac 桌面里工作的开发者。

智能体通过 MCP 接入，可使用 screenshot、click、drag、scroll、type、key、status 等工具，配套 skill 描述「观察 → 操作 → 验证」的循环。CLI 还提供 up、start、stop、pause、resume 等生命周期命令。

运行要求

• Apple 芯片 Mac，macOS 14 或更高版本。
• 首次运行需联网从 Apple 下载兼容的 macOS 恢复镜像，也可使用已有的 .ipsw；需为缓存镜像和不断增长的虚拟磁盘预留空间（默认逻辑大小 64 GiB）。
• 终端内联查看器需要 Ghostty、Kitty 或 iTerm2。其他终端只能用原生 VM 窗口和智能体 CLI；暂不支持 tmux 透传和自动终端分屏。
• 从源码构建需要 Xcode 16+ 和 Swift 6。预编译版本不需要开发工具。

安装与启动

发布安装脚本会下载最新版本并在安装前校验 SHA-256，不需要管理员权限，也不修改 shell 配置；启动器放在 ~/.local/bin，运行文件放在 ~/.local/lib/terminal-mac。请把 ~/.local/bin 加入 PATH。

curl -fsSL https://github.com/govijr/terminal-mac/releases/latest/download/get.sh | bash
terminal-mac up

up 会下载并缓存兼容的恢复镜像，创建并启动虚拟 Mac，然后等待 guest 辅助程序就绪。首次启动会打开 VM 窗口进入 macOS 设置助手，请在其中创建 guest 账户。随后在 guest 内打开 Finder → /Volumes/My Shared Files/tools → TerminalMacGuest.app。辅助程序会安装自身，其按钮会打开 guest 的系统设置，用于授予「屏幕录制」和「辅助功能」权限；如果 macOS 提示，请重新打开它。宿主不需要这两项权限。两项权限授予完成后，CLI 会自动进入终端桌面。

在 Claude Code 中使用：

/plugin install terminal-mac --marketplace govijr/terminal-mac

也可以分别注册 MCP 服务器和 skill：

claude mcp add terminal-mac -- terminal-mac mcp
terminal-mac skills install

其他 MCP 客户端可使用 terminal-mac mcp --config 的输出；terminal-mac mcp NAME 用于 default 以外的虚拟机。有 skills 文件夹的智能体可运行 terminal-mac skills install --dir PATH，具体命令接口见 智能体文档。

终端查看与智能体控制

在查看器中，键盘输入、点击、拖拽、滚动、方向键和常用控制键都会转发给 guest。由于终端会占用 ⌘，Ctrl+G 会打开 Mac 快捷键面板，Ctrl+] 退出查看器但让 VM 继续运行。guest 辅助程序只在画面变化时推送帧，最高 30 fps，并在查看器离开 15 秒后停止推流；Kitty 和 Ghostty 通过共享内存接收画面。

智能体通过辅助程序操作 guest，例如：

terminal-mac action default screenshot --output /tmp/guest.png
terminal-mac action default click 640 400
terminal-mac action default type 'Hello from the agent'

命令返回 JSON，失败时以非零状态退出。截图返回宿主机上的本地 PNG 路径；坐标从左上角开始，使用 guest 显示点。snapshot 目前只是 screenshot 的别名，并不是无障碍树快照。

约束与隔离

• guest 是独立的 Mac，有自己的应用、文件、账户和权限，不继承宿主的应用或已登录会话，但 VM 仍消耗宿主的 CPU、内存和存储。
• 默认 NAT 网络允许 guest 访问互联网，也可能访问宿主机或局域网中的服务。这不是网络隔离环境；--offline 会移除 guest 网络设备，但部分需要联网的安装流程可能受影响。
• 只暴露两个共享：可读写的 control 邮箱和只读的 tools 文件夹。宿主主目录、项目目录、剪贴板、麦克风和摄像头均不挂载。辅助程序仅在 hw.model 以 VirtualMac 开头时运行，这是防止误在宿主执行的检查，不是硬件证明。
• guest 自动化需要 guest 保持登录、辅助程序运行，并在 guest 内授予屏幕录制和辅助功能权限；这些授权属于交互式设置。
• 发布包使用自签名、未经过 Apple 公证；README 说明干净 Mac 上的真实 guest 验收仍待完成，并将当前版本标为早期候选发布。
• 撰写时，VM 克隆、回滚检查点、无障碍快照、全自动 guest 设置、终端分屏和 tmux 传输均被列为后续工作。

HotRepo 点评

traceslm 出现在 HotRepo 2026-11-04 的新项目榜上，新增 268 Star 和 20 Fork。采集到的逐小时样本显示，2026-11-03 21:45 至 00:45 UTC 期间 Star 从 115 升到 268，早期增长很快。结合项目自身的早期候选发布说明，这更多反映初始关注，而非已验证的 guest 验收。README 对隔离边界、邮箱防护和待完成的干净 Mac 验收写得相当具体，对于把智能体控制权交给一台独立 Mac 的工具来说，这个侧重是合适的。