# Get a desktop notification when Claude Code finishes, with a Stop hook

> Source: <https://dev.to/aicoding-guide/get-a-desktop-notification-when-claude-code-finishes-with-a-stop-hook-3832>
> Published: 2026-09-20 19:07:56+00:00

*Originally published at [https://aicoding-guide.com](https://aicoding-guide.com/en/posts/claude-code-hooks-stop-notify/).*

Watching a terminal to see whether a long task has finished is wasted time. A notification at the moment it completes frees you to do something else in the meantime.

The event that fires when Claude finishes responding is the **`Stop` hook**. The `Notification` hook in the documentation's getting-started walkthrough is a different thing: it tells you Claude is waiting for input. This article keeps the two apart and gives the setup for all three platforms.

**Key point**

What you will learn

- How
`Stop` differs from `Notification`, and which one you want- The notification command and config for macOS, Linux and Windows
- The exit-code trap that can keep Claude from stopping

The names are similar; the timing is not.

| Event | Fires when | Matcher | 
|---|---|---|
| `Stop` | Claude finishes responding | Not supported | 
| `SubagentStop` | A subagent finishes | Matches on agent type | 
| `Notification` | Claude Code sends a notification (permission prompt, idle, and so on) | Matches on notification type | 

"Tell me when the work is done" is `Stop`. "Tell me when it's stuck on a permission prompt" is `Notification`. Configuring both is fine.

The notification types you can match on include `permission_prompt`, `idle_prompt`, `auth_success`, `agent_needs_input` and `agent_completed`. The full list of matcher values per event is in [Every value you can put in a Claude Code hook matcher](https://aicoding-guide.com/en/posts/claude-code-hooks-matcher/).

**A matcher on Stop is ignored**

`Stop` does not support a matcher. Adding one is not an error — it is silently ignored, and the hook fires every time. To narrow it, branch inside the hook script instead.

These go in `~/.claude/settings.json`. Create the file if it does not exist.

```
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code finished\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}
```

If nothing appears, Script Editor — which `osascript` routes notifications through — probably lacks notification permission. The documentation notes that in that case the command fails silently and macOS never prompts you to grant it. Run this once in Terminal so Script Editor shows up in your notification settings, then enable **Allow Notifications** for **Script Editor** under **System Settings > Notifications**.

```
osascript -e 'display notification "test"'
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code finished'"
          }
        ]
      }
    ]
  }
}
```

`notify-send` needs a desktop notification daemon, which headless servers, SSH sessions and most containers do not have. Test the command directly first. If it is not found, install `libnotify-bin` on Debian and Ubuntu, or your distribution's equivalent.

```
notify-send 'Claude Code' 'test'
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code finished', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}
```

Run `/hooks` afterwards to see the configured hooks per event and which file each came from. Note that the `/hooks` menu is read-only: to add, modify or remove hooks, edit the settings JSON directly or ask Claude to do it.

This is the part specific to `Stop`. **A `Stop` hook that exits with code 2 blocks the stop, and the conversation continues.** If your notification command fails and returns 2, Claude keeps going when you did not intend it to.

When all you want is a notification, make sure the command exits 0.

```
{
  "type": "command",
  "command": "notify-send 'Claude Code' 'Claude Code finished' || true"
}
```

`|| true` turns a failed notification into a 0 exit.

There is also a cap on blocking. The documentation states that Claude Code overrides a `Stop` hook after it blocks **eight times in a row without progress**. If you write a hook that deliberately blocks, read `stop_hook_active` from the JSON on stdin and exit early once you have already triggered a continuation.

``` bash
#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic
```

A `Stop` hook's stdin carries `last_assistant_message` and `stop_reason`, so the notification can say what actually finished.

``` bash
#!/usr/bin/env bash
# ~/.claude/hooks/notify-done.sh
INPUT=$(cat)
MSG=$(echo "$INPUT" | jq -r '.last_assistant_message // empty' | head -c 120)
notify-send 'Claude Code' "${MSG:-Claude Code finished}" || true
exit 0
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/notify-done.sh"
          }
        ]
      }
    ]
  }
}
```

For the full shape of that JSON, see [The JSON your Claude Code hooks receive on stdin](https://aicoding-guide.com/en/posts/claude-code-hooks-stdin-json/). For building hooks generally, see [Run lint and format automatically after every edit](https://aicoding-guide.com/en/posts/claude-code-hooks-lint-format/).

**Glossary**

**stop_reason**: a string describing why Claude stopped. A normal end of turn carries `end_turn`.

`Stop` for "work finished" and `Notification` for "waiting on you"`osascript`, Linux `notify-send`, Windows a PowerShell MessageBox`|| true` when you only want a notification`stop_hook_active` to stay under the eight-block cap`last_assistant_message` lets the notification say what finished