opencode-console-notify

Native desktop toast notifications for OpenCode — know when the agent finishes, errors, or needs you, without watching the terminal. Windows notifies via WinRT toasts, Linux via notify-send (needs libnotify-bin).

The config TUI is identical on both platforms: fullscreen with keyboard (j/k/arrows, Enter, Space) plus mouse (hover highlights, click selects/activates, wheel scrolls). On Linux it needs a real console and an xterm-compatible terminal for the mouse; pipes and scripts run the line mode everywhere.

What it notifies

| Event | Meaning | | --- | --- | | session.idle | Task finished, waiting for input | | session.error | Something went wrong | | permission.asked | Permission needed to continue | | question.asked | OpenCode asked a question |

Child (sub-agent) sessions are filtered for session.idle / session.error so runs don't spam notifications. Blocking events (permission.asked, question.asked) always notify, even from children, because they stop all progress until answered.

Requirements

• OpenCode
• Windows 10 or 11, or Linux (any ANSI console; mouse needs an xterm-compatible terminal)
• notify-send (libnotify-bin) on Linux for toasts
• No administrator rights needed (Windows registers per-user in HKCU; Linux needs no registration)

Install

Four independent paths — pick any one. Each path installs the plugin itself; Windows also registers the notification identity (AUMID), which Linux does not need.

PowerShell (Windows, one line)

irm https://raw.githubusercontent.com/IbatoLionDev/opencode-console-notify/main/install.ps1 | iex

Shell (Linux, one line)

curl -fsSL https://raw.githubusercontent.com/IbatoLionDev/opencode-console-notify/main/install.sh | sh

Go CLI binary

1. Download opencode-notify.exe (Windows) or opencode-notify-linux (Linux) from the GitHub Releases page.
2. Run:

opencode-notify.exe install

./opencode-notify-linux install

npm / npx (no Go needed)

Zero-dependency, Windows and Linux:

npm i -g opencode-console-notify
opencode-console-notify install

Or without installing anything:

npx opencode-console-notify install
npx opencode-console-notify doctor
npx opencode-console-notify test
npx opencode-console-notify uninstall

The published package works with any npm-compatible manager:

pnpm add -g opencode-console-notify
opencode-console-notify install

yarn global add opencode-console-notify
opencode-console-notify install

bun add -g opencode-console-notify
opencode-console-notify install

One-off runs without installing:

pnpm dlx opencode-console-notify install
bunx opencode-console-notify install

Check which version you are running (also as --version or -V):

opencode-console-notify version

Upgrade

One command per path:

opencode-console-notify upgrade

Checks the npm registry for a newer release. When the installed copy is already up to date it prints both versions and changes nothing; otherwise it installs opencode-console-notify@latest globally and re-runs install from the fresh copy. --plugins-dir DIR (before or after the command) is forwarded to that reinstall.

.\install.ps1 -Upgrade

Skips the local-checkout file and always downloads fresh bytes from GitHub, then installs exactly like a fresh install (same atomic write, AUMID registration, and hash output). -Uninstall wins when both are set.

./install.sh --upgrade

Same as above for Linux (no identity step there).

opencode-notify.exe upgrade

Reinstalls the plugin from the copy embedded in the binary and runs doctor to verify. The embedded copy is pinned at build time, so this refreshes the install but cannot fetch a newer binary — newer opencode-notify.exe builds come from the GitHub Releases page.

Config

opencode-notify.exe config
# or: opencode-console-notify config

Opens an interactive TUI (English/Spanish) with language, update, info, alerts, and customs. On a real console it renders fullscreen with keyboard navigation (j/k/arrows, Enter, Space) plus mouse (hover highlights, click selects/activates, wheel scrolls) — identical on Windows and Linux; on pipes and scripts the line mode runs instead. Language applies to the TUI and the default notification texts. Alerts lists the four default events with their triggers; Space toggles each one and the plugin honors it on the next event. Every view prints its keys in a visible footer. For scripts:

opencode-console-notify config --lang es
opencode-console-notify config --toggle sessionIdle=off
opencode-console-notify config --list-alerts
opencode-console-notify config --list-events
opencode-console-notify config --list-customs
opencode-console-notify config --info

Custom notifications bind your own title and body to any of the 48 subscribable OpenCode events (see config --list-events; noisy families are flagged). Manage them in the TUI customs panel (list, create, edit, delete, toggle) — they show in alerts tagged as custom and toggle like the defaults, and the plugin fires them with the same child-session rule.

Settings persist in console-notify.config.json next to the plugin file; without it everything stays as in v1 (all alerts on, English).

Dev runs (isolated sandbox)

npm run dev -- config
npm run dev:go -- config --list-alerts

Runs the repo copy (JS or Go) against .dev-sandbox/ instead of the real plugins directory or any global install: settings persist between dev runs but your installed copy is never touched. Pass --plugins-dir explicitly to use another directory. doctor and test are intentionally left out — try toasts from a real install.

Then

Restart OpenCode.

Options shared by all paths

Custom plugins directory (every path accepts it; the CLI flags work with install, uninstall, doctor, and test):

.\install.ps1 -PluginsDir "C:\path\to\plugins"
opencode-notify.exe install --plugins-dir "C:\path\to\plugins"
opencode-console-notify install --plugins-dir "C:\path\to\plugins"

Run from a local clone, .\install.ps1 uses the checkout's plugin\ file and downloads nothing.

Build the CLI from source (optional)

Requires Go 1.27+:

go build -o opencode-notify.exe ./cmd/opencode-notify

Verify

opencode-notify.exe doctor
# or: opencode-console-notify doctor

(or re-run the PowerShell script — all three check the same end state: plugin file present and AUMID registered).

doctor also prints an automatic update notice when a newer release exists (the check is best-effort: offline machines just skip it).

Send a test toast:

opencode-notify.exe test
# or: opencode-console-notify test

Uninstall

opencode-notify.exe uninstall
# or: opencode-console-notify uninstall

or re-run the PowerShell script with -Uninstall.

Troubleshooting

• No notifications — run doctor (opencode-notify.exe doctor on Windows, ./opencode-notify-linux doctor or opencode-console-notify doctor on Linux); it reports exactly what is missing. On Linux a missing notify-send (libnotify-bin) means toasts are skipped silently.
• Manual identity check (Windows) — the identity lives at HKCU\Software\Classes\AppUserModelId\OpenCode.Notifier (DisplayName=OpenCode). Both Windows installers manage it; you should never need to touch it by hand. Linux needs no registration.
• Focus Assist / Do Not Disturb — Windows silently suppresses toasts while these are enabled. Check Settings > System > Notifications.
• Debug log — the plugin writes debug info to %TEMP%\opencode-console-notify.debug.log on Windows, $TMPDIR/opencode-console-notify.debug.log (else /tmp) on Linux.

Scope / roadmap

Supported today: Windows 10/11 and Linux. Same plugin events, settings and config TUI on both (fullscreen included); Windows notifies via WinRT toasts with the per-user AUMID identity, Linux via notify-send with the app name. The mouse needs an xterm-compatible terminal; dumb terminals keep full keyboard support.

Not supported yet: macOS (needs console_darwin.go, an osascript/native backend and a no-op identity like Linux) and rich notification-center actions (buttons, images). Contributions welcome.

License

MIT — see LICENSE.