Agent Watch

通过 Apple Watch 控制 Claude Code。
查看终端输出、批准权限请求、发送语音指令——一切尽在腕间。

https://github.com/user-attachments/assets/5f478c28-2086-4696-9d76-e43dda853201 ``` WCSession Apple Watch <===============> iPhone <=======> Mac (SwiftUI) sendMessage (Relay) HTTP Bridge Server transferUserInfo SSE (Node.js) | HTTP Hooks | PTY stdin v Claude Code Session ``` ## 功能特性 - **实时终端输出** 显示在您的 Apple Watch 上 —— 实时查看 Claude 的操作动态 - **权限提示** —— 直接在手腕上批准或拒绝 Claude 的操作（编辑文件？运行命令？） - **动态问答** —— 回答包含所有选项的 `AskUserQuestion` 提示 - **语音指令** —— 通过 watchOS 听写功能向 Claude 口述指令 - **iPhone 伴侣应用** —— 配对界面、连接状态、终端预览、权限审批 - **桥接服务器** —— 运行在 Mac 上的 Node.js 服务器，通过 HTTP hooks + SSE 连接 Claude Code 与手表 ## 系统架构 该系统包含三个组件： ### 1. 桥接服务器 (Mac) 一个 Node.js HTTP 服务器 (`skill/bridge/server.js`)，其功能如下： - 通过 [HTTP hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) 接收来自 Claude Code 的事件（`PostToolUse`、`PermissionRequest`、`Stop` 等） - 通过 Server-Sent Events (SSE) 将事件流式传输给已连接的客户端 - 处理 6 位数字代码 + session token 的配对 - 通过 Bonjour/mDNS 在本地网络上广播自身 - 阻塞 `PermissionRequest` hooks —— 等待手表/手机批准，然后将决定返回给 Claude Code ### 2. iPhone App 一个 SwiftUI iOS 应用，其功能如下： - 通过 Bonjour 发现桥接（或使用 localhost 回退） - 使用 6 位数字代码进行配对 - 显示连接状态 + 终端输出 - 显示交互式权限提示（Yes / Yes all / No） - 通过 WCSession 将事件中继到 Apple Watch ### 3. watchOS App 一个 SwiftUI watchOS 应用，其功能如下： - 通过 Wi-Fi 直接连接到桥接（Bonjour 或手动输入 IP） - 显示实时终端输出（Read, Edit, Bash, Grep 操作） - 显示包含所有选项的权限提示，以可滚动按钮形式呈现 - 支持通过 watchOS 听写进行语音指令输入 - 针对任务完成、批准和错误提供触觉反馈 ## 快速开始 ### 前置条件 - 安装了 Node.js 18+ 的 macOS - 安装了 watchOS SDK 的 Xcode 16+ - Apple Watch 需与您的 Mac 连接同一 Wi-Fi - 已安装 Claude Code CLI ### Apple Watch Wi-Fi 设置 1. 确保您的 Apple Watch 连接到与运行 Claude Code 会话的 Mac **相同的 Wi-Fi 网络** 2. 在您的 Apple Watch 上，前往 **设置 > Wi-Fi > 您的网络** 并将 **私有 Wi-Fi 地址** 设置为 **关闭** —— 这是 Bonjour/mDNS 在本地网络上可靠工作的必要条件 ### 1. 安装桥接 ``` cd skill/bridge npm install ``` ### 2. 安装 Claude Code hooks 这将配置所有 Claude Code 会话以将事件流式传输到桥接： ``` ./skill/setup-hooks.sh ``` 稍后如需移除 hooks：`./skill/setup-hooks.sh --remove` ### 3. 启动桥接服务器 ``` cd skill/bridge node server.js ``` 您将看到： ``` ╔═══════════════════════════════════════╗ ║ AGENT WATCH BRIDGE ║ ╠═══════════════════════════════════════╣ ║ Pairing Code: 648505 ║ ║ IP Address: 192.168.1.4 ║ ║ Port: 7860 ║ ╚═══════════════════════════════════════╝ ``` ### 4. 构建 iOS + watchOS 应用 ``` cd ios/ClaudeWatch xcodegen generate # Generates the .xcodeproj open ClaudeWatch.xcodeproj ``` 在 Xcode 中： 1. 在两个目标（ClaudeWatch + ClaudeWatchWatch）上设置您的 **开发团队** 2. 选择 **ClaudeWatch** scheme 用于 iPhone，或选择 **ClaudeWatchWatch** 用于手表 3. 构建并运行 (Cmd+R) ### 5. 配对 **iPhone：** 输入桥接横幅中显示的 6 位配对代码。 **Apple Watch：** 应用会通过 Bonjour 自动发现桥接。如果失败，请手动输入桥接横幅中显示的 IP 地址。 ### 6. 正常使用 Claude Code 在终端中启动任何 Claude Code 会话。每一次工具调用（Read, Edit, Bash, Grep）都会实时流式传输到手表和手机。权限提示将以交互式卡片形式出现。 ## 项目结构 ``` claude-watch/ ├── skill/ │ ├── bridge/ │ │ ├── server.js # Bridge server (HTTP + SSE + Bonjour) │ │ └── package.json # Node.js dependencies │ ├── setup.sh # Install bridge dependencies │ ├── setup-hooks.sh # Install/remove Claude Code hooks │ └── SKILL.md # Claude Code skill definition │ ├── ios/ClaudeWatch/ │ ├── project.yml # XcodeGen project spec │ │ │ ├── Shared/ # Shared between iOS + watchOS │ │ ├── Models/ │ │ │ ├── SessionState.swift │ │ │ ├── TerminalLine.swift │ │ │ ├── ApprovalRequest.swift │ │ │ ├── WatchMessage.swift │ │ │ └── OutputRingBuffer.swift │ │ ├── Connectivity/ │ │ │ └── WatchSessionManager.swift │ │ └── Extensions/ │ │ ├── Color+Hex.swift │ │ └── ClaudeMascot.swift # Official Claude logo as SwiftUI Shape │ │ │ ├── ClaudeWatch iOS/ # iPhone app │ │ ├── App/ClaudeWatchApp.swift │ │ ├── Views/ │ │ │ ├── PairingView.swift # 6-digit code entry │ │ │ ├── ConnectionStatusView.swift # Terminal + status │ │ │ └── SettingsView.swift │ │ ├── Networking/ │ │ │ ├── BonjourDiscovery.swift # LAN bridge discovery │ │ │ ├── BridgeClient.swift # HTTP client │ │ │ └── SSEClient.swift # Server-Sent Events │ │ └── Services/ │ │ ├── RelayService.swift # Coordinates bridge <-> watch │ │ └── NotificationService.swift │ │ │ └── ClaudeWatch watchOS/ # Apple Watch app │ ├── App/ClaudeWatchWatchApp.swift │ ├── Views/ │ │ ├── OnboardingView.swift # Pairing (Bonjour + manual IP) │ │ ├── SessionView.swift # Terminal output + mic FAB │ │ ├── ApprovalView.swift # Dynamic permission prompts │ │ ├── VoiceInputView.swift # Dictation input │ │ └── StatusDashboard.swift │ ├── Services/ │ │ ├── WatchViewState.swift # Watch-specific state + SSE │ │ ├── WatchBridgeClient.swift # Direct HTTP to bridge │ │ ├── HapticManager.swift │ │ └── SpeechService.swift │ └── Complications/ │ └── ComplicationProvider.swift │ └── .claude/skills/claude-watch/ └── SKILL.md # /claude-watch skill for Claude Code ``` ## 工作原理 ### 事件流 (Mac -> Watch) 1. Claude Code 运行一个工具（例如，编辑文件） 2. `PostToolUse` HTTP hook 触发，POST 数据到桥接服务器 3. 桥接将事件推送给所有已连接的 SSE 客户端 4. 手表/手机接收 SSE 事件并将其渲染为终端行 ### 权限流 (Mac -> Watch -> Mac) 1. Claude Code 遇到权限提示（例如，“您要编辑此文件吗？”） 2. `PermissionRequest` HTTP hook 触发 —— 桥接 **阻塞** 响应 3. 桥接推送包含问题 + 选项的 `permission-request` SSE 事件 4. Watch 显示批准表单，所有选项均显示为可点击按钮 5. 用户点击一个选项 —— 手表通过 HTTP 将决定发回桥接 6. 桥接将决定返回给 Claude Code 的 hook —— Claude 继续或停止 ### AskUserQuestion 流程 与权限流程相同，但 hook 数据包含带有动态选项（label + description）的 `tool_input.questions`。手表将这些渲染为与终端编号选项相匹配的可滚动列表。 ## Claude Code Hooks `setup-hooks.sh` 脚本会在 `~/.claude/settings.json` 中全局安装这些 HTTP hooks： | Hook 事件 | 用途 | 是否阻塞? | |-----------|---------|-----------| | `PostToolUse` | 捕获工具输出（文件读取、编辑、命令） | No (async) | | `PreToolUse` | 捕获工具调用 | No (async) | | `PermissionRequest` | 将权限提示转发到手表 | **Yes** (最长 10 分钟) | | `Stop` | 检测 Claude 何时完成响应 | No (async) | | `PostToolUseFailure` | 捕获错误 | No (async) | | `StopFailure` | 捕获 API 错误 | No (async) | | `Notification` | 空闲/权限通知 | No (async) | ## 配置 ### 桥接服务器 | 环境变量 | 默认值 | 描述 | |---------|---------|-------------| | `PORT` | 7860 | 起始端口（尝试 7860-7869） | ### 移除 Hooks ``` ./skill/setup-hooks.sh --remove ``` ### 取消配对 - **iPhone：** 设置 > 忘记 Mac - **Watch：** 重启应用（当桥接重启时凭据会清除） ## 系统要求 | 组件 | 最低版本 | |-----------|----------------| | macOS | 13.0+ | | Node.js | 18+ | | Xcode | 16+ | | iOS | 17.0 | | watchOS | 10.0 | | Claude Code | 2.1+ | ## 故障排除 ### 手表显示“未找到桥接” - 确保您的 Mac 上正在运行 `node server.js` - 检查您的手表是否连接到同一个 Wi-Fi 网络 - 使用“手动输入 IP”选项，输入桥接横幅中显示的 IP ### 手表显示“不支持的架构” - 在 Xcode 中清理构建文件夹 (Cmd+Shift+Option+K) - 选择正确的 scheme：**ClaudeWatchWatch**（而不是 ClaudeWatch） - 如果直接部署到手表失败，请通过已配对的 iPhone 目标进行部署 ### iPhone 显示“连接失败” - 检查桥接是否正在运行 (`curl http://127.0.0.1:7860/status`) - 桥接必须与 iPhone 处于同一局域网 ### 权限提示未在手表上显示 - 验证 hooks 是否已安装：检查 `~/.claude/settings.json` 中的 hook 条目 - 检查桥接日志中是否有“Hook: PermissionRequest received” - 确保手表已连接到桥接（绿色状态点） ### 桥接立即退出 - 桥接不再自动生成 Claude。它等待来自 hooks 的事件。 - 在单独的终端中启动 Claude Code —— hooks 将自动转发事件。 ## 许可证 MIT

标签：AI编程助手, Apple Watch, bridged连接, Claude API, Claude Code, GNU通用公共许可证, HTTP Hooks, iOS开发, iPhone伴侣应用, LLM工具, Mac服务器, MITM代理, Node.js, Server-Sent Events, SSE, SwiftUI, watchOS, 人机交互, 可穿戴设备, 安全审批, 实时输出, 智能手表控制, 权限管理, 模型越狱, 移动开发, 终端监控, 蓝牙/WiFi通信, 语音命令, 远程控制