claude-notifications

# 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

- **Local**: Uses `terminal-notifier` for native macOS notifications when Claude needs permission, goes idle, or requires MCP input
- **Devpod**: Routes notifications from remote devpods through an SSH reverse tunnel to the local `terminal-notifier`, with OSC 9 fallback
- **Hooks**: Configures Claude Code `Notification` hooks for `permission_prompt`, `idle_prompt`, and `elicitation_dialog`

## 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

```bash
# 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:
- Installs `terminal-notifier` via brew if missing
- Copies `notify.py` to `~/.claude/scripts/`
- Creates and starts the reverse tunnel listener (`notify-listener.py`) via launchd
- Adds `RemoteForward 19876` to `~/.ssh/config` for each devpod
- Copies `notify.py` to each devpod and configures Claude Code hooks there
- Adds `set -g allow-passthrough on` to each devpod's `~/.tmux.conf`
- Configures Claude Code notification hooks in `~/.claude/settings.json`
- Sends a test notification

### 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

- **No notifications showing**: Check System Settings > Notifications for both your terminal app AND "Script Editor" — both must have notifications enabled
- **Do Not Disturb blocking**: Add "Script Editor" to Focus exceptions, or disable DND
- **Listener not running**: `launchctl list | grep claude` and `lsof -i :19876`
- **Restart listener**: `launchctl unload ~/Library/LaunchAgents/com.claude.notify-listener.plist && launchctl load ~/Library/LaunchAgents/com.claude.notify-listener.plist`
- **Listener logs**: `cat ~/.claude/logs/notify-listener.log`
- **Test locally**: `python3 ~/.claude/scripts/notify.py "test" --title "Claude Code" --sound "Glass"`
- **Test devpod tunnel**: From devpod tmux session: `python3 ~/.claude/scripts/notify.py "test" --title "Claude Code" --sound "Glass"`
- **Debug mode**: `DEBUG=1 python3 ~/.claude/scripts/notify.py "test"`