Alert

OS notifications for OpenCode. Alerts you when your agent needs attention — permission requests, questions, errors — so you don't have to watch the terminal.

How It Works

The plugin watches OpenCode events and sends native terminal notifications:

• Permission needed — the agent wants to run a command that requires approval
• Question asked — the agent is waiting for your answer
• Error — something went wrong
• Cancelled — the session was aborted
• Subagent done — a delegated task completed (optional)
• Session idle — the agent stopped and is waiting for input (optional)

Notifications are suppressed when your terminal is already focused — no interruptions when you're already looking at the output.

Install

// ~/.config/opencode/opencode.jsonc
{
  "plugin": ["opencode-alert"]
}

Restart OpenCode. Works immediately with sensible defaults — no configuration needed.

Supported Terminals

The plugin auto-detects your terminal and routes notifications through the correct protocol:

Terminal	Notification	Protocol
Ghostty	✓	OSC 777
WezTerm	✓	OSC 777
iTerm2	✓	OSC 9
Kitty	✓	OSC 99
Windows Terminal	✓	PowerShell toast
rxvt-unicode	✓	OSC 777
foot	✓	OSC 777
tmux (inside a supported terminal)	✓*	Passthrough + OSC
Terminal.app	✗	—
Alacritty	✗	—
Hyper	✗	—

* tmux requires passthrough enabled:

set -g allow-passthrough on

How protocol detection works

Detection is environment-variable based (most reliable across SSH, tmux, nested shells):

1. WT_SESSION → Windows toast
2. KITTY_WINDOW_ID → OSC 99
3. TERM_PROGRAM=iTerm.app or ITERM_SESSION_ID → OSC 9
4. Everything else → OSC 777

If your terminal isn't detected or doesn't support OSC notifications, the plugin writes the escape sequence silently — no crash, no visible garbage, just no notification.

Focus suppression

When the terminal is focused, notifications are suppressed — you're already looking at the output. Focus detection works on:

• macOS — AppleScript (checks frontmost app via System Events)
• Linux (X11) — xdotool + procfs

On Wayland, focus detection is not yet supported — notifications will always send.

Set "terminal": "ghostty" (or any terminal name) in config to override auto-detection if it fails.

Configuration

A default config file is created automatically on first run at ~/.config/opencode/opencode-alert.json. Edit it to customise:

{
  "sounds": {
    "idle": "/System/Library/Sounds/Tink.aiff",
    "permission": "/System/Library/Sounds/Glass.aiff",
    "question": "/System/Library/Sounds/Glass.aiff",
    "error": "/System/Library/Sounds/Basso.aiff"
  },
  "quietHours": {
    "enabled": false,
    "start": "22:00",
    "end": "08:00"
  },
  "notifyChildSessions": false,
  "terminal": null,
  "notifyOnIdle": true,
  "suppressWhenFocused": true,
  "soundCommand": null
}

Options

Option	Type	Default	Description
sounds.idle	string	"/System/Library/Sounds/Tink.aiff"	macOS sound for idle/completed. Set to "" to disable.
sounds.permission	string	"/System/Library/Sounds/Glass.aiff"	macOS sound for permission requests.
sounds.question	string	"/System/Library/Sounds/Glass.aiff"	macOS sound for questions.
sounds.error	string	"/System/Library/Sounds/Basso.aiff"	macOS sound for errors.
soundCommand	string | null	null	Shell command to run alongside built-in sounds (any platform).
quietHours.enabled	boolean	false	Suppress all notifications during quiet hours.
quietHours.start	string	"22:00"	Quiet hours start (HH:MM).
quietHours.end	string	"08:00"	Quiet hours end (HH:MM).
notifyChildSessions	boolean	false	Notify when subagent tasks complete.
terminal	string | null	null	Override terminal detection.
notifyOnIdle	boolean	true	Notify when agent stops without requesting input.
suppressWhenFocused	boolean	true	Skip notifications when terminal is focused.

Sounds

The sounds.* options are macOS only — they run via afplay and expect a path to a .aiff file. Set any sound to "" to disable it. No-op on other platforms.

The soundCommand option runs a shell command alongside the built-in sounds on any platform. Useful for Linux/Windows or custom audio:

# Linux — play a freedesktop sound
"soundCommand": "paplay /usr/share/sounds/freedesktop/stereo/complete.oga"

# macOS — custom sound
"soundCommand": "afplay ~/Library/Sounds/Custom.aiff"

# Windows — system beep
"soundCommand": "powershell -NoProfile -Command \"[console]::beep(880,180)\""

You can also set it via environment variable: OPENCODE_ALERT_SOUND_CMD. Config file takes precedence.

Notification Behaviour

Debounce: When a specific event fires (permission, error, question), the plugin marks that session. If a generic session.idle fires within 3 seconds for the same session, the idle notification is suppressed. This prevents duplicate "completed" notifications after permission prompts.

Quiet hours: Supports overnight spans (e.g., 22:00–08:00). All notifications are suppressed during quiet hours.

tmux: OSC sequences are wrapped in DCS passthrough (\ePtmux;...\e\\) when $TMUX is set. The plugin also resolves the tmux client's real TTY to write to the correct terminal.

What's OSC 777/9/99?

OSC = Operating System Command, part of ANSI escape sequences. Terminals use these for things beyond text formatting — changing titles, colours, clipboard, and notifications.

• OSC 777 — originated in rxvt-unicode for notifications. Adopted by Ghostty and WezTerm.
• OSC 9 — iTerm2's notification protocol.
• OSC 99 — Kitty's notification protocol, more extensible with title/body parts.

Known Limitations

• Terminal.app, Alacritty, Hyper — no OSC notification support. Notifications are silently dropped.
• tmux — requires set -g allow-passthrough on in your tmux config.
• zellij / screen — not yet supported for OSC passthrough.
• Wayland (Linux) — focus detection doesn't work yet. Notifications always send, which is harmless.

License

MIT