Get Claude Code Notifications on Your Phone

To get Claude Code notifications on your phone, you have two options. If you're on a Pro, Max, Team or Enterprise plan, turn on Remote Control and enable Push when actions required in /config; the Claude mobile app then gets a push when Claude needs a permission or an answer, and you can reply from the phone. On any plan, including API keys, add a Notification hook that sends a push through a service such as ntfy, Pushover or a Telegram bot with curl.

The Remote Control details come from the official Remote Control docs and settings reference, the hook details from the hooks guide, and each push service's commands from its own documentation, all checked on October 3, 2026. The hook commands pass a shell syntax check and were checked against those docs; they weren't run against live accounts. For desktop alerts, see the main guide to Claude Code notifications when done.

Your options compared#

Choose Remote Control if your plan supports it and you want to act on the alert, not just see it. Choose ntfy if you use an API key or a cloud provider, or want something you can self-host. Choose Pushover if you already use it for other alerts. Choose a Telegram bot if Telegram is the app you check most.

Whichever you pick, the timing works in your favor. The permission_prompt and idle_prompt notifications are designed to fire only when you seem to be away, so your phone stays quiet while you're at the keyboard.

Option 1: built-in push with Remote Control#

Remote Control connects a Claude Code session running on your machine to the Claude app on iOS or Android, or to claude.ai/code in a browser. Claude keeps running locally; the phone is a second screen and keyboard for the same session. With it active, Claude Code can send push notifications to the phone.

Set it up once:

1. Install the Claude app and sign in with the same account and organization you use for Claude Code. If you don't have the app, run /mobile in Claude Code for a QR code that opens the right app store.
2. Allow notifications when the phone asks.
3. In Claude Code, run /config and turn on Push when actions required (permission prompts and questions), Push when Claude decides (Claude chooses, typically when a long task finishes), or both.
4. Start Remote Control with claude --remote-control, claude remote-control (server mode), or /remote-control inside a running session.

To make this the default for every interactive session, the same choices can live in your user settings. remoteControlAtStartup connects each new session automatically, and the two push settings appear in the settings reference as inputNeededNotifEnabled ("when Claude is waiting on you") and agentPushNotifEnabled ("when it decides to"):

{
  "remoteControlAtStartup": true,
  "inputNeededNotifEnabled": true,
  "agentPushNotifEnabled": true
}

Things to know before you rely on it, all from the Remote Control docs:

• It needs a claude.ai subscription. API keys aren't supported, and neither are Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry or an ANTHROPIC_BASE_URL pointing at a proxy. On Team and Enterprise, an Owner has to enable Remote Control first.
• There's no per-event configuration beyond the two toggles. Claude decides when "Push when Claude decides" fires, and you can also ask for one in your prompt: "notify me when the tests finish".
• It skips pushes while you're typing in or focused on the terminal. To also skip them whenever you're at the machine, set CLAUDE_CLIENT_PRESENCE_FILE to a marker file that a screen-lock tool creates on unlock and deletes on lock.
• The local process must keep running. Close the terminal and the session goes offline. On a remote server, start Claude Code inside tmux or screen so it survives an SSH disconnect.
• If pushes don't arrive, check whether /config shows "No mobile registered" (open the app to refresh it), iOS Focus modes and notification summaries, and Android battery optimization for the Claude app.

Option 2: push through ntfy with a hook#

ntfy is an open-source push service: you publish a message to a topic with a plain HTTP request, and the ntfy app on your phone shows it. The public server at ntfy.sh needs no sign-up, which is also why the topic name matters: ntfy's docs say the topic "is essentially a password, so pick something that's not easily guessable."

1. Install ntfy on your phone from Google Play, F-Droid or the App Store, as listed in its phone app docs, and subscribe to a long random topic name.
2. Send a test from your computer: curl -d "test from Claude Code" ntfy.sh/your-topic-name. The publishing docs show the same command.
3. Save the script below and point a hook at it.

#!/bin/bash
# Push to ntfy when Claude Code needs you. Reads the hook's JSON on stdin.
topic="${NTFY_TOPIC:?set NTFY_TOPIC to your private topic name}"
input=$(cat)
type=$(jq -r '.notification_type // "done"' <<<"$input")
project=$(basename "$PWD")

case "$type" in
  permission_prompt) title="Claude needs permission in $project"; priority="high" ;;
  idle_prompt) title="Claude is waiting in $project"; priority="default" ;;
  *) title="Claude Code: $project"; priority="default" ;;
esac

curl -s -m 10 \
  -H "Title: $title" \
  -H "Priority: $priority" \
  -d "$(jq -r '.message // "Finished"' <<<"$input")" \
  "https://ntfy.sh/$topic" >/dev/null

Make it executable with chmod +x ~/.claude/hooks/push.sh, install jq if jq --version fails, and add export NTFY_TOPIC=your-topic-name to your shell profile. Hook commands inherit Claude Code's environment, as the hooks reference notes, so the variable is there as long as you start claude from a shell that has it. Then register the hook:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          { "type": "command", "command": "\"$HOME/.claude/hooks/push.sh\"", "async": true, "timeout": 15 }
        ]
      }
    ]
  }
}

"async": true keeps a slow network from holding up Claude Code, and curl -m 10 gives up after ten seconds. The message field in the hook's input is short text such as "Permission required: Bash tool", per the Notification input reference, so the push tells you what's being asked without sending your code anywhere.

If messages arrive late on Android, turn on instant delivery for the subscription; ntfy's docs warn that without it, messages "may arrive with a significant delay". For private content, ntfy supports access tokens (-H "Authorization: Bearer tk_...") on protected topics, or you can run your own ntfy server and change the URL.

Why not push on every Stop?#

Stop fires after every response, including a two-second answer to a quick question while you're sitting right there. On a phone, that gets annoying fast. idle_prompt is the better "finished" signal for a phone: it fires about 60 seconds after Claude finished, and only if you haven't typed since, so it effectively means "done, and you're not looking". If you do want an immediate push for every finished turn, add a Stop group pointing at the same script; it falls through to the default title.

Option 3: Pushover#

Pushover is a paid push service with apps for iOS, Android and desktop; its pricing page describes a one-time purchase per platform after a 30-day free trial. Create an application in your Pushover dashboard to get an API token, and copy your user key. Its API takes a POST to https://api.pushover.net/1/messages.json with token, user and message, plus an optional title:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -m 10 --form-string \"token=$PUSHOVER_TOKEN\" --form-string \"user=$PUSHOVER_USER\" --form-string \"title=Claude Code\" --form-string \"message=Claude needs you in $(basename \"$PWD\")\" https://api.pushover.net/1/messages.json >/dev/null",
            "async": true
          }
        ]
      }
    ]
  }
}

Export PUSHOVER_TOKEN and PUSHOVER_USER in your shell profile rather than writing them into the settings file, especially if you ever share or commit settings.

Option 4: a Telegram bot#

Telegram's Bot API sends a message with one HTTPS request to https://api.telegram.org/bot<token>/sendMessage, given a chat_id and text.

1. Message @BotFather in Telegram, create a bot, and copy the token it gives you.
2. Send any message to your new bot, then open https://api.telegram.org/bot<token>/getUpdates in a browser. Your chat ID is the chat.id value in the response.
3. Export both in your shell profile as TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID, and add the hook:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -m 10 \"https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage\" -d \"chat_id=$TELEGRAM_CHAT_ID\" --data-urlencode \"text=Claude needs you in $(basename \"$PWD\")\" >/dev/null",
            "async": true
          }
        ]
      }
    ]
  }
}

Don't confuse this with Claude Code's Channels, which also mention Telegram. Channels push events from a chat app into a running session; the hook above sends alerts out to you.

Phone pushes and remote machines#

Phone pushes are especially useful when Claude Code runs on a server you reached over SSH. Desktop commands like osascript and notify-send would fire on the server, where nobody sees them, but curl to a push service works the same from anywhere with internet access. Put the hook in the server's ~/.claude/settings.json, and run the session inside tmux so it keeps going after you disconnect; running Claude Code in the background covers that side.

Test the setup the same way as a desktop alert: press Shift+Tab until manual mode is on, ask for something that needs permission, then leave the keyboard alone (keep the computer awake, since a sleeping machine pauses the session). The push should arrive after about six seconds. If it doesn't, run the curl line by hand first, then work through our fixes for a notification hook that isn't working.

At the desk, a phone is overkill#

A phone buzz is the right signal when you're away from the computer. When you're at it, working in another app, a push to your pocket is more interruption than you need. On a Mac or a Windows PC, Eddie covers that case from the notch: each session shows as working, needs you or done, in the MacBook notch or at the edge of your Windows desktop, and it taps you when one needs permission. It doesn't send anything to your phone, so the two work well side by side. Our waiting-for-input guide explains the desktop events in detail.