Claude Code Notifications Setup

---

name: claude-notifications

description: "Set up native macOS notifications for Claude Code on local and devpod/remote environments. Use when the user asks to 'setup notifications', 'configure devpod notifications', 'get notified when Claude needs attention', 'setup claude alerts', or 'install notification hooks'. Handles local terminal-notifier, SSH reverse tunnel for devpods, launchd listener, tmux passthrough, and Claude Code hook configuration."

---

# Claude Code Notifications Setup

Set up native macOS notifications for Claude Code — works both locally and on remote devpods via SSH reverse tunnel. Get alerts with sound whenever Claude needs permission, is waiting for input, or requires MCP interaction.

What It Does

Platform

**macOS only.** The setup script will exit with a clear error if run on Linux/devpod. It uses `brew`, `launchctl`, and `terminal-notifier` — all macOS-only. The script SSHs into devpods to configure them remotely, so devpod setup is also done from your Mac.

Important: Run on Local Mac Only

**Always confirm the user is running this on their local Mac, NOT on a devpod.** The entire setup — including devpod configuration — is done from the local machine via SSH. The script SSHs into devpods to configure them remotely. If the user is on a devpod, ask them to switch to their local Mac terminal first.

Setup Workflow

1. Ask for devpod SSH hosts

Ask the user which devpod(s) to configure. Example hosts: `username.devpod-ind`, `username-web.devpod-ind`. If local-only setup, skip devpod args.

2. Run the setup script

# Local only
python3 scripts/setup_notifications.py

# Local + devpods
python3 scripts/setup_notifications.py --devpod <host1> --devpod <host2>

Run from the skill's directory: `~/.claude/skills/claude-notifications/`

The script handles:

3. Remind user of manual steps

After the script completes, **always** tell the user these required manual steps:

1. **Enable notifications for your terminal** in System Settings > Notifications > [Warp / iTerm / Terminal]. Ensure "Allow Notifications" is ON and alert style is "Alerts" or "Banners".

2. **Enable notifications for Script Editor** in System Settings > Notifications > Script Editor (terminal-notifier routes through it).

3. **Turn off Do Not Disturb** or add "Script Editor" and your terminal app to Focus exceptions.

4. **Reconnect SSH sessions** to devpods — existing sessions don't have the reverse tunnel. New sessions get it automatically.

Architecture

┌─────────────────────────────────────────────────┐
│ Devpod (remote)                                 │
│                                                 │
│  Claude Code hook → notify.py                    │
│    → curl localhost:19876 (reverse tunnel)       │
│    → fallback: OSC 9 escape sequence            │
└──────────────────┬──────────────────────────────┘
                   │ SSH RemoteForward 19876
┌──────────────────▼──────────────────────────────┐
│ Local Mac                                       │
│                                                 │
│  notify-listener.py (launchd, port 19876)       │
│    → terminal-notifier → macOS Notification Center│
└─────────────────────────────────────────────────┘

Troubleshooting