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 INLINECODE5

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

CODEBLOCK0

Run from the skill's directory: INLINECODE11

The script handles:

• - Installs terminal-notifier via brew if missing
• Copies notify.py to INLINECODE14
• 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 INLINECODE20
• Configures Claude Code notification hooks in INLINECODE21
• Sends a test notification

3. Remind user of manual steps

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

1. 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

CODEBLOCK1

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 INLINECODE23
• Restart listener: INLINECODE24
• Listener logs: INLINECODE25
• Test locally: INLINECODE26
• Test devpod tunnel: From devpod tmux session: INLINECODE27
• Debug mode: INLINECODE28