feat: add OPENCODE_NO_NOTIFY env var to suppress notifications

When opencode is invoked programmatically from an external harness
(build orchestrators, CI pipelines, automation tools), desktop
notifications are unhelpful and disruptive. Example: worktrunk
(wt step commit) calls opencode run to generate commit messages —
these sessions send "Ready for review" notifications that are pure
noise since no human is waiting for them.

Setting OPENCODE_NO_NOTIFY=1 or OPENCODE_NO_NOTIFY=true disables
all notification types by returning an empty plugin at init time.
This is opt-in — existing behavior is unchanged when the env var
is not set.

Author: christophkroeppl

README.md

@@ -105,6 +105,16 @@ Configuration keys:
 - `sounds`: per-event sounds (`idle`, `error`, `permission`, optional `question`).
 - `quietHours`: scheduled suppression window.
 
+### Disabling notifications with `OPENCODE_NO_NOTIFY`
+
+When opencode is invoked programmatically from an external harness (build orchestrators, CI pipelines, automation scripts), desktop notifications are unhelpful and disruptive. Set the `OPENCODE_NO_NOTIFY` environment variable to suppress all notification types:
+
+```bash
+OPENCODE_NO_NOTIFY=1 opencode run "your task"
+```
+
+When set to `"1"` or `"true"`, the entire plugin is disabled at initialization — no event listeners are registered, no notifications are sent. This is opt-in; existing behavior is unchanged when the env var is not set.
+
 **Available macOS sounds:** Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink
 
 ## FAQ
@@ -122,7 +132,7 @@ No. Smart defaults prevent noise:
 
 ### Can I disable it temporarily?
 
-This plugin does not currently expose an `enabled` config flag. To disable notifications, remove/uninstall the plugin (for example: `ocx remove kdco/notify`) and add it back when needed.
+Set the `OPENCODE_NO_NOTIFY=1` environment variable to suppress all notifications for a session. See [Configuration](#disabling-notifications-with-opencode_no_notify) for details. To uninstall entirely, run `ocx remove kdco/notify` and add it back when needed.
 
 ## Supported Terminals
 

src/notify.ts

@@ -486,6 +486,11 @@ async function handleQuestionAsked(
 // ==========================================
 
 export const NotifyPlugin: Plugin = async (ctx) => {
+	// When invoked programmatically from a harness, suppress all notifications
+	if (process.env.OPENCODE_NO_NOTIFY === "1" || process.env.OPENCODE_NO_NOTIFY === "true") {
+		return {}
+	}
+
 	const { client } = ctx
 
 	// Load config once at startup