claude_ghostty_notification_setup.md

Claude Code Notifications Setup for Ghostty on macOS

This guide explains how to set up desktop notifications, sound alerts, and tab indicators when Claude Code finishes responding and needs your input.

Overview

Since Ghostty doesn't support Claude Code's built-in iTerm2-specific notifications, we use a custom hook-based approach with macOS native notifications.

Setup Steps

1. Create Notification Script

Create ~/.claude/notify-on-stop.sh:

#!/bin/bash

# Send bell to the current TTY to trigger tab decoration
printf '\a' > /dev/tty

# Notify when Claude finishes a task and is waiting for input
osascript -e 'display notification "Claude has finished and needs your input" with title "Claude Code" sound name "Submarine"'

exit 0

Make it executable:

chmod +x ~/.claude/notify-on-stop.sh

2. Configure Claude Code Hooks

Add to ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/YOUR_USERNAME/.claude/notify-on-stop.sh"
          }
        ]
      }
    ]
  }
}

Note: Replace YOUR_USERNAME with your actual username, or use $HOME/.claude/notify-on-stop.sh.

3. Configure Ghostty (Optional)

Create or edit ~/.config/ghostty/config:

# Enable desktop notifications when commands finish in the background
desktop-notifications = true

# Enable shell integration (needed for notifications)
shell-integration = detect
shell-integration-features = cursor,sudo,title

# Visual bell for tab indicators
window-decoration = true

4. Grant Notification Permissions

1. Go to System Settings > Notifications
2. Find Ghostty in the list
3. Enable notifications for Ghostty

5. Restart Claude Code

Exit and restart your Claude Code session for the hooks to take effect.

What You Get

Once configured, you'll receive three types of alerts when Claude finishes and needs input:

1. ✅ macOS notification popup - System notification with message
2. ✅ Sound alert - "Submarine" sound (customizable)
3. ✅ Ghostty tab decoration - Visual indicator on the tab header

Customization

Change Notification Sound

Edit the script and replace "Submarine" with any macOS system sound:

• "Glass"
• "Ping"
• "Pop"
• "Purr"
• "Hero"
• etc.

View available sounds: System Settings > Sound > Sound Effects

Disable Sound

Remove sound name "Submarine" from the osascript command in the notification script.

Disable Tab Decoration

Remove the printf '\a' > /dev/tty line from the notification script.

Troubleshooting

No notifications appearing:

• Check macOS notification permissions for Ghostty
• Verify the hook is in ~/.claude/settings.json
• Restart Claude Code session

No sound:

• Check System Settings > Sound > Sound Effects volume
• Verify the sound name is correct (case-sensitive)

No tab decoration:

• Ensure window-decoration = true in Ghostty config
• Reload Ghostty config with Cmd+Shift+, or restart Ghostty

Script not executable:

chmod +x ~/.claude/notify-on-stop.sh

How It Works

1. Claude Code finishes a response and enters "Stop" state
2. The Stop hook triggers and runs the notification script
3. The script sends a bell character to the terminal (triggers tab decoration)
4. The script sends a macOS notification with sound
5. You're alerted via popup, sound, and visual tab indicator