在手机上观测和控制本机所有 AI 编码 agent —— Claude Code、Codex、Cursor、ChatGPT Desktop 等一网打尽。
差异化定位：相比 Happy（SaaS + wrapper）和 HAPI（self-hosted wrapper），AgentPulse 走 Observer 路线 —— 不取代 claude 的启动方式，而是"贴边监控"已经运行的 agent 进程，包括 Happy/HAPI 都管不了的桌面 AI app（Codex Desktop、ChatGPT Atlas、Cursor、Claude Desktop）。
- Claude Code — CLI + VS Code 扩展 + 桌面 app，通过 JSONL 会话文件 + 原生 Hook 系统拿到完整状态（tool 调用、待审批、Plan Mode、token usage 等）
- Codex — CLI（JSONL） + 桌面 app（macOS Accessibility 抓取）+ ChatGPT Atlas / ChatGPT Desktop
- Cursor — 桌面 app，通过读取其 global SQLite DB 观测助手回复
- Gemini / GitHub Copilot / 自定义 CLI — 进程监测
- WebSocket + HTTP/REST + Server-Sent Events 三合一（port 8350）
- mDNS/Bonjour 局域网零配置自动发现（
_agentpulse._tcp） - SSH 隧道远程开发机监控（每 3s 同步远端 agents）
- Cloudflare Tunnel / ngrok 公网访问
- Live Activity + Widget：锁屏 / 灵动岛展示 agent 实时状态（Happy/HAPI 都没做）
- Push Notification：pending approval / 任务完成时提醒
- Budget 监控：手动设置美元预算 + 24h/7d token/cost 图表
- Pairing Token（AES-256 位随机）+ QR code 配对
- 三档模式
off/soft（默认）/strict（通过AGENTPULSE_AUTH_MODE控制） - Auth token 持久化到
~/.agentpulse/pairing-token.json（mode 0600）
- VS Code Bridge —— 通过 VS Code 扩展触发
claude-vscode.focus+ 剪贴板粘贴 - cmux —— 若用户装了 cmux 终端复用器，用其精确 API 投递
- tmux send-keys —— 对 tmux 内的 CLI agent 使用（即使 Terminal 已关闭也能送达）
- TTY 直写 —— 直接写
/dev/ttysN - osascript —— 激活应用 + AXRaise 指定窗口 + Cmd+V + Enter
┌─────────┐ ┌──────────────────────┐ ┌────────────────┐
│ iOS │ ws/rest│ Relay Server │ observe │ Local agents │
│ SwiftUI │◄───────►│ (Node + Express) │─────────► Claude / Codex│
│ App │ mDNS │ port 8350 │ │ / Cursor / ... │
└─────────┘ └──────────────────────┘ └────────────────┘
│
│ SSH tunnel
▼
┌──────────────────┐
│ Remote dev box │
│ (same relay) │
└──────────────────┘
详见 docs/communication-architecture.md。
cd relay-server
npm install
npm run build
npm start启动后会打印类似：
╔═══════════════════════════════════════════╗
║ AgentPulse Relay Server ║
╠═══════════════════════════════════════════╣
║ HTTP/REST : http://localhost:8350 ║
║ WebSocket : ws://localhost:8350/ws ║
╚═══════════════════════════════════════════╝
🔐 Pairing
Auth mode : soft (warnings only; set AGENTPULSE_AUTH_MODE=strict to enforce)
LAN URL : http://10.6.220.32:8350
Token : <UUID>
Pair URL : agentpulse://pair?host=10.6.220.32&port=8350&token=...
[QR 码]
需要：Xcode 15+、Apple 开发者账号（自签也行）。
./setup-xcode.sh # 通过 xcodegen 生成 .xcodeproj
open AgentPulse.xcodeproj在 Xcode 里选 target → 选设备 → Cmd+R。
两种方式，任选其一：
- Auto-discover（默认）：iPhone 和 Mac 在同一 WiFi，App 自动通过 mDNS 找到 relay
- 手动配对：Settings → Pairing → 粘贴启动日志里的
agentpulse://pair?...URL → Apply
默认 soft 模式对未认证请求只 log warning；准备好后：
AGENTPULSE_AUTH_MODE=strict npm start此后所有未带 token 的 WS/REST 请求会被 401 拒绝。
ssh <dev-box>
cd agentpulse-relay # 你把 relay 代码同步过去
npm install && npm run build && nohup npm start &回到 Mac 在 iOS App 里 Settings → Remote Hosts 添加 SSH 信息，relay 会自动建隧道 + 每 3s 拉远端 agent 列表合并进本地。
cd relay-server
npm test当前覆盖：
src/auth/pairing.test.ts— token 提取、常量时间比较 (13 tests)src/protocol/schema.test.ts— Zod 协议校验 (14 tests)src/utils/codex-ui-reader.test.ts— Codex AX 解析 (18 tests)
合计 45 个 tests，均通过。
| 场景 | 步骤 | 预期 |
|---|---|---|
| Claude Code CLI 监测 | 跑 claude → iOS 看到 agent |
agent 出现，状态随任务更新 |
| Claude Code 双向发送 | iOS 发消息 → CLI 收到 | 消息进 Claude input 并被执行 |
| Codex Desktop 回复观测 | 在 Codex Desktop 对话 → iOS 看到 | 回复出现在 iOS 聊天界面 |
| Cursor 回复观测 | 在 Cursor 对话 → iOS 看到 | 回复出现 (~3s 延迟) |
| tmux detached 发送 | tmux new -s x，跑 claude，关 Terminal，iOS 发消息 |
Claude 仍收到（走 tmux send-keys） |
| 远程 SSH 同步 | 配置远端 → iOS 看到 [remote-...] agent |
远端 agents 出现在列表 |
| Pairing 强制模式 | AGENTPULSE_AUTH_MODE=strict 启动 → 未配对 iOS 尝试连 |
WS/REST 都被 401 拒绝 |
| Live Activity | Claude 进入 waitingForApproval |
锁屏 / 灵动岛有实时状态 |
cd relay-server
npm run simulate # 交互式模拟一个 agent.github/workflows/ci.yml 在 push / PR 时跑：
- relay typecheck (
tsc --noEmit) - 全部单元测试 (
vitest run) - bridge 脚本语法 (
node --check) - SwiftLint（soft failure）
AgentPulse/
├── relay-server/ # Node.js relay（主 server）
│ ├── src/
│ │ ├── adapters/ # 每个 agent 一个 adapter（Claude/Codex/Cursor/...）
│ │ ├── auth/ # 配对 token + 中间件
│ │ ├── hooks/ # Claude Code hook 事件处理
│ │ ├── protocol/ # Zod schema（客户端/服务端消息定义）
│ │ ├── remote/ # SSH 隧道 + 远端 agent 同步
│ │ ├── server/ # Express / WS / mDNS / tunnel
│ │ └── utils/ # JSONL 解析、osascript、tmux、cmux...
│ └── tools/ # 开发用 simulator
├── AgentPulse/ # iOS SwiftUI app
│ ├── Services/ # ConnectionManager / SSE / WS / LiveActivity
│ └── Views/ # AgentList / AgentDetail / Settings / Budget
├── AgentPulseShared/ # iOS / Widget 共享 model（AgentStatus 等）
├── AgentPulseWidgets/ # Home Screen / Lock Screen Widget + Live Activity
├── AgentPulseSDK/ # 可被第三方 app 引用的 Swift 包
├── agentpulse-bridge/ # VS Code 扩展（给 Claude Code 投递输入）
└── docs/
├── optimization-plan.md # 6 阶段优化路线图
├── communication-architecture.md # 详细通信协议说明
├── INTEGRATION.md # 第三方 agent 接入指南
└── PROTOCOL.md # 线上协议参考
详见 docs/optimization-plan.md。简要：
- 阶段 0 基础（已完成）：LICENSE、配对认证、CI、初始 45 tests
- 阶段 1 稳定性（已完成）：远程 agent 同步、iOS 空态兜底、tmux detached 支持、Cursor 回复观测
- 阶段 2 测试基建：200+ tests、结构化日志、开发 simulator 完善
- 阶段 3 安全深化：应用层 E2EE（AES-256-GCM + Curve25519）、audit log
- 阶段 4 平台扩张：PWA（React + Vite），TestFlight，Web push
- 阶段 5 差异化加深：更多桌面 app（Windsurf / Zed）、用户插件、统一 session envelope
- 阶段 6 可选：wrapper 模式、跨 session 搜索、语音输入
MIT — see LICENSE。
对比分析过程中借鉴了：
- Happy 的 E2EE 协议 + 统一 session envelope 设计
- HAPI 的 tunwg WireGuard 隧道 + Web xterm.js 方向
- Claude Code 官方 Hook 系统
欢迎 issue + PR。遵循：
- 每个 PR 至少带 1 个自动化测试覆盖改动
npm test+npx tsc --noEmit必须过- 涉及协议/安全/输入链路的改动必须更新
docs/communication-architecture.md