Get a notification when Claude Code is done

Claude Code can warn you when it finishes or needs your approval: set preferredNotifChannel to "terminal_bell" for a sound in any terminal, or add a Notification or Stop hook that runs an alert. One step further, when you run Claude Code in the Claude desktop app, SpeakApp reads the finished reply aloud and lets you answer it by voice, without going back to the screen.

What Claude Code does by default

Claude Code sends a notification when it finishes a task or pauses for a permission prompt while you seem to be away from the terminal. What you actually get depends on the terminal:

  • Ghostty, Kitty and iTerm2: a desktop notification. iTerm2 shows it only once its alerts are on: Settings → Profiles → Terminal, check “Notification Center Alerts”, then in “Filter Alerts” enable “Send escape sequence-generated alerts”.
  • Apple Terminal: no sound by default.
  • Any other terminal, Windows Terminal and the VS Code integrated terminal included: nothing.

The notification for a finished task also takes its time: it arrives about 60 seconds after Claude stops responding, and only if you haven't typed since. On Windows, without a setting, a long task ends in silence.

Option 1: ring the terminal bell

One setting makes Claude Code send the bell character in every terminal. Add it to ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

In Windows Terminal the bell plays a sound by default. To also flash the taskbar icon, set the profile's bellStyle to "all"; when the window is not in focus, only the icon flashes. In Apple Terminal, turn on Audible bell under Settings → Profiles → Advanced to hear it.

Option 2: a desktop alert with a hook

A hook runs a command of your choice at a given moment of a Claude Code session. Hooks run alongside the built-in notification, they don't replace it. This Notification hook comes from the Claude Code documentation; add it to ~/.claude/settings.json.

Windows (PowerShell)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

It opens a dialog box rather than a notification in the corner of the screen, so the box can appear behind your terminal window. Test the command in PowerShell first. If you run Claude Code under WSL, powershell.exe has to be on your PATH.

macOS and Linux

Keep the same block and change the command line:

  • macOS: "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'". If nothing shows up, run the command once in Terminal, then allow notifications for Script Editor in System Settings → Notifications.
  • Linux: "command": "notify-send 'Claude Code' 'Claude Code needs your attention'". It needs a desktop notification daemon; on Debian and Ubuntu, install libnotify-bin.

Choose when it fires

The empty matcher fires on every notification type. Two of them cover most needs:

  • permission_prompt: Claude is waiting for you to approve a tool use, and the request has been waiting for about six seconds.
  • idle_prompt: Claude finished responding about 60 seconds ago and you haven't typed since.

Type /hooks in Claude Code to check that your hook is listed.

An alert as soon as Claude finishes

For a signal at the end of every reply, without the one-minute wait, use the Stop hook: it fires each time Claude finishes responding, even when you are at your desk. A short sound suits it better than a dialog box. On Windows:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -NoProfile -Command \"[console]::beep(880,300)\""
          }
        ]
      }
    ]
  }
}

On macOS, the sound from the documentation's example works the same way: "command": "afplay /System/Library/Sounds/Glass.aiff".

Option 3: hear the reply and answer by voice

A bell or a dialog box tells you that Claude has finished. You still have to go back to the screen, find the right window, read the reply and type your answer. SpeakApp removes that trip. It reads each finished reply aloud, one after another, as soon as it is ready. You say “ok” and answer by voice, and your message goes straight into the session that spoke, without hunting for its window, touching the keyboard or looking at the screen.

When several sessions finish together, their replies wait their turn. Each conversation gets its card in the reading toast, the panel SpeakApp shows above your windows in the top right corner, with read, skip, later, reply and open. The widget's circle counts what is still waiting. You run all your sessions by voice instead of being called back to each one. How the reading loop works.

Where it works today: Claude Code in the Claude desktop app (Code tab), the Codex app for Windows, and ChatGPT in Chrome. SpeakApp does not read a Claude Code session running in a terminal, nor sessions that run in the cloud.

Which one to choose

What you needTerminal bellHook alertSpeakApp
Know that Claude is doneYes, a soundYes, a dialog box or a soundYes, the reply starts playing
Know what Claude answeredNoNoYes, it is read aloud
Answer without the keyboardNoNoYes, you say “ok” and speak
Follow several sessionsThe same sound for allOne alert per eventReplies queue up, one card each
SetupOne line in settings.jsonA block in settings.jsonInstall the app

Frequently asked questions

Why doesn't Claude Code notify me on Windows?

Claude Code shows a desktop notification by default only in Ghostty, Kitty and iTerm2. In Windows Terminal it sends nothing. Set preferredNotifChannel to "terminal_bell" for a sound, or add a Notification hook for a dialog box.

Why does my notification arrive a minute after Claude has finished?

The finished-task notification, idle_prompt, fires about 60 seconds after Claude stops responding, and only if you haven't typed since. For a signal right away, use a Stop hook.

What is the difference between the Notification hook and the Stop hook?

Notification fires when Claude Code sends a notification: a permission request waiting for about six seconds, or a reply finished about a minute ago. Stop fires each time Claude finishes responding.

Do hooks replace the built-in notification?

No. Hooks run alongside it.

Can I hear Claude Code's replies instead of reading them?

Yes, with SpeakApp, when you use Claude Code in the Claude desktop app (Code tab): each finished reply is read aloud and you answer by voice. SpeakApp does not read a Claude Code session running in a terminal.

How do I follow several Claude Code sessions at once?

A terminal that implements the OSC 7501 status protocol shows whether each session is working, waiting for you or done (Claude Code 2.1.295 or later). With SpeakApp, replies from several sessions wait in a queue and are read one after another, and you answer each one by voice.

Is SpeakApp free?

SpeakApp has a free plan with every feature, within volume limits. Paid plans are on the pricing page.

Try SpeakApp

SpeakApp runs on Windows; the Mac beta has a waiting list. Download SpeakApp or join the Mac waiting list. To see the whole product first: What is SpeakApp?

Sources

Claude Code documentation, read on 1 November 2026: Configure your terminal and Automate actions with hooks. Microsoft documentation: Windows Terminal advanced profile settings. The beep command uses the standard .NET Console.Beep method. What SpeakApp reads, app by app: the features page.