Ambient › Guides

How to get Claude Code notifications on your phone

Updated · 4 min read

Nothing built into Claude Code reaches a phone: its notifications go to the terminal it runs in. A Stop or Notification hook can send a push instead, with one curl to ntfy (free, with iOS and Android apps) or Pushover. Ambient is a Mac app and has no phone app; if the agent you want to follow runs on another machine, ambient remote add brings its sessions to your Mac over ssh.

Get Ambient Free for macOS 14 and later.

A hook that posts to ntfy

Install the ntfy app on your phone and subscribe to a topic. The topic name is the only secret, so make it long and unguessable, something like claude-7f3a9c2e1b. Then add this to ~/.claude/settings.json, with your topic in place of your-topic:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "curl -s -H 'Title: Claude Code' -d \"Done in $(jq -r .cwd | xargs basename)\" ntfy.sh/your-topic >/dev/null", "async": true }] }
    ],
    "Notification": [
      { "matcher": "permission_prompt|idle_prompt", "hooks": [{ "type": "command", "command": "curl -s -H 'Title: Claude Code needs you' -d \"$(jq -r .message)\" ntfy.sh/your-topic >/dev/null", "async": true }] }
    ]
  }
}

Stop runs when Claude finishes responding, and the hook reads the project folder from the JSON on stdin so the push says which one. Notification with the permission_prompt and idle_prompt matchers runs when Claude is about to ask you to approve a tool, or has been waiting for input for a minute; its message field is the text Claude Code would have shown. "async": true keeps the request from holding Claude up. jq ships with macOS 15 and later and is a package install elsewhere. Restart open sessions, or type /hooks to check the hooks are registered, and test with curl -d test ntfy.sh/your-topic.

If you'd like the push to carry Claude's last words, Stop also receives last_assistant_message; $(jq -r .last_assistant_message | head -c 200) adds the first couple of sentences. Remember that text then passes through ntfy's server, so leave it out if replies may quote anything private, or run your own ntfy server.

Or Pushover

Pushover needs an application token, from registering an app on its site, and your user key, from the dashboard. Keep both out of settings files that might get committed: put the command in a small script, ~/.claude/hooks/push.sh, and point the hook at it.

#!/bin/sh
# ~/.claude/hooks/push.sh, run with: chmod +x ~/.claude/hooks/push.sh
msg=$(jq -r '.message // "Claude Code is done"')
curl -s https://api.pushover.net/1/messages.json \
  -F token=APP_TOKEN -F user=USER_KEY \
  -F title="Claude Code" -F "message=$msg" >/dev/null
{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/push.sh", "async": true }] }
    ],
    "Notification": [
      { "matcher": "permission_prompt|idle_prompt", "hooks": [{ "type": "command", "command": "~/.claude/hooks/push.sh", "async": true }] }
    ]
  }
}

The same script serves both events: Notification has a message, Stop doesn't, and the // in the jq filter fills in the default.

Which event to use

Stop is every finished turn, including a one-line answer to a quick question, which gets noisy on a phone. Notification with the two matchers is only the moments Claude is waiting on you, which is usually what you want while you're away. Keep both if you want to know the long tasks are done; keep Notification alone if you want quiet until something needs you. The permission notifications guide covers the timing of the permission alert and a PermissionRequest hook that fires immediately.

Where Ambient fits, and where it doesn't

Ambient runs on a Mac and shows agents there: a notch island, banners and chimes, a menu bar list, a Dock glow. It has no phone app, no server and no account, so it can't push anything to a phone, and this page's honest answer to “Claude Code notifications on phone” is the hook above.

What it can do is follow Claude Code running somewhere else. If your agents run on a devbox, a cloud VM or a Mac mini in a closet and you're at your Mac, pair the machine once:

~/.ambient/bin/ambient remote add devbox      # ssh devbox, using your own ~/.ssh/config
~/.ambient/bin/ambient doctor --remote devbox

That copies a small POSIX shell script to the machine, adds background hooks for Claude Code and Codex there, and from then on your Mac dials out over your own ssh and streams the machine's events back. Its sessions appear beside the local ones, labeled with the machine's name, in the island, menu bar, notifications and board. No server, no root, no daemon, no open port on your Mac, and the remote machine can only send display data: it can't reach anything on your Mac or run anything there. A --redaction level decides how much leaves the machine, from metadata only to the last 160 characters of an agent's message. If your Mac sleeps, events wait in a spool on the machine and arrive on reconnect.

Stop babysitting terminals.

Free for macOS 14 and later. Works with Claude Code, Codex and Gemini CLI.

Get Ambient

Or brew install --cask viveky259259/tap/ambient · Star on GitHub

Common questions

Can Ambient send Claude Code notifications to my phone?

No. Ambient is a macOS app with no phone app and no server, so its island, banners and chimes stay on your Mac. What it can do is follow Claude Code and Codex running on another machine over your own ssh, so a devbox's sessions show up on your Mac next to the local ones. For a phone, use the ntfy or Pushover hook.

Is ntfy free, and is a topic private?

ntfy.sh is free for ordinary use and the apps are open source. A topic is only as private as its name: anyone who guesses it can read and post, so pick a long random one, or reserve it with a paid ntfy.sh plan, or run your own ntfy server. Pushover is a one-time purchase per platform and ties messages to your user key.

Why do I get a push for every little turn?

Stop fires every time Claude finishes responding, including a one-line answer. If that's too much, drop the Stop hook and keep only the Notification one with the permission_prompt and idle_prompt matchers, which fire when Claude is waiting on you.

Does the hook work when Claude Code runs on a Linux server or in the desktop app?

Yes. Hooks run wherever Claude Code runs, so the same curl line works from a Linux devbox, a container or the Claude desktop app; it only needs jq and curl on that machine. Put it in ~/.claude/settings.json there, or in the project's .claude/settings.json to share it with a team.

Sources

More guides: Claude Code notifications on Mac · Claude Code permission notifications · Notifications not working