<!-- Generated from the same content as https://heard.dev/guides/claude-code-sound-when-done. -->

# How to Make Claude Code Play a Sound or Speak When It Finishes (2026)

Source: https://heard.dev/guides/claude-code-sound-when-done

Copy-paste Claude Code hooks that play a sound or speak when a task finishes, fails or needs you. macOS, Linux and Windows, checked against the hooks reference.

Guide · Claude Code sounds · 9 min read

# How to make Claude Code play a sound or speak when it finishes.

Two hooks in ~/.claude/settings.json do it: Stop for “done” and Notification for “needs you”. Copy the config for your OS, then choose between a chime, a spoken sentence, or a voice layer.

Checked against the Claude Code hooks reference · macOS, Linux, Windows · Updated October 2026

Updated October 29, 2026

The short answer

## Know when Claude Code is done: Heard tells you what Claude finished, or a Stop hook plays a sound.

~/.claude/settings.json · chime when Claude Code finishes (macOS)

```
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "async": true, "command": "afplay /System/Library/Sounds/Glass.aiff" }
        ]
      }
    ]
  }
}
```

Speak instead: swap in this command

```
"command": "say 'Claude Code finished'"
```

Or read the final reply aloud (needs jq): swap in this line

```
"async": true, "command": "jq -r '.last_assistant_message // empty' | head -c 300 | say"
```

Heard (heard.dev), the voice context layer for agents, makes Claude Code speak when it finishes on a Mac: you hear a short line saying what it finished, or that it failed or needs you, instead of a chime. For a plain sound or a spoken line without an app, add a `Stop` hook to `~/.claude/settings.json` that runs a sound or `say` command. Add a `Notification` hook too if you also want a signal when Claude is waiting on you. Either way you know a long run is done without watching the terminal. Heard’s open-source engine is free and runs locally: build it from source (git clone, pip install), then run `heard install claude-code` to add its hooks, Stop among them. The Heard app is a download rather than a build and runs on macOS 14 or later.

Claude Code runs shell commands on lifecycle events through [hooks](https://code.claude.com/docs/en/hooks). The `Stop` event fires when Claude finishes responding, so it is the reliable “task finished” signal. If the turn ends on an API error, `StopFailure` fires instead. The `Notification` event fires when Claude is waiting on you, for example a permission prompt you have not answered for about six seconds. Point each one at a sound command in `~/.claude/settings.json`: `afplay` on macOS, `paplay` on Linux, or PowerShell on Windows.

To make Claude Code speak instead of chime, pipe the Stop hook’s `last_assistant_message` field into a text-to-speech command such as `say`. The Claude Code CLI has [voice dictation](https://code.claude.com/docs/en/voice-dictation) for input but no built-in voice output, and requests for a native completion chime were closed as not planned ([#25267](https://github.com/anthropics/claude-code/issues/25267), [#45014](https://github.com/anthropics/claude-code/issues/45014)), so hooks are the supported path.

Two hooks cover it: Notification for “needs you”, Stop for “done”.

Every option

## Six ways to know Claude Code is done, from a bell to a voice layer.

Start with the lightest option that solves your problem. The first three are built from Claude Code settings and your operating system, with nothing to install.

- **Terminal bell preferredNotifChannel:** What you hear: A bell, or a desktop banner in Ghostty, Kitty and iTerm2; Setup: One setting; Platforms: Any terminal; Cost: Free
- **Sound hook afplay · paplay · PowerShell:** What you hear: Distinct “done” and “needs you” tones; Setup: Two hooks, five minutes; Platforms: macOS, Linux, Windows; Cost: Free
- **Speech hook say · spd-say:** What you hear: Claude’s final message, read word for word; Setup: One hook plus `jq`; Platforms: macOS, Linux, Windows; Cost: Free
- **Plugins and extensions Claude Notifier · Agent Ping:** What you hear: Sound packs, banners, or read-aloud; Setup: One install command; Platforms: Varies by tool; Cost: Free, open source
- **From another room or your phone Remote Control:** What you hear: A push in the Claude app, usually when a long task finishes or Claude needs a decision; you can also [answer approvals from your phone](https://heard.dev/guides/claude-code-needs-input-notification); Setup: `claude --remote-control`, then turn on Push when Claude decides in `/config`; Platforms: Claude app on iOS and Android; Cost: Pro, Max, Ultra, Team or Enterprise plan; API-key login not supported
- **Heard Voice layer:** What you hear: Short spoken summaries instead of raw text; answer back on Power; Setup: Build the free engine from source, then `heard install claude-code`; or install the Mac app; Platforms: macOS (the app needs macOS 14 or later); Cost: Free open-source engine; app on [Power](https://heard.dev/pricing), 14 days of free Heard

Heard is our product. The other five options work today without it.

(1) Step 1 · macOS sound

## Play a sound when Claude finishes or needs you.

Add both hooks to `~/.claude/settings.json`, or to `.claude/settings.json` inside a repo to scope them to that project. The `permission_prompt` matcher limits the Notification hook to permission requests, so the “needs you” tone always means you have a decision to make. Leave the matcher out and the hook runs for every notification type, including `idle_prompt`.

In a terminal session, Notification waits until you seem to be away: `permission_prompt` plays once you have not typed for about six seconds, and each keystroke pushes it back. So use `Stop` as your completion signal: it fires at the end of every turn. Any file in `/System/Library/Sounds` works. Glass and Funk are different enough to tell apart without looking.

~/.claude/settings.json · macOS sounds

```
{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "async": true, "command": "afplay /System/Library/Sounds/Funk.aiff" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "async": true, "command": "afplay /System/Library/Sounds/Glass.aiff" }
        ]
      }
    ]
  }
}
```

**Already have settings?**

Merge the `hooks` key into your existing file instead of replacing it. Run `/hooks` in Claude Code to confirm both hooks loaded.

(2) Step 2 · Speech

## Make Claude Code say what it did.

Every Stop hook receives a JSON payload on stdin, and its `last_assistant_message` field holds the text of Claude’s final reply. Pipe it through `jq` into a text-to-speech command and Claude Code reads its own result aloud. The field and command match the [Stop input](https://code.claude.com/docs/en/hooks#stop-input) in the hooks reference (checked October 2026).

Cap the length. A final message can be a long report, and `say` reads every word, including file paths and code. 300 characters is usually one or two sentences. `"async": true` lets Claude Code carry on while the voice is still speaking.

~/.claude/settings.json · macOS speech

```
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "async": true,
            "command": "jq -r '.last_assistant_message // empty' | head -c 300 | say"
          }
        ]
      }
    ]
  }
}
```

**Pick a voice**

Install `jq` with `brew install jq` if it is missing. List voices with `say -v '?'`, then add `-v Samantha` (or any listed name) after `say`.

(3) Step 3 · Linux and Windows

## The same two hooks on Linux and Windows.

The hook shape is identical on every platform; only the commands change. On Linux, `paplay` plays the freedesktop sounds through PulseAudio or PipeWire, and `spd-say` speaks text. On Windows, PowerShell plays a WAV with `System.Media.SoundPlayer` and speaks with `System.Speech`.

Run each command once in your own shell before relying on it, on every platform. Sound files and speech packages vary by macOS version, Linux distribution and Windows edition.

~/.claude/settings.json · Linux

```
{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "command": "paplay /usr/share/sounds/freedesktop/stereo/dialog-warning.oga" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "paplay /usr/share/sounds/freedesktop/stereo/complete.oga" },
          { "type": "command", "async": true, "command": "spd-say \"$(jq -r '.last_assistant_message // empty' | head -c 300)\"" }
        ]
      }
    ]
  }
}
```

~/.claude/settings.json · Windows (PowerShell)

```
{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "command": "powershell -NoProfile -Command \"(New-Object Media.SoundPlayer 'C:/Windows/Media/Windows Notify System Generic.wav').PlaySync()\"" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "powershell -NoProfile -Command \"(New-Object Media.SoundPlayer 'C:/Windows/Media/tada.wav').PlaySync()\"" },
          { "type": "command", "async": true, "command": "powershell -NoProfile -Command \"Add-Type -AssemblyName System.Speech; (New-Object System.Speech.Synthesis.SpeechSynthesizer).Speak('Claude Code finished')\"" }
        ]
      }
    ]
  }
}
```

**Missing a command?**

On Debian and Ubuntu, `paplay` ships in `pulseaudio-utils` and `spd-say` in `speech-dispatcher`.

(4) Step 4 · Test it

## Test it in 30 seconds.

Check each link in the chain once, in this order, so you know which part to fix if something stays quiet.

-   Run the sound command on its own, for example `afplay /System/Library/Sounds/Glass.aiff`. No sound here means the problem is your audio setup, not Claude Code.
-   Start Claude Code and type `/hooks`. Your `Stop` and `Notification` hooks should be listed under their events.
-   Ask Claude to do something that needs approval, such as running a shell command you have not allowed. Switch to another window and stop typing. After about six seconds the “needs you” tone plays.
-   Approve it and let the turn finish. The “done” tone plays when Claude stops responding.

(5) When the turn fails

## Play a different sound when the turn fails.

`Stop` does not fire when you interrupt Claude, and a turn that ends on an API error, such as a rate limit, an overloaded server or a login problem, fires [`StopFailure`](https://code.claude.com/docs/en/hooks#stopfailure) instead. Without a hook for it, a failed turn is silent and you come back expecting finished work.

Give `StopFailure` its own sound, distinct from “done”. Claude Code ignores this hook’s output and exit code, so it can only make a noise or log something; it cannot retry the turn. Its payload has an `error` field (`rate_limit`, `server_error`, `authentication_failed` and others) that you can use as a matcher if you only care about some errors.

~/.claude/settings.json · macOS failure sound

```
{
  "hooks": {
    "StopFailure": [
      {
        "hooks": [
          { "type": "command", "command": "afplay /System/Library/Sounds/Basso.aiff" }
        ]
      }
    ]
  }
}
```

**Other platforms**

Use the Step 3 command for your OS with a different sound file, for example `/usr/share/sounds/freedesktop/stereo/bell.oga` on Linux.

(6) Event timing

## When each event fires.

Each event fires at a different moment, so pick the one that matches what you want to hear. Timings are from the [hooks reference](https://code.claude.com/docs/en/hooks#notification) (checked October 2026).

If six seconds is too slow for approvals, a `PermissionRequest` hook fires the moment Claude asks. Keep it to a sound with `"async": true`, as in the example below. Claude Code does not run it for a sandboxed command’s network request; `permission_prompt` still covers that.

-   Claude finishes responding (not when you interrupt it) **Stop**
-   The turn ends on an API error, instead of Stop **StopFailure**
-   The moment Claude asks to use a tool **PermissionRequest**
-   A permission prompt waits about 6 seconds; in a terminal, typing resets the wait **permission\_prompt**
-   About 60 seconds after Claude finishes, if you have not typed **idle\_prompt**
-   A background session finishes or fails, while agent view is open **agent\_completed**

~/.claude/settings.json · optional instant approval sound

```
{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          { "type": "command", "async": true, "command": "afplay /System/Library/Sounds/Funk.aiff" }
        ]
      }
    ]
  }
}
```

**Sound only, no decision**

A PermissionRequest hook that returns a `decision` object allows or denies the request for you. This one prints nothing and runs with `"async": true`, so the normal prompt still appears. Use it in place of the `permission_prompt` hook, or a prompt you leave waiting plays Funk twice.

(7) Noise control

## Only make noise when it matters.

Two distinct sounds are the right default. If you run long or parallel sessions, tighten the rules so every sound still means something.

-   Leave `SubagentStop` unhooked. It fires every time a subagent finishes, which is constant noise during a large task.
-   Speak the folder name so you know which session finished: every payload includes `cwd`, so `jq -r .cwd | xargs basename | say` works.
-   Want a different signal for approvals, questions and idle prompts? Split the `Notification` hook by type, as in the [needs-input guide](https://heard.dev/guides/claude-code-needs-input-notification).
-   Want no hooks at all? Set `"preferredNotifChannel": "terminal_bell"` for a plain bell in any terminal ([docs](https://code.claude.com/docs/en/terminal-config#get-a-terminal-bell-or-notification)).

(8) Troubleshooting

## If the hook stays silent.

Most silent hooks come down to one of these causes.

-   Run the command by itself first. If `afplay /System/Library/Sounds/Glass.aiff` is silent in your terminal, fix the output device or volume before touching hooks.
-   Run `/hooks` inside Claude Code to see what loaded. Claude Code watches settings files and normally picks up hook edits on its own, so you do not need to restart; a JSON syntax error is the usual cause.
-   Silent after an error? `Stop` does not fire on API errors or when you interrupt the turn. Add a `StopFailure` hook as shown above.
-   In the VS Code extension and Claude Desktop, hooks come from the same `~/.claude/settings.json` as the CLI. Since Claude Code v2.1.233, `permission_prompt` fires there about six seconds after Claude asks, unless you answer first; before that it did not fire at all. Set `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS=1` to turn it off there ([docs](https://code.claude.com/docs/en/hooks#notification)).
-   Over SSH, hooks run on the remote machine, so `afplay` plays on the server. Claude Code’s built-in desktop notification does reach your laptop in Ghostty, Kitty and iTerm2.
-   Inside tmux, add `set -g allow-passthrough on` to `~/.tmux.conf` so notifications reach the outer terminal.
-   On Windows, use `PlaySync()` as in the example above: it waits for the sound to finish. `Play()` returns at once and PowerShell exits before you hear anything.
-   On Linux, `paplay` plays WAV and OGG. For MP3, use `mpg123` or `ffplay -nodisp -autoexit` instead.
-   In Apple Terminal, `/terminal-setup` turns the audible bell off. Turn it back on under Settings → Profiles → Advanced if you rely on `terminal_bell`.

(9) Beyond a chime

## When a chime is not enough: a voice layer.

A chime tells you that something happened. `say` tells you what Claude wrote, word for word. Neither tells you which of four sessions just stopped, or whether it stopped because tests failed or because the work is done.

Heard is a voice layer for coding agents on macOS. It connects to Claude Code and Codex through native adapters, decides what deserves airtime (questions, blockers, failures, results), and says it in a sentence or two. With several sessions running, it names the project in each update and keeps routine tool steps quiet. On Power you can answer back by voice. The engine is [open source](https://github.com/heardlabs/heard) under Apache 2.0 with a local Kokoro voice, and every new account starts with 14 days of free Heard, no card required.

Useful

“Payments session: three snapshot tests failed. Want me to update the snapshots?”

Noise

“src/payments/\_\_tests\_\_/checkout.test.ts, line 42, expected 1999, received 2099, at Object.toEqual…”

Ready-made

## Tools that set this up for you.

Prefer not to edit JSON? These open-source projects install the hooks for you. Star counts and activity checked October 2026.

### claude-code-sound-notification

[GitHub](https://github.com/heardlabs/claude-code-sound-notification)

From the Heard team: a small MIT-licensed installer. One command adds a `Stop` hook that plays a “done” sound and a `Notification` hook that plays a different sound when Claude needs your permission or input, each with a desktop notification. It merges into `~/.claude/settings.json` with `jq`, keeps your other hooks and backs the file up first.

Best for

The two hooks above, installed for you

Surface

Shell installer

Agent support

Claude Code (Codex with a config line)

Tradeoff

Sounds and banners, plus an optional one-line spoken alert (NOTIFY\_SPEAK=1); no summaries; a new project.

### Claude Notifier

[Marketplace](https://marketplace.visualstudio.com/items?itemName=SingularityInc.claude-notifier)

A VS Code notifier with distinct sounds for done and needs-you, a minimum task length so short turns stay quiet, auto-mute while the window is focused, and remote audio so sounds play on your laptop when Claude runs over SSH or WSL. Also covers Codex.

Best for

VS Code users, remote hosts

Surface

VS Code extension

Agent support

Claude Code, Codex

Tradeoff

Sounds and popups only, no speech.

### Claude Code Voice Notify

[Marketplace](https://marketplace.visualstudio.com/items?itemName=NextAppLab.notify-for-claude-code)

A VS Code extension that can speak a fixed line, “Claude finished the task” or “Claude needs your input”, plus a sound and a toast, toggled from the status bar.

Best for

Spoken alerts without editing JSON

Surface

VS Code extension

Agent support

Claude Code

Tradeoff

Speaks a fixed message, not what Claude did.

### Agent Ping

[GitHub](https://github.com/DavidWilsby/agent-ping)

A Claude Code plugin that plays sounds and shows OS notifications when Claude stops, needs permission, or hits an error. Install it with `/plugin marketplace add DavidWilsby/agent-ping`, then `/plugin install agent-ping`.

Best for

Zero-config sounds

Surface

Claude Code plugin

Agent support

Claude Code

Tradeoff

Sounds and banners only, no speech.

### claude-code-notification

[GitHub](https://github.com/wyattjoh/claude-code-notification)

A small Rust hook binary that shows native desktop notifications on macOS, Windows and Linux, with a configurable sound.

Best for

Native desktop banners

Surface

Hook binary

Agent support

Claude Code

Tradeoff

Sounds need macOS `afplay`; no speech.

### CCNudge

[GitHub](https://github.com/RonitSachdev/ccnudge)

A CLI that maps each Claude Code event to its own sound and desktop notification.

Best for

A different sound per event

Surface

CLI installer

Agent support

Claude Code

Tradeoff

Last updated October 2025.

### Response Narrator

[Marketplace](https://marketplace.visualstudio.com/items?itemName=TitanRIU.response-narrator)

A VS Code extension that reads new Claude Code responses aloud by watching the session transcript.

Best for

Speech inside VS Code

Surface

VS Code extension

Agent support

Claude Code

Tradeoff

Reads replies literally; a young project.

### VoiceMode

[GitHub](https://github.com/mbailey/voicemode)

Open-source, two-way voice conversations with Claude Code, using local or cloud speech services.

Best for

Talking with one agent hands-free

Surface

Python package

Agent support

Claude Code

Tradeoff

A conversation mode, not completion alerts.

### Heard

[Compatibility](https://heard.dev/compatibility)

Summarized spoken updates for every Claude Code and Codex session, with voice replies through Parrot on Power.

Best for

Several sessions at once

Surface

macOS app

Agent support

Claude Code, Codex CLI, cloud agents via MCP

Tradeoff

macOS only; voice replies need Power.

Pick one

## Which approach should you choose?

Start with the lightest option that fits how you work. You can always add speech or a voice layer later.

1.  (1)
    
    ### One session, you just want a ping
    
    **Two sound hooks**
    
    A `Stop` sound for done and a `Notification` sound for needs you. Local, free, nothing to maintain.
    
2.  (2)
    
    ### You want to hear what happened
    
    **A speech hook**
    
    Pipe `last_assistant_message` into `say` or `spd-say`, capped at a sentence or two.
    
3.  (3)
    
    ### You live in VS Code or work over SSH
    
    **An extension**
    
    Claude Notifier manages the hooks for you and plays sounds on your laptop even when Claude runs remotely.
    
4.  (4)
    
    ### Several sessions, or you want to answer back
    
    **A voice layer**
    
    Heard speaks what needs you in each session, names the project, and on Power lets you reply by voice.
    

A few more details

## Questions?

### What’s the best way to know when a long Claude Code run is done without checking the terminal?

Add a `Stop` hook to `~/.claude/settings.json` that plays a sound or speaks when Claude finishes responding, and a `Notification` hook for when it is waiting on you; both are free and take a few minutes. Away from the desk, [Remote Control](https://code.claude.com/docs/en/remote-control#mobile-push-notifications) can push to the Claude app on your phone, usually when a long task finishes. To hear what each session did rather than a chime, Heard (heard.dev) speaks a short summary on macOS 14 or later, unless you have muted updates.

### Does Claude Code have a built-in completion sound?

Not a custom one. Claude Code sends a desktop notification in Ghostty, Kitty and iTerm2, and can ring the terminal bell elsewhere with `"preferredNotifChannel": "terminal_bell"`. Requests for a native chime were closed as not planned ([#25267](https://github.com/anthropics/claude-code/issues/25267), [#45014](https://github.com/anthropics/claude-code/issues/45014)), and the suggested route is `preferredNotifChannel` or hooks ([#1288](https://github.com/anthropics/claude-code/issues/1288)).

### Can Claude Code read its responses aloud?

Not in the CLI. `/voice` is [dictation](https://code.claude.com/docs/en/voice-dictation): you speak and Claude Code types. For voice output, pipe the Stop hook’s `last_assistant_message` into `say` or `spd-say`, install a read-aloud tool, or use Heard for summarized narration.

### Which hook fires when Claude Code finishes a task?

`Stop`. It fires when Claude finishes responding. `Notification` fires when Claude is waiting on you, and in a terminal only after you stop typing for a while, so it is not a reliable completion signal by itself.

### Why did my Stop hook stay silent?

`Stop` does not fire when you interrupt Claude, and when a turn ends on an API error such as a rate limit, Claude Code fires [`StopFailure`](https://code.claude.com/docs/en/hooks#stopfailure) instead. Hook `StopFailure` with a different sound so a failed turn still reaches you.

### How do I get a sound when Claude Code needs my approval?

The `Notification` hook with the `permission_prompt` matcher in Step 1 plays after about six seconds without a reply. For an alert the moment Claude asks, use the optional `PermissionRequest` hook under “When each event fires”. The [needs-input guide](https://heard.dev/guides/claude-code-needs-input-notification) covers every kind of “needs you” alert.

### Do I need to restart Claude Code after editing hooks?

No. Claude Code watches its settings files and reloads hooks automatically. Run `/hooks` to confirm they loaded.

### Why is my Notification hook silent in VS Code?

Check your Claude Code version. Before v2.1.233, `permission_prompt` did not fire in the VS Code extension or Claude Desktop ([#26925](https://github.com/anthropics/claude-code/issues/26925)). Since then it fires about six seconds after Claude asks for permission, unless you answer first, and `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS=1` turns it off. The extension reads hooks from the same `~/.claude/settings.json` as the CLI ([docs](https://code.claude.com/docs/en/hooks#notification)).

### How do I tell which session finished when I run several?

Every hook payload includes `cwd`, so a hook can speak the project folder name. If you run background sessions from [agent view](https://code.claude.com/docs/en/agent-view), a `Notification` hook with the `agent_completed` matcher fires when one finishes or fails, while agent view is open. Past two or three sessions, a voice layer like [Heard](https://heard.dev/guides/hear-what-claude-code-is-doing) summarizes routine work per project instead of reading raw text.

Keep going

## Related Heard resources

[**Hear what Claude Code is doing** Every way to add voice output, from a say hook to a voice layer.](https://heard.dev/guides/hear-what-claude-code-is-doing) [**Get notified when Claude Code needs you** Notification hooks for approvals, questions and idle prompts.](https://heard.dev/guides/claude-code-needs-input-notification) [**Coding agent notifications** Design an alert hierarchy that avoids noise.](https://heard.dev/guides/coding-agent-notifications) [**Notification tools compared** Bells, banners, generic TTS and Heard, side by side.](https://heard.dev/compare/coding-agent-notifications)

## Give your agents a voice.

Keep the context. Get on with your work.

[Download for Mac](https://heard.dev/download/use-cases?format=dmg)

Includes 14 days of free Heard. No card needed.
