[Claude Code] Receiving Task Completion Notifications with terminal-notifier

Overview

When you assign tasks to Claude Code and switch to other work, you often find yourself constantly checking the terminal to see if the task is finished. By combining Claude Code’s Hooks feature with macOS’s terminal-notifier, you can automatically receive desktop notifications when tasks are completed or when input is required.

In this post, we’ll walk through the setup step by step, from installing terminal-notifier to configuring Claude Code Hooks.

For installation and basic usage of Claude Code, please refer to Claude Code Basics and Usage.

Why Do You Need Notifications?

When you delegate tasks like code writing, refactoring, or test creation to Claude Code, they can take anywhere from tens of seconds to several minutes to complete. By receiving notifications during this time, you can immediately return to the terminal, allowing you to continue working efficiently without idle waiting time.

This is particularly useful in the following situations:

• When you’re working on documents while Claude is writing code
• When you’ve delegated a long refactoring task and are browsing the web
• When Claude is requesting permission approval but you’re not looking at the terminal

Installing terminal-notifier

terminal-notifier is a tool that lets you send desktop notifications from the command line on macOS. It can be easily installed via Homebrew.

brew install terminal-notifier

Verify Installation

Once installed, verify it with the following command:

terminal-notifier -title 'Test' -message 'Notifications are working correctly' -sound default

If a notification appears in the top-right corner of your macOS screen, the installation was successful.

Basic Usage

The main options for terminal-notifier are as follows:

Using the -group option causes previous notifications in the same group to be replaced by new ones, preventing the notification center from being flooded with Claude notifications.

What Are Claude Code Hooks?

Hooks are commands that automatically execute when specific events occur in Claude Code. They are configured in settings.json and allow you to connect shell commands to various events.

The key Hook events useful for notifications are:

settings.json File Location

Claude Code configuration files exist in multiple locations depending on their purpose.

Since notification settings vary by personal environment, it’s recommended to add them to the User (Global) settings (~/.claude/settings.json).

Hook Structure

Hooks are configured with the following structure:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "matching pattern",
        "hooks": [
          {
            "type": "command",
            "command": "shell command to execute"
          }
        ]
      }
    ]
  }
}

• EventName: The event that triggers the Hook (Stop, Notification, etc.)
• matcher: A pattern that filters when the Hook should execute. Setting it to "*" makes it run in all cases.
• type: The execution type. "command" runs a shell command.
• command: The shell command to execute.

Stop Hook — Task Completion Notification

This setting sends a notification when Claude finishes responding (task is complete).

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -subtitle 'Task Complete' -message 'Your requested task has been completed' -sound default -group 'claude-code'"
          }
        ]
      }
    ]
  }
}

With this setting applied, a macOS desktop notification will appear the moment any task you’ve assigned to Claude is finished.

Option details:

• -title 'Claude Code': Displays Claude Code as the title at the top of the notification.
• -subtitle 'Task Complete': Displays Task Complete as the subtitle below the title.
• -message 'Your requested task has been completed': The notification body message.
• -sound default: Plays the macOS default notification sound. You can notice it even when focused on other work.
• -group 'claude-code': Groups notifications under the same group ID. Even when running multiple tasks consecutively, notifications won’t pile up — the latest one replaces the previous.

Notification Hook — Input Awaiting Alert

This setting sends a notification when Claude is waiting for user input (permission requests, questions, etc.).

{
  "hooks": {
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -subtitle 'Input Required' -message 'Permission request or input awaiting' -sound default -group 'claude-code'"
          }
        ]
      }
    ]
  }
}

In Claude Code’s default mode (Edit mode), user permission approval is required for file modifications, command execution, and more. Without the Notification Hook, Claude might be stuck waiting for permission approval while you’re unaware and keep waiting.

With this setting applied, you’ll receive a notification the moment Claude starts waiting for input, so you can quickly return, approve, and continue the workflow.

Complete Configuration

Here is the complete ~/.claude/settings.json configuration combining Stop Hook and Notification Hook.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -subtitle 'Task Complete' -message 'Your requested task has been completed' -sound default -group 'claude-code'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -subtitle 'Input Required' -message 'Permission request or input awaiting' -sound default -group 'claude-code'"
          }
        ]
      }
    ]
  }
}

With both Hooks configured, you can receive notifications in the following workflow:

1. Assign a task to Claude and switch to other work.
2. If Claude needs permission approval → An “Input Required” notification arrives.
3. Approve the permission and go back to other work.
4. When Claude completes the task → A “Task Complete” notification arrives.

With just these two notifications, you can keep track of Claude’s status without checking the terminal.

Verifying the Configuration

You can verify that the settings have been applied correctly within Claude Code.

/hooks

Running the /hooks command will display the list of currently configured Hooks.

Alternatively, you can directly check the contents of the settings file with the following command:

cat ~/.claude/settings.json

After modifying the settings file, the changes are applied immediately without needing to restart Claude Code.

macOS Notification Permission Settings

If terminal-notifier notifications are not appearing, you need to check the macOS notification permission settings.

1. Go to System Settings > Notifications.
2. Find terminal-notifier in the app list.
3. Verify that Allow Notifications is turned on.
4. Verify that the notification type is set to Banners or Alerts.

When you run terminal-notifier for the first time, macOS will display a popup asking for notification permission. You must select Allow for notifications to appear properly.

If Do Not Disturb (Focus Mode) is enabled, notifications may not appear. If needed, add terminal-notifier to the allowed apps in your Focus Mode settings.

Conclusion

In this post, we covered how to set up notifications using terminal-notifier with Claude Code. By configuring just the Stop Hook and Notification Hook, you can stay informed of task completion and input-waiting states, allowing you to work efficiently.

Since this setup lets you assign tasks to Claude Code and focus on other work with confidence, we highly recommend applying it if you haven’t already.

Github Sponsor Buy me a coffee

Was my blog helpful? Please leave a comment at the bottom. it will be a great help to me!

App promotion

You can use the applications that are created by this blog writer Deku.
Deku created the applications with Flutter.

If you have interested, please try to download them for free.

word learning app for kids

BlaBoo

Korean TOPIK vocabulary app

TOPIK words

Japanese vocabulary app

Japanese words

Chinese HSK vocabulary app

HSK words