---
title: "Claude Code Notification When Done, on Your Phone"
description: "Set up a Claude Code notification when done with a Notification or Stop hook, send it to your phone, and let Claude ask you and wait for your answer."
url: "https://notifexapp.com/blog/claude-code-notification-when-done"
published: "2026-11-18"
updated: "2026-11-18"
author: "Alaa Jawhar"
---

# Claude Code Notification When Done: Hooks and Your Phone

To get a Claude Code notification when done, add a hook to `~/.claude/settings.json`. Claude Code runs your command when it waits for input or finishes a reply, and the command pings you. A hook only tells you something happened. If you also want to answer from your phone, give Claude an MCP tool that asks you and waits.

This guide covers both. First the built-in hooks, set up the way the [Claude Code hooks guide](https://code.claude.com/docs/en/hooks-guide) describes. Then how to send the ping to your phone. Then the step a ping cannot do: getting your answer back into the session.

## How do you get a Claude Code notification when it is done?

Use a hook. Hooks are shell commands that Claude Code runs at fixed points in a session. They run every time, so you do not depend on the model remembering to tell you.

![The Claude Code /hooks screen showing a Notification hook that runs an osascript desktop notification command.](https://d29bihfk9mha1v.cloudfront.net/notifex/blog-claude-code-notification-when-done-notif-1-v2.webp)

_Claude Code /hooks view of the Notification hook from step 3, captured in a terminal on a Mac with a demo project, November 2026._

Two hook events matter for a done notification. The **Notification** event fires when Claude is waiting for your input or your permission. The **Stop** event fires when Claude finishes responding. The [hooks reference](https://code.claude.com/docs/en/hooks) lists every event and its input.

To add a desktop notification on macOS:

1. Open `~/.claude/settings.json`. Create the file if it does not exist.
2. Add a `hooks` block with a `Notification` entry and an empty matcher, as shown below.
3. Set the command to `osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'`.
4. Save the file, then run `/hooks` in Claude Code to check that the hook is listed.
5. Ask Claude for something that needs a permission prompt, switch to another window, and wait for the banner.

`{ "hooks": { "Notification": [ { "matcher": "",` `  "hooks": [ { "type": "command",` `    "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" } ] } ] } }`

On Linux the guide uses `notify-send`. On Windows it uses a PowerShell message box. If nothing appears on macOS, the guide notes that Script Editor needs notification permission in System Settings.

## Should you use the Notification hook or the Stop hook?

Use Notification when you want to hear about waiting. Use Stop when you want to hear about every finished reply. An empty matcher on Notification fires on all notification types. A matcher narrows it to one type.

_Hook choices for a Claude Code done notification (Claude Code hooks docs, checked 2026-11-18)_

| Hook and matcher | Fires when | Good for |
| --- | --- | --- |
| Notification, matcher permission_prompt | Claude needs you to approve a tool use, and the prompt has waited about six seconds | Runs that stall on a permission you did not pre-approve |
| Notification, matcher idle_prompt | Claude finished responding about 60 seconds ago and you have not typed since | A quiet "it is done, come back" ping |
| Notification, empty matcher | Any notification type, including the two above | One hook that covers every wait |
| Stop | Claude finishes responding | Short sessions where every reply matters; it can be noisy on long ones |

Most people start with `idle_prompt`. It waits a minute, so it does not buzz while you are still reading the reply.

## How do you get the notification on your phone?

A desktop banner helps only while you sit near the screen. To reach your phone, point the hook at a push service instead of a local command.

![Two App Store screenshots: the ntfy app listing notifications in a topic, and the Claude app showing a Claude Code task waiting for approval.](https://d29bihfk9mha1v.cloudfront.net/notifex/blog-claude-code-notification-when-done-phone-routes-v2.webp)

_ntfy and Claude app screenshots from their App Store listings, November 2026. Apps and logos belong to their owners._

### A push service such as ntfy

ntfy takes a plain HTTP POST. The [ntfy publishing docs](https://docs.ntfy.sh/publish/) show the shape: `curl -d "Claude Code is waiting" ntfy.sh/your-topic`. Put that line in the hook command and subscribe to the topic in the ntfy app. On the public server a topic name works like a password, so pick one that is hard to guess.

### Remote Control push

If you sign in to Claude Code with a claude.ai plan, [Remote Control](https://code.claude.com/docs/en/remote-control) can push to the Claude app on iOS or Android. Run `/config` and turn on _Push when actions required_ for permission prompts and questions, or _Push when Claude decides_. Anthropic's docs say there is no per-event setting beyond those two toggles.

We compare these routes in more depth in [Claude Code on your phone](https://notifexapp.com/blog/claude-code-on-your-phone). Other agents have their own alerts: [Cursor notifications when the agent is done](https://notifexapp.com/blog/cursor-notifications-when-done) and [how Codex notifications work](https://notifexapp.com/blog/codex-notifications-explained).

## What can a done notification not do?

A hook sends a message out. Nothing comes back. If Claude stopped to ask which branch to deploy, the ping tells you a question exists. You still answer it in the terminal, or in a client that mirrors the session.

![A developer at a café counter looks at a notification on his phone while his laptop waits at home with a paused prompt.](https://d29bihfk9mha1v.cloudfront.net/notifex/blog-claude-code-notification-when-done-notif-2-v2.webp)

_Illustration: the ping tells you a question is waiting, but you answer it at the keyboard._

That matters for the runs you leave alone. A permission prompt waits until you return. A plain question in the chat also waits, because the session has nobody to read it. The notification shortens the wait only if you can get back to the keyboard.

## How can Claude ask you on your phone and wait for the answer?

Give Claude a tool that asks a person. Notifex is a remote MCP server built for that. Claude calls **ask_question**, your phone gets a push, and the call blocks until someone answers. Your answer goes straight back to Claude as the tool result, and the run continues.

1. Install [Notifex on your iPhone](https://notifexapp.com/iphone-app) or [your Android phone](https://notifexapp.com/android-app). It is free on both stores.
2. Create a project in the app or the portal and copy its secret key. It is shown once.
3. Add the server to Claude Code with the command below, using your key.
4. Run `/mcp` in Claude Code and check that notifex is connected.
5. Tell Claude when to ask, in plain words, in the prompt or in `CLAUDE.md`.

![Two iPhone screens: the Notifex welcome screen after install, and the Save your connection screen with the one-time secret key.](https://d29bihfk9mha1v.cloudfront.net/notifex/blog-claude-code-notification-when-done-setup-steps-1-2-v1.webp)

_Steps 1 and 2 in the Notifex app on an iPhone 17 Pro simulator, demo fixture data, captured October 2026, key redacted. Steps 3 to 5 happen in Claude Code._

`claude mcp add --transport http notifex https://mcp.notifexapp.com/mcp \` `  --header "Authorization: Bearer <YOUR_API_KEY>"`

This is the standard remote server pattern from the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp). The [Notifex setup page for Claude Code](https://notifexapp.com/claude-code) has the same entry as JSON for `.mcp.json`.

A prompt line that works: "Before you deploy, ask me with Notifex which build to ship. Wait for my answer." Claude can offer options (single-select or multi-select) or ask for free text. It can also send up to 10 questions in one push and attach a screenshot or a log file.

> **Keep the key private**
>
> The secret key identifies your project. Treat it like a password and keep it out of the repository.

## Can you use hooks and Notifex together?

Yes, and they do different jobs. A hook is deterministic: it fires on every matching event, whether or not Claude thinks to tell you. An MCP question is a decision point: Claude chooses to ask, and it waits for you.

- **Keep the hook for "done".** An `idle_prompt` hook tells you a run is over, even when nothing needs a decision.
- **Use ask_question for "which one?".** Deploys, migrations, deletes and branch choices go to your phone and wait for you.
- **Use send_message for updates you do not need to answer.** Claude can post a short summary to the same thread when it finishes.

![A woman on her sofa taps one of two answer options on her phone while her laptop keeps working on the coffee table.](https://d29bihfk9mha1v.cloudfront.net/notifex/blog-claude-code-notification-when-done-notif-3-v2.webp)

_Illustration: the hook says done; the question waits for your choice._

The send_message route depends on Claude following your instruction, so it is less strict than a hook. Many people keep both: the hook as a safety net, the thread as the record.

## Which option fits how you work?

Pick by where you will be when Claude stops.

- **At your desk:** a Notification hook with a desktop command is enough.
- **Away, and you only need to know it finished:** a hook that posts to a push service such as ntfy.
- **Away, on a claude.ai plan, and you want to drive the whole session:** Remote Control with push turned on.
- **Away, and Claude needs a decision it should not guess:** an MCP question through Notifex. This also works from Cursor, Codex and other MCP clients, as listed on [the page for connecting other agents](https://notifexapp.com/connect-your-agent).

For a broader comparison of ways to keep a person in charge, see [push questions vs terminal prompts](https://notifexapp.com/compare/push-questions-vs-terminal-prompts).

## Quick answers

### Does Claude Code have a built-in notification when done?

Claude Code fires a Notification hook event when it waits for input or permission, and a Stop event when it finishes responding. You attach your own command to either event in settings.json.

### What is the idle_prompt matcher?

It is a Notification matcher that fires when Claude finished responding about 60 seconds ago and you have not typed since. It suits a quiet "come back" ping.

### Can a hook send the notification to my phone?

Yes. Make the hook command post to a push service, for example a curl request to an ntfy topic. The message still goes one way only.

### How do I answer Claude Code from my phone?

You have two routes. Drive the whole session with Remote Control in the Claude app. Or add an MCP server such as Notifex, so Claude asks a question on your phone and waits for your answer.
