Claude Code can work on its own for minutes at a time, then stop: it needs your permission to run a command, or it has finished and waits for your next prompt. If you’ve stepped away from the terminal, it waits as long as you do.

Claude Code has hooks for both moments. A Notification hook runs when it needs your permission, and a Stop hook runs when it finishes a response. This guide connects both to Honk, so your iPhone and Apple Watch tell you, and a session that pings ten times sends one notification instead of ten.

Before you start

A Honk account (invite-only for now: request access) and a project for your coding agents, such as “Claude Code”, with an ingestion key. Give this project its own key: anyone who has it can post to the project, and to nothing else.
The honk CLI on the computer where Claude Code runs: go install github.com/honk-hq/go/cmd/honk@latest, or a binary from the releases page.
jq, which reads the JSON that Claude Code passes to hooks. Recent versions of macOS include it; on Linux, install it with your package manager.

1. Keep the key in a file

Hooks run as shell commands in Claude Code’s environment. To keep the key out of settings files you might commit, put it in ~/.config/honk/env:

HONK_URL=https://honk-honk.app
HONK_KEY=honk_…

Then run chmod 600 ~/.config/honk/env, so only you can read it.

2. Add the hook script

Save this as ~/.claude/hooks/honk.sh and make it executable with chmod +x:

#!/usr/bin/env bash
# A push when Claude Code needs your permission (Notification) or finishes (Stop).
# Claude Code sends the event as JSON on stdin. Every ping from one project
# shares a group key, so Honk folds repeats into one notification.
set -a; . "$HOME/.config/honk/env"; set +a
input=$(cat)
dir=${CLAUDE_PROJECT_DIR:-$(jq -r '.cwd // empty' <<<"$input")}
project=$(basename "${dir:-$PWD}")

case $(jq -r '.hook_event_name' <<<"$input") in
  Notification)
    level=loud
    title="Claude Code needs you in $project"
    text=$(jq -r '.message // empty' <<<"$input") ;;
  Stop)
    level=light
    title="Claude Code finished in $project"
    text=$(jq -r '.last_assistant_message // empty | .[:280]' <<<"$input") ;;
  *) exit 0 ;;
esac

honk send --severity "$level" --title "$title" --message "${text:-$title}" \
  --group-key "claude-code/$project" --source "$(hostname -s)" --quiet || true

It reads the event that Claude Code sends on stdin and turns it into one Honk event:

Needs permission: a Loud honk titled “Claude Code needs you in my-app,” with Claude Code’s own message, such as “Claude needs your permission.”
Finished: a Light honk titled “Claude Code finished in my-app,” with the first 280 characters of the last reply.

|| true makes sure a network problem never turns into a hook error.

3. Register the hooks

Add both hooks to ~/.claude/settings.json, which applies to every project on this computer. If the file already has a hooks key, add Notification and Stop next to the events that are already there:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude/hooks/honk.sh",
            "async": true
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude/hooks/honk.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

"matcher": "permission_prompt" limits the Notification hook to permission requests. The Stop hook takes no matcher: it runs at the end of every response.
"async": true runs the hook in the background, so Claude Code never waits for the push.

The same block works in a repository’s .claude/settings.json, which you can commit to share it with your team (each person then needs the script, the CLI and their own key), or in .claude/settings.local.json for one project on your computer only.

Type /hooks in Claude Code to check that both hooks are listed. To test the script without waiting for Claude, run:

echo '{"hook_event_name":"Notification","message":"Test from the terminal"}' | ~/.claude/hooks/honk.sh

One notification per project, not one per ping

Every event from a project uses the group key claude-code/<project>, so Honk keeps them in one group. That decides how often your phone buzzes:

The first ping pushes right away.
Pings after it don’t each push. You get at most one update every 5 minutes, with the running count, and on your iPhone each update replaces the previous banner instead of adding one.
A level louder than anything the group has pushed so far gets through right away, even within those 5 minutes: a permission request (Loud honk) after a finished response (Light honk), for example.

Both numbers are in the project’s Settings. While a problem repeats, notify at most once every … changes the 5 minutes. After a day without pings, the next one counts as new and pushes right away; Group messages that arrive less than … apart shortens that day, so each new work session starts with a push.

Quieter: only when you’ve walked away

The Stop hook runs after every response, even while you’re watching the terminal. To get a push only when you’ve stepped away, delete the Stop block and change the matcher to "permission_prompt|idle_prompt". Claude Code sends idle_prompt when it finished about 60 seconds ago and you haven’t typed since, so a push means it’s really waiting for you.

What the push shows

The notification shows the title and the message, and the message can be the start of Claude’s reply, code included. For private work, open the project’s Settings and set What notifications show to Generic (no content): the push then shows only the project name, and the text stays in the inbox. Or leave the reply out of the script altogether.

Codex

OpenAI’s Codex CLI has a simpler hook: notify runs a program after each finished turn and passes the event as one JSON argument. This script sends the same Light honk, in a group of its own:

#!/usr/bin/env bash
# Codex runs this after each finished turn, with the event as one JSON argument.
set -a; . "$HOME/.config/honk/env"; set +a
project=$(basename "$(jq -r '.cwd // "codex"' <<<"$1")")
text=$(jq -r '."last-assistant-message" // empty | .[:280]' <<<"$1")

honk light "Codex finished in $project" "${text:-Done.}" \
  --group-key "codex/$project" --source "$(hostname -s)" --quiet || true

Save it as ~/.codex/honk.sh, make it executable, and add one line to ~/.codex/config.toml, with your own home folder in the path:

# a top-level key: put it above the first [section]
notify = ["/Users/you/.codex/honk.sh"]

Codex currently sends only finished turns (agent-turn-complete) to notify, so this covers the end of a task, not approval requests.

Honk is invite-only for now: request access. Everything in this guide works on the Free plan.