Tars Vibe 项目

Tars 是什么

Tars 是一款将 iPhone 转变为 AI Agent 可视化状态面板的开源工具，由 Mac 菜单栏 App + iOS App 组成，通过本地网络（Bonjour/TCP）实时同步 AI 编程工具的运行状态。灵感来自电影《星际穿越》中的 TARS 机器人，用两个像素眼睛的四种表情变化，让你无需盯着终端也能远程掌握 Agent 工作进展。

核心功能

• 全屏像素表情面板：iPhone 全屏显示 TARS 风格的像素眼睛，支持多种主题（Eva、Pika、Miku 等），AMOLED 黑色背景省电护眼
• 四种状态直观呈现：空闲（眼睛安静）→工作中（眼睛闪烁）→待批准（眼睛瞪大）→完成（眼睛弯成笑弧），余光一扫便知当前状态
• 细节信息下钻：面板底部显示当前工具名称、待处理问题或最近一条助手回复，裁剪至两行
• Mac 菜单栏 App：无需账号、不扫描文件，通过监听 Claude Code / Codex / opencode / pi 的生命周期钩子事件，将 Agent 状态实时推送至配对手机
• 零入侵 Agent 集成：采用官方生命周期钩子而非日志抓取，安装后自动为 Claude Code、Codex、opencode、pi 各自安装对应 hook 脚本，不影响原有工作流
• 隐私优先：跨网络仅传输会话 ID 的 SHA-256 前缀、状态词和一行详情文本（≤160 字符），数据不落盘
• 多 Agent 并发监控：支持同时监控多个 Agent 会话，通过优先级 approval → working → completed → waiting 自动汇聚状态
• 主题生态：支持自定义像素主题，欢迎社区 PR 贡献更多主题风格

技术实现

Tars 的架构分为四个层次：

第一层：Agent Hooks Mac 上的 hook.py 脚本注册到各 Agent 的生命周期事件（SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、Stop 等），将事件映射为四种状态之一，通过 127.0.0.1:17894 本地端口推送。该脚本始终以 async 方式注册，不会阻塞 Agent 运行。

第二层：状态机模型 事件→状态映射规则清晰：会话启动或空闲提示触发「等待」，用户提交或工具执行中触发「工作中」，权限请求触发「待批准」，Agent 停止触发「完成」并保持 5 秒后消失。无新事件时静默会话 30 分钟后自动过期。

第三层：传输层 Mac 通过 Bonjour 广播 _tars._tcp 服务，iPhone 首次连接发送六位配对码验证身份，之后接收以换行分隔的 JSON 快照（含会话 UUID、单调序列、状态、源可用性、心跳间隔、详情行）。活跃时心跳 20 秒一次，空闲时 120 秒一次，iPhone 支持后台自动重连。

第四层：iPhone 渲染层 纯色的像素眼睛由 12×12 位图实时绘制，表情变化通过位图切换和颜色变化传达状态，所有主题均为原创像素艺术，无授权图片使用。

快速上手

1. Mac 端安装：克隆仓库，执行 xcodebuild 构建 TarsMac.app 并放入 /Applications，随后打开菜单栏应用
2. Agent 连接：在菜单栏应用设置中，进入 Agents 选项卡，开启 Claude Code / Codex / opencode / pi 之一，Codex 用户需额外在 Codex 内执行 /hooks 并信任 Tars 条目
3. iPhone 端安装：用 Xcode 打开 Tars.xcodeproj，选择团队和目标设备后运行，允许本地网络访问
4. 配对：iPhone 首次启动后 2 秒若未配对会显示 PIN 输入界面，在 Mac 设置窗口读取六位码输入即配对成功
5. 启动体验：开启任意 Agent 会话，iPhone 上的 TARS 眼睛随即激活工作，实时反映 Agent 状态

适用人群

• AI 编程重度用户：日常使用 Claude Code、Codex 等工具进行长时间代码开发，需要随时了解 Agent 进展而不愿频繁切换窗口
• 多任务并行开发者：同时运行多个 Agent 会话，需要集中监控各会话状态
• 远程工作场景用户：Agent 在服务器或远程机器运行，本地屏幕只用来监控，用 iPhone 从房间任何角落获取状态更新
• 极客玩家：对《星际穿越》TARS 机器人有情怀，喜欢像素艺术和工具定制

相关链接

• GitHub 仓库：https://github.com/reycn/tars
• 中文文档：doc/README.zh-CN.md