A developer walks her dog in the park and glances at a done notification on her phone while her laptop sits at home.

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 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.
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 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 matcherFires whenGood for
Notification, matcher permission_promptClaude needs you to approve a tool use, and the prompt has waited about six secondsRuns that stall on a permission you did not pre-approve
Notification, matcher idle_promptClaude finished responding about 60 seconds ago and you have not typed sinceA quiet "it is done, come back" ping
Notification, empty matcherAny notification type, including the two aboveOne hook that covers every wait
StopClaude finishes respondingShort 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.
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 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 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. Other agents have their own alerts: Cursor notifications when the agent is done and how Codex notifications work.

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.
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 or your Android phone. 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.
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. The Notifex setup page for 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.

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.
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.

For a broader comparison of ways to keep a person in charge, see push questions vs terminal prompts.

Quick answers

  • 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.

Give your agent someone to ask

Free on the App Store and Google Play. Then add one MCP entry and let your agent ask.

Download on the App StoreGet it on Google Play