Toast Notifications - macOS Installation

This guide covers installing toast notifications for macOS using native AppleScript APIs. No additional software required!

Quick Installation

Step 1: Download and Install

Open Terminal
Download and run the installer:
```
curl -fsSL 'https://gist.githubusercontent.com/ChrisColeTech/c57539fb0e5f8b68db9c15653490c318/raw/c909ee32c529c13f218b851d39317f7af9f9b588/macos_toast_install.sh' -o ~/install_toast_macos.sh && bash ~/install_toast_macos.sh
```
The installer will:
- Detect your macOS version
- Test native notification capabilities
- Check for optional enhancers (terminal-notifier, alerter)
- Install toast function to your shell configs
- Use the best available notification method

Reload your shell configuration:

# For zsh users (default on macOS Catalina+)
source ~/.zshrc

# For bash users
source ~/.bashrc
# or
source ~/.bash_profile

Step 2: Test Installation

toast "Hello" "macOS notifications working!"

If you see a macOS notification, everything is working!

How It Works

Native AppleScript (Built-in)

Uses osascript command (always available)
No additional installations required
Basic title + message notifications

# What happens behind the scenes:
osascript -e 'display notification "message" with title "title"'

Optional Enhancers

terminal-notifier (Enhanced)

# Install for enhanced features
brew install terminal-notifier

# Provides: sounds, icons, click actions, better formatting

alerter (Advanced)

# Install for advanced features
brew install alerter

# Provides: buttons, user input, custom icons, more control

Usage Examples

Basic Notifications

toast "Build Complete"
toast "Error" "Something went wrong"
toast "Long Running Task" "Your process has finished successfully"

In Scripts

#!/bin/bash
# Build script example
npm run build
if [ $? -eq 0 ]; then
    toast "Build Success" "Project built successfully"
else
    toast "Build Failed" "Check the logs for errors"
fi

Advanced Usage (with optional tools)

# With terminal-notifier installed, you get:
# - Sound notifications
# - Better formatting
# - Click actions

# With alerter installed, you can use:
alerter -title "Advanced" -message "With buttons" -actions "OK,Cancel"

Claude Code Integration

Settings File Location

~/.claude/settings.json

Complete Hook Configuration

{
  "model": "sonnet",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"New session started - Ready to help!\""
          }
        ]
      },
      {
        "matcher": "resume",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Session resumed - Continuing where we left off\""
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Processing your request...\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Executing bash command\""
          }
        ]
      },
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Starting specialized task agent\""
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"File created successfully\""
          }
        ]
      },
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"File edited successfully\""
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"⚠️ User input needed to continue\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"✅ Task completed successfully\""
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"🤖 Subagent task finished\""
          }
        ]
      }
    ]
  }
}

Hook Types Explained

Hook Type	When It Triggers	Purpose
`SessionStart`	New session or resume	Welcome notifications
`UserPromptSubmit`	When you send a message	Confirms input received
`PreToolUse`	Before tool execution	Shows what's about to happen
`PostToolUse`	After successful tool use	Confirms completion
`Notification`	Claude needs permission or idle timeout	Attention alerts
`Stop`	Main agent finishes responding	Task completion
`SubagentStop`	Specialized agent finishes	Subtask completion

Minimal Configuration

For a simpler setup, use just the essential hooks:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Task complete\""
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command", 
            "command": "toast \"Claude Code\" \"Input needed\""
          }
        ]
      }
    ]
  }
}

Managing Hooks

Available Hook Events:

PreToolUse - Before tool execution
PostToolUse - After tool execution
Notification - For notifications
UserPromptSubmit - When user submits prompts
Stop - When sessions stop
SubagentStop - When subagents stop
PreCompact - Before context compaction
SessionStart - When sessions begin

Configuration Parameters:

type: "command" (only supported type)
command: Command to execute (bash/zsh compatible on macOS)
timeout: Optional timeout in seconds
matcher: Tool name pattern (exact, regex, or * wildcard)

Configuration Files (in order of precedence):

.claude/settings.local.json (local project settings)
.claude/settings.json (project-wide settings)
~/.claude/settings.json (user-wide settings)

Temporarily Muting Hooks: To temporarily disable specific hooks:

Comment out: Add // before the hook entry in JSON
Rename event: Change "PreToolUse" to "_PreToolUse"
Remove temporarily: Delete the hook entry

Example of commenting out a hook:

{
  "hooks": {
    // "PreToolUse": [
    //   {
    //     "matcher": "Bash",
    //     "hooks": [
    //       {
    //         "type": "command",
    //         "command": "toast \"Claude Code\" \"Executing bash command\""
    //       }
    //     ]
    //   }
    // ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Task complete\""
          }
        ]
      }
    ]
  }
}

Important: Hooks are captured at startup, so restart Claude Code after making changes.

Uninstallation

Remove macOS Integration

curl -fsSL 'https://gist.githubusercontent.com/ChrisColeTech/09c04a387154198e98cbb6bc12f820be/raw/d4c25f1a45bc525ace671bb24a1fc6bbdf6c1600/macos_toast_uninstall.sh' -o ~/uninstall_toast_macos.sh && bash ~/uninstall_toast_macos.sh

Manual Removal

Edit your shell config files (~/.zshrc, ~/.bashrc, ~/.bash_profile)
Remove the toast function block between # -- macos toast helper start -- and # -- macos toast helper end --
Reload your shell: source ~/.zshrc or restart terminal

Remove Optional Tools

# Remove optional enhancers if installed
brew uninstall terminal-notifier
brew uninstall alerter

Troubleshooting

"toast command not found"

Run source ~/.zshrc or source ~/.bashrc
Restart your terminal
Verify the function was added: grep -A 5 "macos toast helper" ~/.zshrc

"osascript not found" or permission errors

osascript should be available on all macOS systems
Check System Preferences > Security & Privacy > Privacy > Notifications
Ensure Terminal (or your terminal app) has notification permissions

Notifications not appearing

Check System Preferences > Notifications & Focus
Ensure notifications are enabled for Terminal/your terminal app
Try manually: osascript -e 'display notification "test" with title "test"'

Different shells

The installer handles multiple shell configurations:

zsh: ~/.zshrc (default on macOS 10.15+)
bash: ~/.bashrc or ~/.bash_profile
other: ~/.profile

Permission Issues

# If you get permission errors, try:
chmod +x ~/install_toast_macos.sh
chmod +x ~/uninstall_toast_macos.sh

Requirements

macOS 10.9+ (any reasonably recent version)
Terminal or any shell application
No additional software required for basic functionality

Optional Enhancements

Install terminal-notifier for better notifications:

# Via Homebrew
brew install terminal-notifier

# Via direct download
curl -L https://github.com/julienXX/terminal-notifier/releases/download/2.0.0/terminal-notifier-2.0.0.zip -o terminal-notifier.zip
unzip terminal-notifier.zip
mv terminal-notifier-2.0.0/terminal-notifier.app /Applications/

Install alerter for advanced notifications:

# Via Homebrew  
brew install alerter

# Provides interactive notifications with buttons and user input

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Terminal      │───▶│   osascript      │───▶│ macOS Notifications │
│                 │    │                  │    │                 │
│ toast "Hello"   │    │ AppleScript API  │    │ 🔔 Notification │
│                 │    │ (built-in)       │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Features Comparison

Method	Installation	Sound	Icons	Actions	Customization
osascript	✅ Built-in	❌	❌	❌	Basic
terminal-notifier	📦 Homebrew	✅	✅	✅	Good
alerter	📦 Homebrew	✅	✅	✅	Advanced

Next Steps

For other platforms: See README-Windows.md | README-WSL.md
For development: Check out the local scripts in this directory
Integration ideas: Use in CI/CD, build scripts, long-running processes, system monitoring

ChrisColeTech/README-macOS.md