opencode-notify

Attention notifications plugin for OpenCode.

Blinks the Zellij tab, plays a sound, and posts a macOS desktop notification when a session needs your attention (idle after work, permission request, question asked). The plugin adapts to whether your terminal window is visible and whether the Zellij tab is active, so you only get pinged when you would actually miss the event.

| Zellij tab blinking | Desktop notification | | :--------------------------------------------------: | :-----------------------------------------------------------: | | | |

Behavior

When OpenCode needs attention:

| Tab active | Ghostty visible | Action | | ---------- | --------------- | -------------------------------- | | Yes | Yes | Do nothing (user can see it) | | Yes | No | Desktop notification | | No | Yes | Blink tab + sound | | No | No | Blink tab + desktop notification |

The tab blinking stops when:

• You switch to the tab (detected via polling)
• OpenCode goes busy again (you responded)

Install

Add to your tui.json (create at ~/.config/opencode/tui.json if it doesn't exist):

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["@renjfk/opencode-notify"]
}

Prerequisites

All integrations are optional and probed independently at startup. The plugin degrades gracefully: anything missing is skipped, and a warning toast is shown so you know what was disabled.

| Dependency | Enables | Without it | | -------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- | | Zellij (zellij) + running inside a Zellij pane | Tab blinking when OpenCode needs attention | Tab blinking is skipped; desktop notifications and sound still work | | macOS + Ghostty | Window-visibility aware behavior (no spam when visible) | Ghostty is treated as "not visible"; falls back to always notifying | | terminal-notifier + macOS | Desktop notifications | Desktop notifications are skipped | | macOS (afplay) | Attention sound | Sound is skipped |

Recommended setup (full experience)

For the behavior matrix above to work end-to-end, install all of the following on macOS:

brew install zellij terminal-notifier

Use Ghostty as your terminal and run OpenCode inside a Zellij session. This gives you:

• Tab blinking so you can spot attention events at a glance across panes
• Audible cue when Ghostty is visible but the OpenCode tab is in the background
• Desktop notifications when Ghostty is hidden, so you get pinged even when you've tabbed away
• Silence when the tab is active and Ghostty is visible - the plugin stays out of your way when you can already see what's happening

If you don't use Zellij, Ghostty, or macOS, the plugin still does something useful: it falls back to desktop notifications and/or sound wherever those are available, and no-ops otherwise.

Recommended: meaningful Zellij tab names (fish shell)

By default Zellij names tabs Tab #1, Tab #2, etc. The plugin's blinking is easier to parse when each tab shows the current directory or command instead. If you use fish, drop contrib/zellij.fish into ~/.config/fish/conf.d/ to get:

• Tab renamed to the shortened $PWD on shell start and on every cd
• Tab renamed to the running command while it executes, then back to the directory when it completes
• Targeted per-tab updates using --tab-id so background tabs don't get clobbered by foreground activity

curl -L https://raw.githubusercontent.com/renjfk/opencode-notify/main/contrib/zellij.fish \
  -o ~/.config/fish/conf.d/zellij.fish

Requires Zellij 0.44.0+ (for rename-tab --tab-id) and jq.

How it works

1. On every attention event (session.idle after busy, permission.asked, question.asked), the plugin checks:
   • Is the Zellij tab hosting OpenCode active?
   • Is a Ghostty window visible on screen?
2. If the tab is inactive, the plugin renames it to blink between ● and ○ prefixes until the tab becomes active again or the session goes busy.
3. If Ghostty is not visible, a terminal-notifier message is posted with the tab name as the title and the session title as the subtitle.
4. If Ghostty is visible but the tab is inactive, only an audible cue (Blow system sound) is played - no desktop notification.

Notifications are debounced to 2 seconds to avoid duplicates.

Contributing

opencode-notify is open to contributions and ideas!

Issue conventions

Format: type: brief description

• feat: new features or functionality
• fix: bug fixes
• enhance: improvements to existing features
• chore: maintenance tasks, dependencies, cleanup
• docs: documentation updates
• build: build system, CI/CD changes

Development

npm run check        # lint + fmt
npm run lint         # oxlint
npm run fmt          # oxfmt --check
npm run fmt:fix      # oxfmt --write

Release process

Manual releases via opencode; see RELEASE_PROCESS.md.

License

This project is licensed under the MIT License.