Get notified when Claude Code finishes or needs input

Claude Code has a built-in alert, but by default it only shows a desktop notification in iTerm2, Ghostty and Kitty. To be told in any terminal on a Mac, add two hooks to ~/.claude/settings.json: a Stop hook, which runs when Claude finishes responding, and a Notification hook matched on permission_prompt, which runs when Claude is waiting for your approval. Each hook can run osascript for a banner, afplay for a sound, or both.

If you only want the snippet, the notification hook generator builds it from a few checkboxes.

What Claude Code does before you add any hooks

Claude Code raises a notification when it finishes a task or pauses for a permission prompt and you appear to be away from the terminal. The preferredNotifChannel setting, shown in /config as Local notifications, decides how that reaches you. The default is "auto":

• in iTerm2, Ghostty and Kitty, a desktop notification;
• in Terminal.app, the bell character, and only when you have turned Terminal's audible bell off;
• in any other terminal, nothing.

To get the bell in every terminal, add this to ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

The other accepted values are "iterm2", "iterm2_with_bell", "kitty", "ghostty" and "notifications_disabled". Two terminals need extra setup before the built-in notification gets through:

• iTerm2: open Settings > Profiles > Terminal, check "Notification Center Alerts", click "Filter Alerts" and enable "Send escape sequence-generated alerts".
• tmux: add set -g allow-passthrough on to ~/.tmux.conf and run tmux source-file ~/.tmux.conf. Without it, tmux swallows the notification before the outer terminal sees it.

Hooks go further: you choose the event, the text and the sound, and they work in terminals where "auto" does nothing.

Which hook events mean finished and which mean waiting

A hook is a command Claude Code runs when a named event happens. These are the events that matter here:

Stop, no matcher

Every time Claude finishes responding, whether or not you are at the keyboard. Not when you interrupt, and not when the turn ends in an API error (that fires StopFailure).

Notification with the matcher permission_prompt

Claude needs you to approve a tool use, and the prompt has waited about six seconds. In a terminal session each keystroke restarts the wait.

Notification with the matcher idle_prompt

Claude finished responding about 60 seconds ago, you have not typed since, and no background agent is still running.

PermissionRequest, matched on a tool name such as Bash

The moment Claude Code is about to ask for permission to use a tool, with no delay.

Stop takes no matcher; one added there is silently ignored. For Notification, the matcher is the notification type. Leave it out to run the hook for every type, which also covers elicitation_dialog (an MCP server asking you for input), auth_success and several others, or join types with a pipe: "permission_prompt|idle_prompt". Matchers are case-sensitive.

Choosing between Stop and idle_prompt is choosing how much noise you want. Stop fires immediately on every turn, including the short ones you are watching. idle_prompt waits a minute and only fires if you have not come back.

The settings.json for a banner and a sound

This block shows a banner and plays a sound when Claude finishes a turn and when a permission prompt has been waiting:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Finished responding\" with title \"Claude Code\"'"
          },
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Waiting for your permission\" with title \"Claude Code\"'"
          },
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

The shape has three levels. Under hooks, each key is an event name. Its value is a list of matcher groups, each with an optional matcher and its own hooks list. Each entry in that inner list is a handler: "type": "command" and the command to run, which Claude Code passes to sh -c on macOS. Handlers that match run in parallel.

Both commands ship with macOS. osascript -e 'display notification …' shows a banner, which is silent on its own. afplay plays an audio file; ls /System/Library/Sounds lists the system sounds.

Put the block in ~/.claude/settings.json to cover every project on your Mac. A project's .claude/settings.json is the file a team commits, so teammates on other systems would inherit macOS-only commands; for one project, use .claude/settings.local.json. If the file already has a hooks key, put the Stop and Notification entries inside it. A second hooks key does not merge with the first: only the last one is used.

Three things to know about how these run:

• Hooks run alongside the built-in notification, not instead of it, so in iTerm2, Ghostty or Kitty you get both. Set "preferredNotifChannel": "notifications_disabled" to keep only the hook; hooks still run with that value.
• Claude Code waits for a hook to finish, and afplay runs for the length of the sound, a second or two. "async": true on a handler runs it in the background. Leave it off for claude -p, where an async hook still running at exit is killed.
• To have the banner come from your terminal instead of osascript, a hook can return a terminalSequence field, and Claude Code emits the notification escape sequence for you. The hooks reference has the script.

Name the project in the banner

With several sessions open, "Finished responding" does not say which one. Claude Code sets CLAUDE_PROJECT_DIR in the hook's environment to the folder the session started in, so the command can name it:

{
  "type": "command",
  "command": "osascript -e 'on run argv' -e 'display notification \"Finished in \" & (item 1 of argv) with title \"Claude Code\"' -e 'end run' \"$(basename \"$CLAUDE_PROJECT_DIR\")\""
}

The folder name reaches the script as an argument instead of being pasted into it, so a quote or an apostrophe in the name cannot break the command.

Test each layer separately

1. Run the commands by hand. Paste osascript -e 'display notification "Finished responding" with title "Claude Code"' and then afplay /System/Library/Sounds/Glass.aiff into a terminal. No banner here means the problem is in macOS, not Claude Code.
2. Check that Claude Code loaded the hooks. Type /hooks in a session and confirm they are listed under Stop and Notification. Edits to the file are normally picked up without a restart.
3. Trigger Stop. Send a short prompt, or run claude -p "Reply with the word ok". The banner and sound arrive as the reply ends.
4. Trigger permission_prompt. Ask Claude to run a command that needs approval, then keep your hands off the keyboard for more than six seconds.
5. Read the debug log. Start with claude --debug-file /tmp/claude.log and run tail -f /tmp/claude.log in another terminal to see which hooks matched and how they exited.

Why a hook runs and you still get nothing

• Script Editor is not allowed to notify. osascript banners are delivered as the built-in Script Editor app, not as your terminal. Without notification permission for Script Editor the command fails silently, and macOS does not ask. Run osascript -e 'display notification "test"' once, then open System Settings > Notifications, find Script Editor and turn on Allow Notifications.
• A Focus is on. A Focus, including Do Not Disturb, silences notifications from apps you have not allowed. Turn it off, or open System Settings > Focus, select the Focus, click Allowed Apps and allow the app that sends the banner.
• The banner was hidden or brief. System Settings > Notifications has a separate switch for notifications while mirroring or sharing the display, and Script Editor's Persistent style keeps a banner on screen until you dismiss it.
• The sound is muted. afplay is ordinary audio playback, not a notification. Focus and notification permissions do not apply to it; output volume and mute do.
• You were typing. permission_prompt needs about six seconds without a keystroke and idle_prompt about 60, so testing with your hands on the keyboard looks like a broken hook.
• The JSON did not load. Trailing commas and comments are not allowed, and with either one /hooks lists nothing from the file. python3 -m json.tool ~/.claude/settings.json prints the file if it parses and the position of the error if it does not. Two hooks keys parse without an error, but only the last is used.
• Hooks are switched off. "disableAllHooks": true in your settings turns off every hook. If /hooks says only hooks from managed settings run here, your organization has blocked user hooks.
• The failure is hidden. For Notification hooks, Claude Code ignores the exit code and stderr, so a mistyped command shows no error outside the debug log. A failing Stop hook does show a hook error notice in the transcript.
• It is the built-in notification that is missing. Check the terminal list above, and confirm that your terminal app, not Script Editor, has notification permission.

Notifications on your phone

Hooks alert the Mac you are sitting at. For a phone, Claude Code sends push notifications through Remote Control, which needs a Pro, Max, Team or Enterprise plan and does not work with API keys:

1. Install the Claude app for iOS or Android, sign in with your Claude Code account and allow notifications.
2. In Claude Code, run /config and enable Push when actions required (permission prompts and questions), Push when Claude decides (such as a long task finishing), or both.
3. Connect the session with claude --remote-control, or /remote-control inside one. Pushes are sent only while Remote Control is connected, and not while you are typing in or focused on that terminal.

The Codex CLI equivalent

Codex has two mechanisms, both set in ~/.codex/config.toml: notifications from its terminal UI, which are on by default, and a notify program that it runs for you.

notify = ["osascript", "-e", "display notification \"Codex finished a turn\" with title \"Codex\""]

[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "auto"
notification_condition = "unfocused"

• tui.notifications is true, false, or a list of event types such as the two above. notification_method is auto, osc9 or bel; auto prefers an OSC 9 desktop notification and falls back to the bell. notification_condition is unfocused (the default) or always.
• notify runs an external program, written as a list of arguments, when a turn completes. agent-turn-complete is currently its only event, so it cannot tell you about approval requests; tui.notifications can.
• Codex appends one JSON argument describing the turn. osascript ignores it, but afplay rejects a second argument, so wrap a sound in a shell: notify = ["sh", "-c", "afplay /System/Library/Sounds/Glass.aiff"].
• notify must sit above the first [section] header, or TOML reads it as part of that section. Codex ignores notify in a project's .codex/config.toml, so set it in the user file.

Codex also has a separate hooks system with Stop and PermissionRequest events, described in its hooks documentation.

When several agents are waiting at once

A notification says that something wants you. With agents running in five projects, the harder questions are which one and what it is asking. Naming the project in the banner helps, and you still have to find the right terminal to answer.

Armadai, a native macOS app that runs Claude Code and Codex in separate project workspaces on one canvas, handles this with a list instead of an alert. Its sidebar shows a status beside each session, working, idle or needs approval, across all your projects. When a session is waiting you hover it, read the request and approve it from the sidebar, and your canvas stays where you left it. The choices offered depend on the agent and the request, and a prompt that needs more context or is not supported in the sidebar is answered by opening its session.

Armadai costs $20 a month after a 7-day free trial that requires a payment method, and it has no free plan. The homepage has an interactive illustration of that sidebar.