返回博客

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

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 · apiClaude 最后一条回复的前 300 个字符default
权限确认Claude needs you · apiClaude needs your permissionhigh
等待输入Claude needs you · apiClaude is waiting for your inputhigh
API 错误Claude stopped · apiAPI error: rate_limithigh

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 在轮到你时告诉你。

分享这篇文章