⌚ agent-watch-approve

AI 在干活,你在摸鱼;危险操作抬腕一点,任务跑完手表喊你。

让 Claude Code 和 Codex 的危险操作推送到你的 Apple Watch / iPhone 上审批, 任务完成自动通知 —— 全程不用回终端。 安卓 / Wear OS / 鸿蒙(兼容模式)同样支持:一个开关切到 ntfy 载体,连 Pushcut 都不用装(见「不止苹果」一节)。

English

📺 看它干活

▶️ 完整介绍视频(30 秒) —— 点开即播(备用:仓库内文件)

功能速览

📸 真机实拍

🚀 最短成功路径(5 步)

1. 装 Pushcut(iPhone + Apple Watch 都装),app 里建一条 Notification(名字随意),Account → API 拿 key;
2. 想一个长随机 ntfy topic 名(无需注册,名字就是密码,例如 myagent_8f3k2j9x);
3. 放脚本:watch_approve.py / watch_done.py / watch.env(由 watch.env.example 复制)放进一个固定目录,填好 key / topic;
4. 自检:python watch_approve.py --doctor —— 逐项检查配置、Pushcut(key/设备名/通知名)、ntfy 收发,最后真发一条测试通知到你手机/手表;
5. 接线:python watch_approve.py --print-claude-config / --print-codex-config 打印已转义好绝对路径的配置片段,粘进 ~/.claude/settings.json / ~/.codex/hooks.json,重启 agent,跑条危险命令测试。

每步细节见下文「十分钟上手」;哪里不顺,先跑 --doctor,再看「排错」。 (安卓 / Wear OS 用户:第 1 步换成装 ntfy app,免 Pushcut,走「📱 不止苹果」一节。)

它解决什么问题

跑长任务时,agent 时不时停下来问一句「可以执行吗?」——你必须守着终端。这个项目把这件事搬到手腕上:

1. ⌚ 远程审批 —— 危险操作(rm -rf、git push --force、提权、出沙箱……)推送到手表,带 ✅ 允许 / ❌ 拒绝 / 🖥️ 终端查看 按钮,点一下,结果秒回 agent(「终端查看」= 退回终端慢慢看再决定);
2. 🤔 选择题上手表 —— Claude 在终端抛出的多选决策框(方案 A 还是方案 B?)也推到手表,按钮 方案A / 方案B / 🖥️ 在终端查看,点哪个 Claude 就按哪个继续;
3. 🔔 完成提醒 —— agent 每跑完一轮任务,手表震一下「任务已完成」,你随时回来验收;
4. 🚦 限额提醒 —— 订阅额度用完(Claude)或快烧完(Codex,默认 ≥90% 预警)时第一时间通知你,附重置时间;任务被 API 错误中断也会提醒;
5. 🤖 其余全自动 —— 不危险的操作静默放行(可配),终端再也不弹「yes/no」。
6. 🪟 多窗口并行 —— 同时开几个项目/窗口也不串台:每次审批走独立回执通道,点谁批谁;通知带「📁 项目名」,一眼分清是谁在问。

两个 Python 脚本,只用标准库、零依赖,并且全程 fail-safe:配置缺失 / 网络挂了 / 超时,一律退回 agent 自己的终端审批,绝不卡死你的任务。

sequenceDiagram
    participant A as Claude Code / Codex
    participant H as watch_approve.py
    participant P as Pushcut 云
    participant W as ⌚ Apple Watch
    participant N as ntfy.sh
    A->>H: 危险操作,触发 hook
    H->>P: 触发通知(注入 ✅/❌ 按钮)
    P->>W: 限时通知,直达手表
    W->>N: 点按钮 → 后台请求发布 allow/deny
    N-->>H: hook 从 stream 读到结果
    H-->>A: 放行 / 拒绝

前置条件

• Claude Code 和/或 Codex CLI
• Python 3(在 PATH 上;只用标准库,无需 pip install)
• Pushcut 账号(hook 动态注入按钮需要 Pro),iPhone 和 Apple Watch 都装上 app
• 一个 ntfy topic(公共 ntfy.sh 即可,topic 名就是密码,取长随机串)
• (国内)一个本地 HTTP 代理,如 Clash 的 http://127.0.0.1:7890

十分钟上手

第 0 步:准备 Pushcut 和 ntfy

1. Pushcut 里建一条 Notification(名字随意,填进配置的 PUSHCUT_NOTIF),标题/正文/按钮都不用配——hook 会动态覆盖;
2. Account → API 拿 API key;
3. 想一个长随机 ntfy topic 名,例如 myagent_8f3k2j9x(无需注册)。

第 1 步:放脚本

把 watch_approve.py、watch_done.py、watch.env 放进一个固定目录,例如 C:\Users\你\watch-hooks\(macOS/Linux 如 ~/watch-hooks/):

git clone https://github.com/ghy196830-del/agent-watch-approve.git
cp agent-watch-approve/watch_approve.py agent-watch-approve/watch_done.py ~/watch-hooks/
cp agent-watch-approve/watch.env.example ~/watch-hooks/watch.env   # 然后填入你的 key/topic

为什么要 watch.env? hook 子进程的环境变量取决于「谁启动了 agent」,Codex 还不会把 自己配置里的 env 传给 hook。脚本启动时会读同目录的 watch.env 兜底(只填补缺失项, 真实环境变量优先),这样从 VS Code、终端、任何地方启动 agent 都能工作。

第 2 步:接 Claude Code

懒人方式:python watch_approve.py --print-claude-config 会打印一段已填好当前脚本绝对路径、 转义好 Windows 反斜杠的配置,直接合并进 ~/.claude/settings.json(全局)或项目的 .claude/settings.json 即可。也可以手动改 examples/claude/settings.example.json。重启 Claude Code 生效。

关键就两块:PreToolUse(审批)+ Stop(完成提醒),matcher 用 "*" 配合 danger-only(见下文「自动驾驶」)。

第 3 步:接 Codex

懒人方式:python watch_approve.py --print-codex-config 打印现成片段,存为 ~/.codex/hooks.json。 也可以手动改 examples/codex/hooks.example.json。

Codex 的三个专属注意点(都踩过坑了):

1. 审批挂的是 PermissionRequest 事件,不是 PreToolUse。 Codex 只在自己要弹审批时(提权 / 出沙箱 / 联网等)触发它,hook 回 allow/deny;不回应就走正常终端审批——语义和手表审批严丝合缝。 (新版 Codex 的 PreToolUse 也支持 allow/deny,可用于日志/策略检查,但它不对应「Codex 要问你了」这个时机,实测旧版还拦不到新 shell 通道,不建议作为本项目的审批主链路。)
2. hook 必须先「信任」才会跑,而且改一次就要重新信任 —— 否则被静默跳过,无任何报错。在 Codex TUI 里运行 /hooks → 找到这两条 hook → review & trust。
3. codex exec(非交互模式)永远不会触发 PermissionRequest(它的 approval policy 是 never)。测试审批请用交互式会话;Stop 完成提醒在 exec 下正常触发。

第 4 步:先自检,再单测一发

# 一键体检:配置占位符、Pushcut key/设备名/通知名、ntfy 收发回环,最后发条测试通知
python ~/watch-hooks/watch_approve.py --doctor

macOS / Linux(bash/zsh):

# Claude 风格(PreToolUse):
echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"rm -rf /tmp/x"}}' \
  | python ~/watch-hooks/watch_approve.py

# Codex 风格(PermissionRequest):
echo '{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{"command":"git push --force"}}' \
  | python ~/watch-hooks/watch_approve.py --agent codex

# 完成提醒:
python ~/watch-hooks/watch_done.py < /dev/null

Windows(PowerShell)原生写法 —— JSON 用 here-string 最稳,引号不用转义(管道里别放中文, 编码会被 PowerShell 5.1 弄花,见「排错」):

@'
{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"rm -rf /tmp/x"}}
'@ | python C:\Users\你\watch-hooks\watch_approve.py

@'
{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{"command":"git push --force"}}
'@ | python C:\Users\你\watch-hooks\watch_approve.py --agent codex

'' | python C:\Users\你\watch-hooks\watch_done.py   # 完成提醒

手表上点 ✅ 允许,第一条会立刻输出 permissionDecision: "allow",第二条输出 decision: {"behavior": "allow"}(Codex 格式,脚本按事件自动切换)。

⚠️ 开了 danger-only(默认推荐配置)后,要用危险命令测试——echo hello 按设计不弹通知。

自动驾驶模式(可选进阶)

watch.env.example 默认是安全档:危险操作上手表,其余退回 agent 自己的正常审批 (WATCH_DANGER_ONLY=1 + 非危险 ask)。想升级成「危险才打扰,其余全自动」, 把 example 里这行的注释去掉即可:

WATCH_DANGER_ONLY=1            # 只有命中危险清单的操作才上手表
WATCH_NONDANGER_DECISION=allow # 其余静默放行(不弹手表、不弹终端)← 取消注释进入自动驾驶

配合 Claude Code 的 "matcher": "*":所有工具调用都过 hook,非危险的(读文件、搜索、MCP……) 静默放行,只有真正危险的才震你手腕。为什么不用白名单 matcher?——白名单永远会漏掉下一个新工具 (WebSearch、新 MCP……),漏掉的会退回终端弹窗,你的手表永远收不到。

内置危险清单覆盖:rm -rf、sudo、git push --force、git reset --hard、dd、mkfs、 chmod 777、shutdown、kill、DROP/TRUNCATE TABLE、DELETE FROM、curl | sh、 docker rm/prune、terraform destroy、kubectl delete、PowerShell Remove-Item -Recurse -Force 等。 WATCH_DANGER_EXTRA 可追加,WATCH_DANGER_REGEX 可整体替换。

⚠️ 代价要心里有数:allow 模式下,危险清单没逮到的操作会无确认直接执行。 危险正则是唯一关卡,按自己的口味扩充它。

手表上看到的不是命令原文,而是一句人话 + 目标文件名,例如:

🗑️ 删除文件夹:node_modules ⚠️ git 强制推送:main 📝 修改文件:app.py、readme.md

防 agent「自改 hook」:脚本自身所在目录默认已受保护(WATCH_PROTECT_SELF=1, 规范化绝对路径比较):任何对 watch_approve.py / watch.env 的写操作强制上手表 (🛡️ 改 hook 脚本),agent 想偷偷解除你的管控?先过你手腕这关。WATCH_PROTECT_PATHS 可再追加别的目录(子串匹配)。已知边界:shell 重定向(echo x > 脚本)绕得过此规则, 但默认危险清单里的写盘类命令仍会兜住一部分。

限额提醒(订阅党刚需)

Claude Code 和 Codex 的订阅都有用量窗口,烧完直接给你停活——人在摸鱼,任务在后台默默死掉是最惨的。 这件事也搬上手表了,两边机制不同(都实测过):

• Claude:挂在官方 StopFailure hook 上(回合因 API 错误终止时代替 Stop 触发)。 限额错误(error=rate_limit)→「🚦 Claude 额度已用完」+ 重置时间(从错误文案里抽出 resets 1:10am (Asia/Shanghai) 这类信息);其它 API 错误 →「⚠️ 任务异常终止」+ 错误类型。
• Codex:限额报错的回合不跑任何 hook(读源码确认:错误路径直接 break),没法在死亡瞬间通知, 所以改为预警:每次任务完成时顺带读 Codex 自己的额度遥测(rollout 里的 rate_limits,含 used_percent 和重置时间),用量 ≥ WATCH_LIMIT_WARN_PCT(默认 90%)时,完成通知自动变成 「⚠️ Codex 额度已用 NN%」+ 重置时间——在烧干之前就提醒你省着点用。
• 这类通知用单独的警示音(WATCH_LIMIT_SOUND,默认 problem),和普通完成提醒一耳朵区分。

接线:Claude 在 settings.json 的 hooks 里加一段 StopFailure(示例已含);Codex 无需额外接线(复用已有的 Stop)。

多窗口并行

同时开几个 Claude Code / Codex 窗口?两件事已经内置:

• 互不串台 —— ntfy 是发布/订阅:若所有窗口共用一个 topic,你在 A 窗口的通知上点 ✅,正在等批的 B 窗口会收到同一条回执、被一起放行。所以每次审批都用独立回执 topic(基础 topic + 随机后缀),按钮只对自己那次请求生效;过期通知上的迟到点击也不会误批后来的请求。(实测:两窗口同时等批,两次点击各放各的,互不影响。)
• 分得清来源 —— 审批和完成通知的正文末尾都带「📁 项目文件夹名」,一眼看出是哪个窗口在说话。

不想要?WATCH_UNIQUE_TOPIC=0 回到共享 topic,WATCH_SHOW_CWD=0 去掉 📁 行。 注意:app 里手配静态按钮(`PUSHCUT_DYNAMIC_ACT