Claude Code 推送通知:任务完成即时知晓

Claude Code 很乐意自己干上二十分钟。麻烦在于这二十分钟的另一面:你要么盯着终端等,要么走开,回来才发现它从第三分钟起就一直卡在权限确认上。
Hook 能解决这两个问题。Claude Code 会在生命周期的固定节点运行 shell 命令,其中三个节点正是你想在手机上知道的:
- Stop:Claude 结束了本轮回复。任务完成,或者它有问题要问你。
- Notification:Claude 需要你介入。出现权限确认,或者它空闲等待输入。
- StopFailure:本轮因 API 错误结束,例如速率限制或账单问题。
本指南用一个脚本把这三个事件都接入 Pocket Alert。设置大约需要五分钟。
准备工作
- Claude Code,任意较新版本。
jq和curl。大多数 Linux 发行版自带;macOS 上执行brew install jq安装。- 一个 Pocket Alert 账户,以及来自 API Keys 的 API 密钥。免费套餐即可。
- 在你的 iPhone 或 Android 手机上安装 Pocket Alert 应用并登录。
第 1 步:Hook 脚本
Claude Code 会通过 stdin 把一个 JSON 对象传给每个 hook。你需要的字段有:hook_event_name、cwd,Stop 事件中的 last_assistant_message,Notification 事件中的 message,以及 StopFailure 事件中的 error。脚本把这些转换成一条推送:
#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")
case "$(jq -r '.hook_event_name' <<<"$payload")" in
Stop)
title="Claude finished · $project"
message=$(jq -r '.last_assistant_message // "Task complete"' <<<"$payload")
level=default ;;
Notification)
title="Claude needs you · $project"
message=$(jq -r '.message' <<<"$payload")
level=high ;;
StopFailure)
title="Claude stopped · $project"
message=$(jq -r '"API error: " + (.error // "unknown")' <<<"$payload")
level=high ;;
*) exit 0 ;;
esac
jq -n --arg t "$title" --arg m "${message:0:300}" --arg l "$level" \
'{title: $t, message: $m, level: $l}' |
curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
-H "Token: $POCKETALERT_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- >/dev/null || true
exit 0
保存为 ~/.claude/hooks/pocketalert.sh 并添加执行权限:
mkdir -p ~/.claude/hooks
chmod +x ~/.claude/hooks/pocketalert.sh
脚本里有两行比看上去更重要:
jq -n负责构建 JSON。 Claude 的最后一条消息里充满引号、反引号和换行符。如果手动把它粘进 JSON 字符串,遇到第一个引号就会出错;jq会正确转义。- 结尾的
exit 0,以及 curl 后面的|| true。 对于 Stop hook 来说,退出码 2 表示“不要停止,继续执行”。通知类 hook 绝不能阻塞 Claude,即使你的网络断开也一样。
或者使用 Pocket Alert CLI
安装 Pocket Alert CLI 2.0 或更高版本后,curl 那段可以缩减为一条命令。CLI 会自行转义文本,并从 POCKETALERT_API_KEY 读取密钥(下方 env 配置块会设置它),或从 pocketalert auth 读取:
pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true
请保留 -t 和 -m,不要改用位置参数:如果回复以破折号开头(比如 Markdown 列表),就会被当作选项解析。
第 2 步:注册 Hook
把 hook 添加到 ~/.claude/settings.json,使其对所有项目生效。如果该文件已有 hooks 键,请把这些条目合并进去:
{
"env": {
"POCKETALERT_API_KEY": "YOUR_API_KEY"
},
"hooks": {
"Stop": [
{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
],
"StopFailure": [
{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
],
"Notification": [
{
"matcher": "permission_prompt|idle_prompt",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }]
}
]
}
}
env 配置块把 API 密钥传给 hook,同时无需把它写进你的 shell 配置文件。如果你已经在别处导出了 POCKETALERT_API_KEY,就不必添加这个配置块。
Notification 上的 matcher 按通知类型过滤。permission_prompt 在权限确认等待约六秒仍无应答时触发,idle_prompt 在 Claude 完成后约一分钟、且你期间没有输入时触发。在终端会话中,两者都只会在你看起来已离开时才触发,因此你盯着屏幕时手机不会震动。Stop 没有 matcher:Claude 每完成一次回复都会触发。
如果只想让 hook 作用于某一个代码仓库,可以把同样的 hooks 配置块放进该仓库的 .claude/settings.json,或放进 .claude/settings.local.json 以避免提交到 git。
第 3 步:测试
Claude Code 通常会自动识别设置文件的修改(如果 /hooks 还没列出它们,请新开一个会话)。给它一个简单的任务:
> List the files in this directory and stop.
Claude 完成后,你的手机会显示 Claude finished · your-project,并附上回复的开头部分。如果什么都没收到,在 Claude Code 中运行 /hooks 查看已注册的 hook。
要单独测试脚本,可以喂给它一个模拟事件:
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
| POCKETALERT_API_KEY=YOUR_API_KEY ~/.claude/hooks/pocketalert.sh
手机上会收到什么
| 事件 | 标题 | 正文 | 级别 |
|---|---|---|---|
| 任务完成 | Claude finished · api | Claude 最后一条回复的前 300 个字符 | default |
| 权限确认 | Claude needs you · api | Claude needs your permission | high |
| 等待输入 | Claude needs you · api | Claude is waiting for your input | high |
| API 错误 | Claude stopped · api | API error: rate_limit | high |
high 级别的推送会在 iPhone 上以时效性通知的形式送达,因此权限确认能穿透专注模式,而常规的“已完成”消息保持安静。每条推送也会保留在应用的历史记录和 网页控制台 中,方便你回看 Claude 通宵做了什么。
按自己的需要定制
只在你离开时发送。 Stop 会在每次回复后触发,包括你正在盯着看的那些简短回复。在脚本开头加一个开关:
[ -f ~/.claude/away ] || exit 0
然后离开座位时执行 touch ~/.claude/away,回来时执行 rm ~/.claude/away。权限确认无论如何都值得收到,因此你可以只把检查放进 Stop) 分支中。
按项目分组。 在 Pocket Alert 中为每个项目创建一个应用,并在 JSON 中添加 application_id。这样应用就能按项目过滤,你还可以为每个项目设置各自的默认级别。
完全不阻塞 Claude。 在 "async": true 旁边添加 "type": "command",hook 就会在后台运行。在无头模式(claude -p)下请不要使用:后台 hook 会在会话结束时被终止,推送可能根本发不出去。
从手机上恢复会话。 在付费套餐中,带有会话 ID 的 copy 操作按钮 可以让你在手机上复制 claude --resume <id>,回到电脑前再粘贴执行。
或者让 Claude 通过 MCP 发送
Hook 是确定性的:无论 Claude 记不记得你,它都会触发。另一种方式是给 Claude 一个通知工具,让它自行决定何时使用。添加 Pocket Alert MCP 服务器:
claude mcp add --transport http pocketalert https://mcp.pocketalert.app/mcp \
--scope user --header "Authorization: Bearer YOUR_API_KEY"
现在你可以说“运行迁移,完成后把行数推送给我”,Claude 就会调用 create_message,并为此专门撰写一条消息。该工具还接受 level 和 actions 参数,list_messages 则允许 Claude 回读它之前发送过的内容。
两者可以结合使用:用 hook 保证“已完成”和“需要你介入”的提醒必达,用 MCP 发送有实际内容的消息。关于在高风险操作前进行审批,请参阅 人在回路通知。
如果没有收到推送
- 检查密钥。 运行上面的测试命令。curl 返回
401说明 API 密钥有误;去掉>/dev/null即可看到响应内容。 - 检查 hook 是否已加载。 运行
/hooks。设置文件的修改通常几秒内生效;如果 hook 没有列出,请重启 Claude Code。 - 检查
jq是否在 Claude Code 使用的 PATH 中。 Hook 在 Claude 的环境中运行,而通过图形界面启动的编辑器可能看不到 Homebrew 的/opt/homebrew/bin。 - 检查每日上限。 免费套餐每天可发送 50 条消息。长时间会话中如果有大量简短回合,很容易用完配额;上面的离开开关可以帮你减少消息数量。
常见问题
这在 VS Code 和 JetBrains 扩展中能用吗?
可以。这些扩展底层运行的是 Claude Code,并读取相同的 ~/.claude/settings.json,因此 hook 在那里同样会触发。
Claude 能看到 API 密钥吗?
在对话中看不到:hook 在对话之外运行,Stop 和 Notification 的输出也不会展示给模型。但 env 配置块作用于整个会话,因此 Claude 运行的 Bash 命令有可能读取该变量。如果这一点很重要,可以把密钥保存在只有你能读取的文件中,例如权限为 ~/.config/pocketalert/key 的 600,并在脚本中改用 -H "Token: $(cat ~/.config/pocketalert/key)"。
这和终端响铃有什么区别?
响铃和桌面通知都需要你在电脑前。推送则能送达你身处任何位置的手机,保留历史记录,并且可以设置为突破专注模式,用于提醒那些阻塞 Claude 的确认请求。
能获取完整回复,而不只是 300 个字符吗?
一条推送最多可携带约 3,000 个字符的文本。你可以提高 0:300 的上限,但推送的用途是帮你判断是否需要回到电脑前,而不是阅读完整答案。
这是免费的吗?
是的。Hook 是 Claude Code 的功能,而 Pocket Alert 的免费套餐在一台设备上每天覆盖 50 条消息。付费套餐提供更多消息、设备和操作按钮。
获取 API 密钥,放入脚本,让 Claude 在轮到你时告诉你。