setup

Agent Notifications Setup

Interactive wizard to configure the agent-notifications plugin. The config file lives at ~/.claude/agent-notifications/config.json. Present each step in sequence, asking one question at a time.

Step 1: Check Current State

Read ~/.claude/agent-notifications/config.json if it exists.

• Config exists: Show current settings in a concise table and ask what to change. Offer to reconfigure from scratch or adjust individual settings.
• No config: Inform the user a fresh config will be created.

Step 2: Detect Terminal

Run the following to identify the terminal environment:

echo "TERM_PROGRAM=$TERM_PROGRAM KITTY_WINDOW_ID=$KITTY_WINDOW_ID WEZTERM_EXECUTABLE=$WEZTERM_EXECUTABLE ITERM_SESSION_ID=$ITERM_SESSION_ID VSCODE_GIT_IPC_HANDLE=$VSCODE_GIT_IPC_HANDLE"

Terminal detection mapping:

Environment Variable / Value	Terminal	Notification Method
TERM_PROGRAM=ghostty	Ghostty	OSC 777 (native)
WEZTERM_EXECUTABLE set	WezTerm	OSC 777 (native)
TERM_PROGRAM=iTerm.app or ITERM_SESSION_ID set	iTerm2	OSC 9 (native)
KITTY_WINDOW_ID set	Kitty	OSC 99 (native)
TERM_PROGRAM=vscode or VSCODE_GIT_IPC_HANDLE set	VS Code	terminal-notifier (fallback)
TERM_PROGRAM=Apple_Terminal	Terminal.app	terminal-notifier (fallback)
TERM_PROGRAM=WarpTerminal	Warp	terminal-notifier (fallback)
TERM_PROGRAM=Hyper	Hyper	terminal-notifier (fallback)

Report the detected terminal and whether it supports native OSC notifications. Native OSC terminals work across all tabs and windows without extra dependencies.

For fallback terminals, check if terminal-notifier is installed:

which terminal-notifier

If missing, suggest brew install terminal-notifier.

Step 3: Configure Bundle ID (Fallback Terminals Only)

Skip this step for native OSC terminals — bundle ID is irrelevant for them.

For fallback terminals, the bundle ID controls which app activates when clicking a notification. Auto-detect it:

osascript -e 'id of app "AppName"'

Common bundle IDs:

Terminal	Bundle ID
Ghostty	com.mitchellh.ghostty
iTerm2	com.googlecode.iterm2
Terminal.app	com.apple.Terminal
VS Code	com.microsoft.VSCode
Warp	dev.warp.Warp-Stable
Hyper	co.zeit.hyper

For other terminals (e.g., Cursor, Alacritty), detect the bundle ID with osascript -e 'id of app "AppName"'.

Step 4: Notification Preferences

Ask the user about each setting one at a time, offering sensible defaults:

1. Notification types — Enable/disable individual events. All enabled by default:

   • question — Claude asks a question
   • planReady — Claude finishes a plan
   • permission — Claude needs tool permission
   • taskCompleted — Claude finishes responding

2. Message detail level — "full" (context + branch + project) or "minimal" (event + project only). Default: "full".

3. Sounds (fallback terminals only) — macOS system sounds used by terminal-notifier. Default: Blow for most events, Glass for taskCompleted. List available sounds with ls /System/Library/Sounds/ | sed 's/.aiff//'. Preview with afplay /System/Library/Sounds/Glass.aiff.

4. Frontmost detection (fallback terminals only) — When skipFrontmostDetection is false (default), notifications are suppressed if the terminal app is focused. Ask whether to always notify regardless.

Skip settings that don't apply to the detected terminal (e.g., sounds and frontmost detection for OSC terminal users).

Step 5: Write Config

Assemble the final config JSON:

{
  "sounds": {
    "question": "Blow",
    "planReady": "Blow",
    "permission": "Blow",
    "taskCompleted": "Glass"
  },
  "notifications": {
    "question": true,
    "planReady": true,
    "permission": true,
    "taskCompleted": true
  },
  "terminal": {
    "skipFrontmostDetection": false,
    "bundleId": "<detected>"
  },
  "messageDetail": "full"
}

Show the assembled config to the user for confirmation before writing. Create the directory if needed (~/.claude/agent-notifications/), then write to ~/.claude/agent-notifications/config.json.

After writing, confirm success and note that the plugin picks up the new config on the next notification — no restart needed.