Blog · August 14, 2026 · 6 min read · by Vilva Athiban P B

Claude Code Notification Scripts: Copy-Paste Recipes for Every Platform

If you searched for a Claude Code finished notification script, you probably don't want another explanation of why notifications matter. You want something to paste into a config file so your machine makes a noise when Claude Code is done — or needs you. This post is exactly that: working recipes for macOS, Linux, and Windows, organized by what you want to happen.

Every script here plugs into Claude Code's hooks system — two events in particular. Stop fires when Claude finishes responding, and Notification fires when it needs your permission or input. Wire a command to those two events and you never have to watch the terminal again. (If you want the full background on how hooks work, our hooks guide covers the whole system; this post sticks to the notification recipes.)

Where these scripts go

All recipes below live in ~/.claude/settings.json (for every project) or .claude/settings.json inside one project. The structure is the same every time — only the command string changes:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "YOUR-COMMAND-HERE" }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "YOUR-COMMAND-HERE" }
        ]
      }
    ]
  }
}

Use the same command for both events, or different ones — a soft sound for "done", a loud one for "waiting on you" is a popular split. After editing, restart your Claude Code session so the hooks load.

macOS: sound only

The simplest possible script — play one of the built-in system sounds. No dependencies, works on every Mac:

afplay /System/Library/Sounds/Glass.aiff

Browse /System/Library/Sounds/ for alternatives — Funk, Ping, Sosumi. Use a different sound for the Notification hook so your ears learn the difference between "finished" and "needs input".

macOS: banner notification

For a real notification-center banner, use osascript (built in) — or terminal-notifier if you have Homebrew:

# Built-in (no install):
osascript -e 'display notification "Claude Code is done" with title "Claude Code" sound name "Glass"'

# With terminal-notifier (brew install terminal-notifier):
terminal-notifier -title "Claude Code" -message "Done - come back" -sound Glass -activate com.apple.Terminal

The -activate flag is the nice touch: clicking the banner brings your terminal to the front. Swap the bundle id if you use iTerm2 (com.googlecode.iterm2) or another terminal. One macOS gotcha: the first time a banner fires, macOS may ask you to allow notifications for the script runner — approve it once and you're set.

Linux: notify-send and a sound

On most Linux desktops, notify-send posts a desktop notification and paplay handles sound:

# Banner:
notify-send "Claude Code" "Finished - come back"

# Banner plus sound:
notify-send "Claude Code" "Finished" && paplay /usr/share/sounds/freedesktop/stereo/complete.oga

# Terminal bell fallback (works even over SSH):
printf "\a"

The terminal bell deserves more respect than it gets: most terminal apps can turn the bell into a visual flash or system notification, and it survives SSH sessions where desktop notifications can't reach you.

Windows: a toast from PowerShell

On Windows (or WSL calling out to PowerShell), a system sound is one line, and a proper toast is a few more:

# Simple sound:
powershell.exe -c "[System.Media.SystemSounds]::Exclamation.Play()"

# Toast notification (install once: Install-Module BurntToast):
powershell.exe -c "New-BurntToastNotification -Text 'Claude Code', 'Done - come back'"

From WSL, powershell.exe is reachable from your Linux shell, so the exact same hook config works inside your distro.

Phone push: when you leave the desk

Sounds and banners only help while you're at the machine. For long tasks — the kind where you make coffee or switch rooms — push the notification to your phone with a free ntfy.sh topic:

curl -s -d "Claude Code is done" ntfy.sh/your-secret-topic-name

Install the ntfy app on your phone, subscribe to the same topic name, and every hook fire becomes a phone push. Pick an unguessable topic name — anyone who knows it can see your pings.

The catch with all of these

One honest caveat before you wire up six hooks: scripts only cover the tool you configured, on the machine you configured, in the state you remembered to set up. If you also run Codex CLI or Cursor, each needs its own separate setup — different config files, different event names, different quirks. The scripts also can't tell you which session finished when you run several agents in parallel, and a typo in a JSON file fails silently: no error, just no ding.

Script it or install it — either way, the goal is the same workflow our notifications guide keeps coming back to: kick off the task, walk away with your attention intact, and let the machine tell you when you're actually needed.

Keep reading

Desk Exercises for Programmers: 15 Moves to Do While Your AI Agent Codes

7 min read

Exercise While Coding: Turn Claude Code Wait Time Into Micro-Workouts

7 min read

Claude Code Notch Notifications on Mac: See When Claude Is Done Without Watching the Terminal

7 min read

Claude Code Tips and Tricks: 12 Ways to Use Claude Code Effectively

8 min read

Claude Code Multiple Sessions: How to Run Agents in Parallel Without Losing Track

6 min read

A Claude Code Workflow That Doesn't Involve Watching the Terminal

5 min read

Claude Code Hooks: A Practical Guide to Automating Your Agent Workflow

7 min read

Claude Code Auto Mode: Fewer Permission Prompts Without Living Dangerously

7 min read

Claude Code Subagents: How to Delegate Work to Specialized Agents

7 min read

Claude Code Context Management: Treat the Context Window Like a Budget

6 min read

Per-Subagent Model Selection: Route the Grunt Work Down, Keep the Judgment Up Top

7 min read

Skills and Plugins: How to Teach Claude Code Your Way of Working

7 min read

Claude Code Background Tasks: Run Long Commands Without Blocking Your Session

6 min read

Codex CLI Notifications: How to Get a Ding When Codex Is Done or Needs Input

7 min read

Cursor Notification When Done: Every Way to Get Notified When Cursor Finishes

6 min read

Claude Code Notifications: How to Get Notified When Claude Code Finishes or Needs Your Input

6 min read

Want to Be Notified When Claude Responds? How Claude Notifications Work on Web, Desktop, and Mobile

5 min read

Get a Ding the Moment Codex Needs Your Response

6 min read

Get Notified the Moment Claude Code Is Waiting for Your Input

6 min read

“Notifications Are Turned Off for Claude” — Here Is the Fix

6 min read

Codex Sound When Done: Make Codex CLI Play a Sound When It Finishes

6 min read

terminal-notifier + Claude Code: Native macOS Alerts When Your Agent Finishes

6 min read

Gemini CLI Notifications: How to Get a Sound or Alert When Gemini Finishes

6 min read

Get Claude Code Notifications on Your Phone

6 min read

Claude Code Remote Control, Explained

7 min read

preferredNotifChannel: Claude Code's Built-In Notification Setting

6 min read

Claude Code Notifications in tmux and Over SSH

7 min read

Claude Code Effort Levels: Why Your Setting Keeps Getting Ignored

8 min read

Codex vs Claude Code Notifications: How Each One Tells You It Is Done

8 min read

Claude Code Notifications Not Working: A Diagnostic Checklist

10 min read

Claude Code Notifications Inside Your Editor's Terminal

7 min read

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Explained

7 min read

CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP Explained

8 min read

Cursor Alerts Explained: Every Alert Cursor Raises, and How to Control Them

7 min read

Claude Code Environment Variables: The Groups That Actually Matter

10 min read

Claude Code Notifications on WSL and Windows

9 min read

Claude Code Checkpoints and /rewind

8 min read

Claude Remote Control: How It Works, Turning It Off, and Auto Mode

7 min read

Claude Code /loop: Poll a Deploy, Babysit a PR, and Get Told When It's Done

8 min read

Setting Up NotchFit With OpenAI Codex CLI: Hooks, $notchfit-plan, and the Daily Flow

7 min read

Claude Mods Explained: What the New Plugin Layer Can Do, and How to Turn On 'You Should Know'

9 min read

NotchFit vs Mac Break Reminder Apps: A Clock or a Signal From Your Coding Agent?

8 min read

Claude Code Headless Mode: Running claude -p in Scripts and CI, and the Three Signals That It Finished

10 min read

Building a Movement Habit at a Desk: Use the Agent Run as the Cue, One Set as the Unit, and Streaks Carefully

8 min read

Claude Code MCP Servers Explained: Adding Servers, Choosing a Scope, Handling Secrets, and Why Long Tool Calls Go to the Background

10 min read

/notchfit:plan Explained: How Claude Code or Codex Writes a Weekly Workout Plan the Notch Can Actually Run

8 min read

Claude Code Spinner Verbs Explained: What “Pondering” and “Brewing” Mean, How to Change Them, and Why You Should Stop Watching the Spinner

7 min read

Why NotchFit's Done and Permission Alerts Wait Until Your Set Ends, When That Costs You, and How to Turn the Workout Off

7 min read

How to Resume a Claude Code Session: --continue vs --resume, Naming Sessions, the Session Picker, Branching, and What Comes Back

9 min read

NotchFit on a Mac Without a Notch: How Pill Mode Works on Mac mini, iMac, Mac Studio and a MacBook With the Lid Closed

6 min read

How to Run a Claude Code Session in the Background: /background, claude --bg, Agent View, and Getting Back to It

9 min read

What a Notch App Can See: NotchFit's Local-First Design, What the Claude Code and Codex Hooks Send, and What Stays on Your Mac

7 min read

Why Codex CLI Asks for Permission Every Time, and How to Tune the Sandbox and Approval Policy Without Going Full Access

8 min read

What to Do While Claude Code or Codex Works: A Simple Protocol for the Two-to-Twenty-Minute Gap in Every Agent Run

7 min read

Is It Possible to Get a Notification When Claude Code or Codex Hits a Reset? Yes for Claude Code: the quota_auto_resume Hooks, Explained

8 min read

What a MacBook Notch App Can Actually Do: The Five Kinds of Notch Utility, Their Trade-offs, and Where NotchFit Fits

7 min read