Claude Code Notification When Done: Toast and Chime

Done Toast gives you a Claude Code notification when done: once a turn that took a while finishes, a toast says Done in 2m 14s and a short two-note chime plays. A turn that ends on an error says Stopped on an error after 2m 14s instead. Short turns, interrupted turns and subagent turns stay silent, so the sound means "come back, your answer is ready".

If you work in another window during long tasks, turn on the system notification option and the same message appears in macOS Notification Center or as a Linux notify-send popup. Requires Claude Code 2.1.287 or later.

The recording sends Claude a task that takes longer than the threshold. When the turn completes, the toast with the turn's duration appears at the bottom of the screen.

Choose one of the methods in the install block. Sound works on macOS out of the box; system notifications are opt-in.

The mod has a single hook. From hooks/register.ts:

on('turn.complete', async ($, e, next) => {
  const result = await next(e)
  if (!shouldNotify(e, minSeconds)) return result

  const text = toastText(e, includeAnswerPreview)
  $.ui.toast(text)

  if (sound) {
    $.audio.play({ asset: 'sounds/done.wav' }).catch(() => undefined)
  }

  if (systemNotification) {
    platform ??= $.process
      .run(['uname', '-s'], { timeoutMs: 5000 })
      .then(ran => (ran.exitCode === 0 ? parseUname(ran.stdout) : undefined))
      .catch(() => undefined)
    platform
      .then(found =>
        found === undefined ? undefined : $.process.run(notificationArgv(found, 'Claude Code', text), { timeoutMs: 10000 }),
      )
      .catch(() => undefined)
  }

  return result
})

turn.complete fires when Claude finishes a turn. The hook awaits next(e) first, so it never delays the turn's result. shouldNotify in hooks/format.ts returns false for subagent turns (those with an agentId), aborted turns and anything shorter than minSeconds. toastText formats the duration as 45s, 2m 14s or 1h 3m.

The chime is sounds/done.wav, bundled with the mod and played with $.audio.play. The mods API has no platform field and no notification call, so when system notifications are on, the mod asks uname -s once and caches the answer. It then runs osascript -e 'display notification …' on macOS or notify-send on Linux. Arguments go in as an argv array with no shell, so quotes in Claude's answer cannot break out. The sound and notification are fire-and-forget; errors are swallowed.

Change these options in /config. To use your own sound, replace sounds/done.wav in the mod folder, or change the asset path in the hook. The toast wording comes from toastText in hooks/format.ts, and the notification title 'Claude Code' is the second argument to notificationArgv.

Changes the UI covers the toast. Plays sound covers the chime. Runs commands appears because $.process.run is in the code, but it is only used when you turn on systemNotification: then it runs uname -s once, followed by osascript or notify-send with fixed arguments. With the default settings no process is started.

The mod does not intercept tool calls, read your prompts, touch files or use the network. Disable it with /plugin disable cm-done-toast, or start a session with all mods off using claude --safe-mode.

Tested with Claude Code 2.1.291 on macOS in the terminal. If nothing happens when a turn ends:

• Check claude --version is 2.1.287 or later and the mod is enabled in /plugin.
• Run /reload-plugins after installing from the shell.
• The turn may have been shorter than minSeconds.
• No sound outside macOS is expected.
• On macOS, allow notifications for your terminal app in System Settings if the system notification never shows.
• On Linux, install libnotify (notify-send) for system notifications.