Get a phone notification when Claude Code finishes or needs your input

By Bohdan StefaniukUpdated 5 min read

Draft. The script below was run against a local test server with the hook input Claude Code documents, but not yet end to end against Ahem from a live Claude Code session.

Claude Code can run a command on two hook events: Notification (it’s waiting for your permission or input) and Stop (it finished responding). Point both at a small script that sends an event to Ahem, and your phone buzzes when Claude needs you, with the project name and Claude’s last message, even when you’re away from your desk.

What you need

  • Claude Code with hooks (any recent version).
  • jq and curl. Both come with most Macs and Linux systems; otherwise brew install jq or your package manager.
  • An Ahem account (the free plan is enough), a project called Agents, and an API key for it.

Step by step

  1. Create the project and key. In Ahem, create a project named “Agents” (its address is agents) and an API key for it. A new key can send events and create channels. Store it where Claude Code can read it, for example in your shell profile:

    export AHEM_KEY="ak_live_…"
  2. Save this script as ~/.claude/hooks/ahem-notify.sh and make it executable with chmod +x ~/.claude/hooks/ahem-notify.sh:

    #!/bin/sh
    # Sends a Claude Code hook event to Ahem. Never blocks Claude Code: always exits 0.
    url="${AHEM_URL:-https://api.useahem.com/v1/channels/agents/claude-code}"
    input=$(cat)
    event=$(printf '%s' "$input" | jq -r '.hook_event_name')
    project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")
    
    if [ "$event" = "Notification" ]; then
      title="Claude needs you · $project"
      level="warning"; type="agent.waiting"
      body=$(printf '%s' "$input" | jq -r '.message // ""')
    else
      title="Claude finished · $project"
      level="success"; type="agent.task_completed"
      body=$(printf '%s' "$input" | jq -r '(.last_assistant_message // "")[0:2000]')
    fi
    
    printf '%s' "$input" |
      jq --arg t "$title" --arg b "$body" --arg l "$level" --arg ty "$type" --arg p "$project" \
        '{title: $t, body: $b, level: $l, type: $ty, group: .session_id,
          metadata: ({project: $p, notification: .notification_type} | with_entries(select(.value != null)))}' |
      curl -sS -m 5 "$url" \
        -H "Authorization: Bearer $AHEM_KEY" -H "Content-Type: application/json" \
        -d @- >/dev/null 2>&1
    exit 0

    It reads the hook’s JSON from standard input. A Notification becomes a warning with Claude’s message; a Stop becomes a success with the first 2,000 characters of Claude’s last reply. The session id is the event’s group, and the folder name goes into the title and metadata.

  3. Register the hooks in ~/.claude/settings.json, merged with what’s already there:

    {
      "hooks": {
        "Notification": [
          {
            "matcher": "permission_prompt|idle_prompt",
            "hooks": [{ "type": "command", "command": "~/.claude/hooks/ahem-notify.sh", "async": true }]
          }
        ],
        "Stop": [
          {
            "hooks": [{ "type": "command", "command": "~/.claude/hooks/ahem-notify.sh", "async": true }]
          }
        ]
      }
    }

    The Notification matcher keeps it to the two moments you care about: permission_prompt (Claude wants to use a tool and the prompt has waited a few seconds) and idle_prompt (Claude finished a while ago and you haven’t typed since).

  4. Turn on notifications in the Ahem app or your browser, then ask Claude Code for something that needs a permission. When you step away, your phone shows “Claude needs you · my-repo”.

Make it quieter

  • Only buzz when Claude is waiting. Set the #claude-code channel’s rule to Warnings and errors. “Finished” events (success) are still stored, so you can scroll through every run later.
  • One thread per session. The script sends the session id as group, so each Claude Code session is one thread in the inbox.
  • Count your agent’s work. Add a counter: count of agent.task_completed, today.
  • A channel per machine or per repo. Set AHEM_URL to another channel address, for example https://api.useahem.com/v1/channels/agents/laptop. New channel names are created on the first event.

Troubleshooting

  • Nothing arrives. Run the script by hand, then look in the Ahem inbox:
    echo '{"hook_event_name":"Stop","cwd":"/tmp/test","session_id":"t1","last_assistant_message":"hi"}' \
      | ~/.claude/hooks/ahem-notify.sh
    If the event is there, the hook isn’t registered: run /hooks in Claude Code to see what it loaded.
  • AHEM_KEY is empty inside the hook. Claude Code started from an app rather than a terminal may not load your shell profile. Put the key in the script, or in a file the script reads.
  • Too many “finished” notifications. Stop fires every time Claude finishes a response, not only at the end of a long task. Use the channel rule above.
  • A 404 from the API. The project in the address (agents) must exist; projects are not created automatically. Channels are, as long as the key has the channels:create scope, which new keys have.
  • Notifications only when you’re away. That’s Claude Code’s timing, not Ahem’s: in a terminal, permission_prompt waits until you haven’t typed for a few seconds, and idle_prompt about a minute.

Other ways to do it

  • A desktop notification (osascript -e 'display notification …' on macOS, notify-send on Linux). Free, but it only reaches the computer you’re sitting at.
  • A Telegram bot. Works, with MarkdownV2 escaping and one chat for everything. See Ahem vs a Telegram bot.
  • Claude Code’s own notification settings. Good for the terminal; they don’t reach your phone.

FAQ

Questions

Does the hook slow Claude Code down?
No. The hooks run with "async": true, so Claude Code doesn’t wait for them, and the script gives up after 5 seconds and always exits 0, so a network problem never gets in Claude’s way.
Can I include the diff or the files changed?
Yes. Add fields to metadata in the script (up to 8 KB), and keep the body under 10,000 characters.
Does it work for Codex, Cursor or other agents?
Any tool that can run a command can send an event the same way: one HTTP request with a JSON body. A guide for Codex is planned.
Is it free?
Ahem’s free plan includes 3,000 events a month. Every Stop and every notification is one event.

Let your agent tap you on the shoulder.

Create a free project called Agents, paste the script, and your phone buzzes the next time Claude needs you.