Add TUI notifications and attention sounds (disabled by default) (#26980)

packages/opencode/package.json

@@ -108,6 +108,7 @@
     "@opencode-ai/plugin": "workspace:*",
     "@opencode-ai/script": "workspace:*",
     "@opencode-ai/sdk": "workspace:*",
+    "@opencode-ai/ui": "workspace:*",
     "@openrouter/ai-sdk-provider": "2.8.1",
     "@opentelemetry/api": "1.9.0",
     "@opentelemetry/context-async-hooks": "2.6.1",

packages/opencode/specs/tui-plugins.md

@@ -29,6 +29,16 @@ Example:
   "plugin": ["@acme/opencode-plugin@1.2.3", ["./plugins/demo.tsx", { "label": "demo" }]],
   "plugin_enabled": {
     "acme.demo": false
+  },
+  "attention": {
+    "enabled": true,
+    "notifications": true,
+    "sound": true,
+    "volume": 0.4,
+    "sound_pack": "opencode.default",
+    "sounds": {
+      "error": "/Users/me/sounds/error.mp3"
+    }
   }
 }
 ```
@@ -45,6 +55,11 @@ Example:
 - Internal plugins can declare `enabled: false` to be registered but inactive by default; `plugin_enabled` and runtime KV can still enable them by id.
 - `plugin_enabled` is merged across config layers.
 - Runtime enable/disable state is also stored in KV under `plugin_enabled`; that KV state overrides config on startup.
+- `attention.enabled` defaults to `false`; when `false`, it disables all `api.attention.notify(...)` delivery.
+- `attention.notifications` and `attention.sound` independently control terminal-mediated desktop notifications and built-in sounds.
+- `attention.volume` sets the default built-in sound volume from `0` to `1`.
+- `attention.sound_pack` selects the initial semantic sound pack. Persisted runtime selection in KV can override it.
+- `attention.sounds` overrides individual semantic sound slots such as `error`, `done`, or `subagent_done`.
 - `leader_timeout` is a top-level TUI setting.
 - `keybinds` is a flat object keyed by command id; values are key binding values (`false`, `"none"`, a key string/object, a binding object, or an array of key strings/objects/binding objects).
 - `keybinds.leader` sets the key used by `<leader>` shortcuts.
@@ -212,6 +227,7 @@ That is what makes local config-scoped plugins able to import `@opencode-ai/plug
 Top-level API groups exposed to `tui(api, options, meta)`:
 
 - `api.app.version`
+- `api.attention.notify(input)`
 - `api.keys.formatSequence(parts)`, `formatBindings(bindings)`
 - `api.keymap`
 - `api.route.register(routes)` / `api.route.navigate(name, params?)` / `api.route.current`
@@ -246,6 +262,24 @@ Top-level API groups exposed to `tui(api, options, meta)`:
 - `formatBindings(bindings)` formats binding lists and returns `undefined` when there is nothing to show.
 - For generic config-to-bindings helpers, import `createBindingLookup` from `@opencode-ai/plugin/tui`.
 
+### Attention
+
+- `api.attention.notify({ title?, message, notification?, sound? })` requests user attention while keeping terminal focus, notifications, and audio owned by the host.
+- `message` is required; `title` defaults to `"opencode"`; `notification` defaults to enabled with `when: "blurred"`; `sound` defaults to enabled with `when: "always"`.
+- `when: "always"` requests delivery regardless of terminal focus state.
+- `when: "focused"` only requests delivery after the terminal is known focused; `when: "blurred"` only requests delivery after the terminal is known blurred.
+- Example: `notification: { when: "blurred" }, sound: { name: "question", when: "always" }` plays sound while focused but only triggers system notifications when blurred.
+- Semantic sound names are `"default"`, `"question"`, `"permission"`, `"error"`, `"done"`, and `"subagent_done"`.
+- `sound: true` plays the `"default"` sound; `sound: { name: "question" }` plays a named semantic sound.
+- `sound: { volume }` overrides volume for that call; `sound: false` disables sound for that call; `notification: false` disables system notification for that call.
+- `api.attention.soundboard.registerPack({ id, name?, sounds })` registers a sound pack and returns a disposer. Relative paths resolve from the plugin root and are cleaned up on plugin deactivation.
+- `api.attention.soundboard.activate(id, { persist })` selects the active pack. `persist: true` writes the selected pack id to TUI KV state, not `tui.json`.
+- `api.attention.soundboard.current()` and `list()` expose the active/registered packs for plugin UX.
+- Config `attention.sounds` overrides active-pack sounds by slot. Failed loads fall back to the active pack and then `opencode.default`.
+- The host strips ANSI/control characters and collapses newlines before sending text to the terminal notification API.
+- Terminal and OS settings decide whether a requested notification is visibly displayed.
+- Prefer privacy-safe messages such as `"A question needs your input"`; avoid full commands, paths, prompts, errors, secrets, or file contents unless the plugin intentionally exposes them.
+
 ### Routes
 
 - Reserved route names: `home` and `session`.

packages/opencode/specs/v2/notifications.md

@@ -0,0 +1,13 @@
+# TUI Notifications Default
+
+Problem:
+
+- v1 defaults `attention.enabled` to `false`
+- users can opt in with `attention.enabled = true`
+- v2 should make core TUI notifications a default behavior
+
+## v2 Target
+
+Flip `attention.enabled` to `true` by default in v2.
+
+Keep `attention.enabled = false` as the explicit opt-out.

packages/opencode/src/audio.d.ts

@@ -3,6 +3,11 @@ declare module "*.wav" {
   export default file
 }
 
+declare module "*.mp3" {
+  const file: string
+  export default file
+}
+
 declare module "*.wasm" {
   const file: string
   export default file

packages/opencode/src/cli/cmd/tui/app.tsx

@@ -2,6 +2,7 @@ import { render, TimeToFirstDraw, useRenderer, useTerminalDimensions } from "@op
 import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"
 import * as Clipboard from "@tui/util/clipboard"
 import * as Selection from "@tui/util/selection"
+import * as TuiAudio from "@tui/util/audio"
 import { createCliRenderer, MouseButton, type CliRendererConfig } from "@opentui/core"
 import { RouteProvider, useRoute } from "@tui/context/route"
 import {
@@ -63,6 +64,7 @@ import { TuiConfig } from "@/cli/cmd/tui/config/tui"
 import { TuiPluginRuntime } from "@/cli/cmd/tui/plugin/runtime"
 import { createTuiApi } from "@/cli/cmd/tui/plugin/api"
 import type { RouteMap } from "@/cli/cmd/tui/plugin/api"
+import { createTuiAttention } from "@/cli/cmd/tui/attention"
 import { FormatError, FormatUnknownError } from "@/cli/error"
 import { CommandPaletteProvider, useCommandPalette } from "./context/command-palette"
 import { OpencodeKeymapProvider, registerOpencodeKeymap, useBindings, useOpencodeKeymap } from "./keymap"
@@ -176,10 +178,10 @@ export function tui(input: {
       unguard?.()
       resolve()
     }
-
     const onBeforeExit = async () => {
       offKeymap()
       await TuiPluginRuntime.dispose()
+      TuiAudio.dispose()
     }
 
     const renderer = await createCliRenderer(rendererConfig(input.config))
@@ -283,6 +285,7 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
     routeRev()
     return routes.get(name)?.at(-1)?.render
   }
+  const attention = createTuiAttention({ renderer, config: tuiConfig, kv })
 
   const api = createTuiApi({
     tuiConfig,
@@ -298,11 +301,13 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
     theme: themeState,
     toast,
     renderer,
+    attention,
   })
   const [ready, setReady] = createSignal(false)
   TuiPluginRuntime.init({
     api,
     config: tuiConfig,
+    dispose: () => attention.dispose(),
   })
     .catch((error) => {
       console.error("Failed to load TUI plugins", error)
@@ -320,7 +325,10 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
     },
     { priority: 1 },
   )
-  onCleanup(offSelectionKeys)
+  onCleanup(() => {
+    offSelectionKeys()
+    attention.dispose()
+  })
 
   // Wire up console copy-to-clipboard via opentui's onCopySelection callback
   renderer.console.onCopySelection = async (text: string) => {

packages/opencode/src/cli/cmd/tui/attention.ts

@@ -0,0 +1,261 @@
+import type {
+  TuiAttention,
+  TuiAttentionNotifyInput,
+  TuiAttentionNotifyResult,
+  TuiAttentionNotifySkipReason,
+  TuiAttentionWhen,
+  TuiKV,
+  TuiAttentionSoundName,
+  TuiAttentionSoundPack,
+  TuiAttentionSoundPackInfo,
+} from "@opencode-ai/plugin/tui"
+import stripAnsi from "strip-ansi"
+import type { TuiConfig } from "./config/tui"
+import { isAttentionSoundName } from "./config/tui-schema"
+import * as TuiAudio from "@tui/util/audio"
+import defaultSoundPath from "@opencode-ai/ui/audio/bip-bop-01.mp3" with { type: "file" }
+import questionSoundPath from "@opencode-ai/ui/audio/bip-bop-03.mp3" with { type: "file" }
+import permissionSoundPath from "@opencode-ai/ui/audio/staplebops-06.mp3" with { type: "file" }
+import errorSoundPath from "@opencode-ai/ui/audio/nope-03.mp3" with { type: "file" }
+import doneSoundPath from "@opencode-ai/ui/audio/bip-bop-01.mp3" with { type: "file" }
+import subagentDoneSoundPath from "@opencode-ai/ui/audio/yup-01.mp3" with { type: "file" }
+import * as Log from "@opencode-ai/core/util/log"
+
+type FocusState = "unknown" | "focused" | "blurred"
+
+type AttentionRenderer = {
+  readonly isDestroyed: boolean
+  on(event: "focus" | "blur", listener: () => void): unknown
+  off(event: "focus" | "blur", listener: () => void): unknown
+  triggerNotification(message: string, title?: string): boolean
+}
+
+type RegisteredSoundPack = TuiAttentionSoundPack & {
+  builtin: boolean
+}
+
+type TuiAttentionHost = TuiAttention & {
+  dispose(): void
+}
+
+const log = Log.create({ service: "tui.attention" })
+
+const DEFAULT_TITLE = "opencode"
+const DEFAULT_PACK_ID = "opencode.default"
+const KV_SOUND_PACK = "attention_sound_pack"
+const TITLE_LIMIT = 80
+const MESSAGE_LIMIT = 240
+const BUILTIN_PACK: RegisteredSoundPack = {
+  id: DEFAULT_PACK_ID,
+  name: "OpenCode Default",
+  builtin: true,
+  sounds: {
+    default: defaultSoundPath,
+    question: questionSoundPath,
+    permission: permissionSoundPath,
+    error: errorSoundPath,
+    done: doneSoundPath,
+    subagent_done: subagentDoneSoundPath,
+  },
+}
+
+function skipped(reason: TuiAttentionNotifySkipReason): TuiAttentionNotifyResult {
+  return {
+    ok: false,
+    notification: false,
+    sound: false,
+    skipped: reason,
+  }
+}
+
+function normalizeText(input: string | undefined, fallback: string, limit: number) {
+  const text = stripAnsi(input ?? "")
+    .replace(/[ \t]*[\r\n]+[ \t]*/g, " ")
+    .replace(/[\u0000-\u0009\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, "")
+    .trim()
+  const normalized = text.length ? text : fallback
+  return Array.from(normalized).slice(0, limit).join("")
+}
+
+function clampVolume(volume: number) {
+  if (!Number.isFinite(volume)) return 0
+  return Math.min(1, Math.max(0, volume))
+}
+
+function soundVolume(input: TuiAttentionNotifyInput, config: Pick<TuiConfig.Resolved, "attention">) {
+  if (!config.attention.sound) return
+  if (input.sound === false) return
+  if (input.sound === undefined) return clampVolume(config.attention.volume)
+  if (input.sound === true) return clampVolume(config.attention.volume)
+  return clampVolume(input.sound.volume ?? config.attention.volume)
+}
+
+function normalizePack(pack: TuiAttentionSoundPack): RegisteredSoundPack | undefined {
+  const id = pack.id.trim()
+  if (!id) return
+  return {
+    id,
+    name: pack.name?.trim() || undefined,
+    builtin: false,
+    sounds: Object.fromEntries(
+      Object.entries(pack.sounds).filter(
+        (item): item is [TuiAttentionSoundName, string] =>
+          isAttentionSoundName(item[0]) && typeof item[1] === "string" && item[1].trim().length > 0,
+      ),
+    ),
+  }
+}
+
+function focusSkip(when: TuiAttentionWhen, focus: FocusState) {
+  if (when === "always") return
+  if (focus === "unknown") return "focus_unknown"
+  if (when === "blurred" && focus === "focused") return "focused"
+  if (when === "focused" && focus === "blurred") return "blurred"
+}
+
+export function createTuiAttention(input: {
+  renderer: AttentionRenderer
+  config: Pick<TuiConfig.Resolved, "attention">
+  kv?: TuiKV
+  audio?: Pick<typeof TuiAudio, "loadSoundFile" | "play">
+}): TuiAttentionHost {
+  let focus: FocusState = "unknown"
+  let disposed = false
+  let activePackID: string | undefined
+  const packs = new Map<string, RegisteredSoundPack>([[BUILTIN_PACK.id, BUILTIN_PACK]])
+  const audio = input.audio ?? TuiAudio
+
+  const onFocus = () => {
+    focus = "focused"
+  }
+  const onBlur = () => {
+    focus = "blurred"
+  }
+
+  input.renderer.on("focus", onFocus)
+  input.renderer.on("blur", onBlur)
+
+  function configuredPackID() {
+    const stored = input.kv?.get<string | undefined>(KV_SOUND_PACK, undefined)
+    return activePackID ?? stored ?? input.config.attention.sound_pack
+  }
+
+  function currentPack() {
+    return packs.get(configuredPackID()) ?? BUILTIN_PACK
+  }
+
+  function soundCandidates(name: TuiAttentionSoundName) {
+    return [input.config.attention.sounds[name], currentPack().sounds[name], BUILTIN_PACK.sounds[name]].filter(
+      (item, index, list): item is string => typeof item === "string" && list.indexOf(item) === index,
+    )
+  }
+
+  async function playSound(name: TuiAttentionSoundName, volume: number) {
+    try {
+      for (const file of soundCandidates(name)) {
+        const current = await audio.loadSoundFile(file).catch((error) => {
+          log.debug("failed to load attention sound", { file, error })
+          return null
+        })
+        if (disposed) return false
+        if (current == null) continue
+        if (audio.play(current, { volume }) != null) return true
+      }
+      return false
+    } catch (error) {
+      log.debug("failed to play attention sound", { error })
+      return false
+    }
+  }
+
+  return {
+    async notify(request) {
+      try {
+        if (!input.config.attention.enabled) return skipped("attention_disabled")
+        if (disposed || input.renderer.isDestroyed) return skipped("renderer_destroyed")
+
+        const message = normalizeText(request.message, "", MESSAGE_LIMIT)
+        if (!message) return skipped("empty_message")
+
+        const requestedNotification = typeof request.notification === "object" ? request.notification : undefined
+        const notificationSkip = focusSkip(requestedNotification?.when ?? "blurred", focus)
+        const notificationRequested = input.config.attention.notifications && request.notification !== false
+        const shouldNotify = notificationRequested && !notificationSkip
+        const notification = shouldNotify
+          ? (() => {
+              try {
+                return input.renderer.triggerNotification(
+                  message,
+                  normalizeText(request.title, DEFAULT_TITLE, TITLE_LIMIT),
+                )
+              } catch (error) {
+                log.debug("failed to trigger attention notification", { error })
+                return false
+              }
+            })()
+          : false
+        const volume = soundVolume(request, input.config)
+        const requestedSound = typeof request.sound === "object" ? request.sound : undefined
+        const soundSkip = volume === undefined ? undefined : focusSkip(requestedSound?.when ?? "always", focus)
+        const soundName = requestedSound?.name && isAttentionSoundName(requestedSound.name) ? requestedSound.name : "default"
+        const sound = volume === undefined || soundSkip ? false : await playSound(soundName, volume)
+
+        if (!notification && !sound) {
+          if (notificationRequested && notificationSkip) return skipped(notificationSkip)
+          if (soundSkip) return skipped(soundSkip)
+        }
+
+        return {
+          ok: notification || sound,
+          notification,
+          sound,
+        }
+      } catch (error) {
+        log.debug("failed to handle attention notification", { error })
+        return {
+          ok: false,
+          notification: false,
+          sound: false,
+        }
+      }
+    },
+    soundboard: {
+      registerPack(pack) {
+        const next = normalizePack(pack)
+        if (!next) return () => {}
+        packs.set(next.id, next)
+        let disposed = false
+        return () => {
+          if (disposed) return
+          disposed = true
+          if (packs.get(next.id) === next) packs.delete(next.id)
+        }
+      },
+      activate(id, options) {
+        const pack = packs.get(id)
+        if (!pack) return false
+        activePackID = pack.id
+        if (options?.persist) input.kv?.set(KV_SOUND_PACK, pack.id)
+        return true
+      },
+      current() {
+        return currentPack().id
+      },
+      list(): TuiAttentionSoundPackInfo[] {
+        const current = currentPack().id
+        return Array.from(packs.values()).map((pack) => ({
+          id: pack.id,
+          name: pack.name,
+          active: pack.id === current,
+          builtin: pack.builtin,
+        }))
+      },
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      input.renderer.off("focus", onFocus)
+      input.renderer.off("blur", onBlur)
+    },
+  }
+}

packages/opencode/src/cli/cmd/tui/config/tui-schema.ts

@@ -1,12 +1,47 @@
 import { ConfigPlugin } from "@/config/plugin"
 import { TuiKeybind } from "./keybind"
 import { Schema } from "effect"
+import { isRecord } from "@/util/record"
+import { Filesystem } from "@/util/filesystem"
+import { TuiAttentionSoundNames, type TuiAttentionSoundName } from "@opencode-ai/plugin/tui"
+
+export type TuiAttentionSoundPaths = Partial<Record<TuiAttentionSoundName, string>>
+
+export function isAttentionSoundName(value: string): value is TuiAttentionSoundName {
+  return TuiAttentionSoundNames.includes(value as TuiAttentionSoundName)
+}
+
+export function resolveAttentionSoundPaths(
+  root: string,
+  sounds: unknown,
+  options?: { trim?: boolean },
+): TuiAttentionSoundPaths {
+  if (!isRecord(sounds)) return {}
+  return Object.fromEntries(
+    Object.entries(sounds).flatMap(([name, file]) => {
+      if (!isAttentionSoundName(name)) return []
+      if (typeof file !== "string") return []
+      const value = options?.trim ? file.trim() : file
+      if (!value) return []
+      return [[name, Filesystem.resolveFilePath(root, value)]]
+    }),
+  )
+}
 
 export const KeymapLeaderTimeoutDefault = 2000
 const KeymapLeaderTimeout = Schema.Int.check(Schema.isGreaterThan(0)).annotate({
   description: "Leader key timeout in milliseconds",
 })
 
+const TuiAttentionSounds = Schema.Struct({
+  default: Schema.optional(Schema.String),
+  question: Schema.optional(Schema.String),
+  permission: Schema.optional(Schema.String),
+  error: Schema.optional(Schema.String),
+  done: Schema.optional(Schema.String),
+  subagent_done: Schema.optional(Schema.String),
+})
+
 export const ScrollSpeed = Schema.Number.check(Schema.isGreaterThanOrEqualTo(0.001))
 
 export const ScrollAcceleration = Schema.Struct({
@@ -17,6 +52,15 @@ export const DiffStyle = Schema.Literals(["auto", "stacked"]).annotate({
   description: "Control diff rendering style: 'auto' adapts to terminal width, 'stacked' always shows single column",
 })
 
+export const Attention = Schema.Struct({
+  enabled: Schema.optional(Schema.Boolean),
+  notifications: Schema.optional(Schema.Boolean),
+  sound: Schema.optional(Schema.Boolean),
+  volume: Schema.optional(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(1))),
+  sound_pack: Schema.optional(Schema.String),
+  sounds: Schema.optional(TuiAttentionSounds),
+}).annotate({ description: "Attention notification and sound settings" })
+
 export const TuiInfo = Schema.Struct({
   $schema: Schema.optional(Schema.String),
   theme: Schema.optional(Schema.String),
@@ -24,6 +68,7 @@ export const TuiInfo = Schema.Struct({
   plugin: Schema.optional(Schema.Array(ConfigPlugin.Spec)),
   plugin_enabled: Schema.optional(Schema.Record(Schema.String, Schema.Boolean)),
   leader_timeout: Schema.optional(KeymapLeaderTimeout),
+  attention: Schema.optional(Attention),
   scroll_speed: Schema.optional(ScrollSpeed).annotate({
     description: "TUI scroll speed",
   }),

packages/opencode/src/cli/cmd/tui/config/tui.ts

@@ -1,5 +1,6 @@
 export * as TuiConfig from "./tui"
 
+import path from "path"
 import { createBindingLookup } from "@opentui/keymap/extras"
 import { mergeDeep, unique } from "remeda"
 import { Context, Effect, Fiber, Layer, Schema } from "effect"
@@ -7,7 +8,7 @@ import { ConfigParse } from "@/config/parse"
 import { InvalidError } from "@/config/error"
 import * as ConfigPaths from "@/config/paths"
 import { migrateTuiConfig } from "./tui-migrate"
-import { KeymapLeaderTimeoutDefault, TuiInfo } from "./tui-schema"
+import { KeymapLeaderTimeoutDefault, resolveAttentionSoundPaths, TuiInfo } from "./tui-schema"
 import { Flag } from "@opencode-ai/core/flag/flag"
 import { isRecord } from "@/util/record"
 import { Global } from "@opencode-ai/core/global"
@@ -22,6 +23,7 @@ import * as Log from "@opencode-ai/core/util/log"
 import { ConfigVariable } from "@/config/variable"
 import { Npm } from "@opencode-ai/core/npm"
 import type { DeepMutable } from "@opencode-ai/core/schema"
+import type { TuiAttentionSoundName } from "@opencode-ai/plugin/tui"
 
 const log = Log.create({ service: "tui.config" })
 
@@ -33,7 +35,15 @@ type Acc = {
   plugin_origins: ConfigPlugin.Origin[]
 }
 
-export type Resolved = Omit<Info, "keybinds" | "leader_timeout"> & {
+export type Resolved = Omit<Info, "attention" | "keybinds" | "leader_timeout"> & {
+  attention: {
+    enabled: boolean
+    notifications: boolean
+    sound: boolean
+    volume: number
+    sound_pack: string
+    sounds: Partial<Record<TuiAttentionSoundName, string>>
+  }
   keybinds: TuiKeybind.BindingLookupView
   leader_timeout: number
   // Internal resolved plugin list used by runtime loading.
@@ -101,7 +111,16 @@ const loadState = Effect.fn("TuiConfig.loadState")(function* (ctx: { directory:
           })
         }
       }
-      const validated = ConfigParse.schema(Info, normalized, configFilepath)
+      const parsed = ConfigParse.schema(Info, normalized, configFilepath)
+      const validated = parsed.attention?.sounds
+        ? {
+            ...parsed,
+            attention: {
+              ...parsed.attention,
+              sounds: resolveAttentionSoundPaths(path.dirname(configFilepath), parsed.attention.sounds),
+            },
+          }
+        : parsed
       return yield* resolvePlugins(validated, configFilepath)
     }).pipe(
       // catchCause (not tapErrorCause + orElseSucceed) because JSONC parsing and validation
@@ -197,6 +216,14 @@ const loadState = Effect.fn("TuiConfig.loadState")(function* (ctx: { directory:
   const parsedKeybinds = TuiKeybind.parse(keybinds)
   const result: Resolved = {
     ...acc.result,
+    attention: {
+      enabled: acc.result.attention?.enabled ?? false,
+      notifications: acc.result.attention?.notifications ?? true,
+      sound: acc.result.attention?.sound ?? true,
+      volume: acc.result.attention?.volume ?? 0.4,
+      sound_pack: acc.result.attention?.sound_pack ?? "opencode.default",
+      sounds: acc.result.attention?.sounds ?? {},
+    },
     keybinds: createBindingLookup(TuiKeybind.toBindingConfig(parsedKeybinds), {
       commandMap: TuiKeybind.CommandMap,
       bindingDefaults: TuiKeybind.bindingDefaults(),

packages/opencode/src/cli/cmd/tui/feature-plugins/home/tips-view.tsx

@@ -1,11 +1,52 @@
-import { createMemo, For } from "solid-js"
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
+import { createMemo, For, type Accessor } from "solid-js"
 import { DEFAULT_THEMES, useTheme } from "@tui/context/theme"
 import { Flag } from "@opencode-ai/core/flag/flag"
+import { useCommandShortcut } from "../../keymap"
 
 const themeCount = Object.keys(DEFAULT_THEMES).length
-const themeTip = `Use {highlight}/themes{/highlight} or {highlight}Ctrl+X T{/highlight} to switch between ${themeCount} built-in themes`
 
 type TipPart = { text: string; highlight: boolean }
+type TipShortcut = Accessor<string>
+type Shortcuts = {
+  agentCycle: TipShortcut
+  childFirst: TipShortcut
+  childNext: TipShortcut
+  childPrevious: TipShortcut
+  commandList: TipShortcut
+  editorOpen: TipShortcut
+  helpShow: TipShortcut
+  inputClear: TipShortcut
+  inputNewline: TipShortcut
+  inputPaste: TipShortcut
+  inputUndo: TipShortcut
+  leader: TipShortcut
+  messagesCopy: TipShortcut
+  messagesFirst: TipShortcut
+  messagesLast: TipShortcut
+  messagesPageDown: TipShortcut
+  messagesPageUp: TipShortcut
+  messagesToggleConceal: TipShortcut
+  modelCycleRecent: TipShortcut
+  modelList: TipShortcut
+  sessionCycleRecent: TipShortcut
+  sessionCycleRecentReverse: TipShortcut
+  sessionExport: TipShortcut
+  sessionInterrupt: TipShortcut
+  sessionList: TipShortcut
+  sessionNew: TipShortcut
+  sessionParent: TipShortcut
+  sessionPinToggle: TipShortcut
+  sessionQuickSwitch1: TipShortcut
+  sessionQuickSwitch9: TipShortcut
+  sessionSidebarToggle: TipShortcut
+  sessionTimeline: TipShortcut
+  sessionToggleRecent: TipShortcut
+  statusView: TipShortcut
+  terminalSuspend: TipShortcut
+  themeList: TipShortcut
+}
+type Tip = string | ((shortcuts: Shortcuts) => string | undefined)
 
 function parse(tip: string): TipPart[] {
   const parts: TipPart[] = []
@@ -33,17 +74,86 @@ function parse(tip: string): TipPart[] {
 
 const NO_MODELS_TIP = "Run {highlight}/connect{/highlight} to add an AI provider and start coding"
 
-export function Tips(props: { connected?: boolean }) {
+function shortcutText(value: string) {
+  return `{highlight}${value}{/highlight}`
+}
+
+function commandText(command: string, shortcut: string) {
+  if (!shortcut) return shortcutText(command)
+  return `${shortcutText(command)} or ${shortcutText(shortcut)}`
+}
+
+function press(shortcut: string, text: string) {
+  if (!shortcut) return undefined
+  return `Press ${shortcutText(shortcut)} ${text}`
+}
+
+function configShortcut(api: TuiPluginApi, command: string): TipShortcut {
+  return () =>
+    api.tuiConfig.keybinds
+      .get(command)
+      .map((binding) => api.keys.formatSequence(Array.from(api.keymap.parseKeySequence(binding.key))))
+      .filter(Boolean)
+      .join(", ")
+}
+
+export function Tips(props: { api: TuiPluginApi; connected?: boolean }) {
   const theme = useTheme().theme
-  const randomTip = TIPS[Math.floor(Math.random() * TIPS.length)]
-  const parts = createMemo(() => parse(props.connected === false ? NO_MODELS_TIP : randomTip))
+  const tipOffset = Math.random()
+  const shortcuts: Shortcuts = {
+    agentCycle: useCommandShortcut("agent.cycle"),
+    childFirst: configShortcut(props.api, "session.child.first"),
+    childNext: configShortcut(props.api, "session.child.next"),
+    childPrevious: configShortcut(props.api, "session.child.previous"),
+    commandList: useCommandShortcut("command.palette.show"),
+    editorOpen: useCommandShortcut("prompt.editor"),
+    helpShow: useCommandShortcut("help.show"),
+    inputClear: useCommandShortcut("prompt.clear"),
+    inputNewline: useCommandShortcut("input.newline"),
+    inputPaste: useCommandShortcut("prompt.paste"),
+    inputUndo: useCommandShortcut("input.undo"),
+    leader: configShortcut(props.api, "leader"),
+    messagesCopy: configShortcut(props.api, "messages.copy"),
+    messagesFirst: configShortcut(props.api, "session.first"),
+    messagesLast: configShortcut(props.api, "session.last"),
+    messagesPageDown: configShortcut(props.api, "session.page.down"),
+    messagesPageUp: configShortcut(props.api, "session.page.up"),
+    messagesToggleConceal: configShortcut(props.api, "session.toggle.conceal"),
+    modelCycleRecent: useCommandShortcut("model.cycle_recent"),
+    modelList: useCommandShortcut("model.list"),
+    sessionCycleRecent: useCommandShortcut("session.cycle_recent"),
+    sessionCycleRecentReverse: useCommandShortcut("session.cycle_recent_reverse"),
+    sessionExport: configShortcut(props.api, "session.export"),
+    sessionInterrupt: configShortcut(props.api, "session.interrupt"),
+    sessionList: useCommandShortcut("session.list"),
+    sessionNew: useCommandShortcut("session.new"),
+    sessionParent: configShortcut(props.api, "session.parent"),
+    sessionPinToggle: configShortcut(props.api, "session.pin.toggle"),
+    sessionQuickSwitch1: useCommandShortcut("session.quick_switch.1"),
+    sessionQuickSwitch9: useCommandShortcut("session.quick_switch.9"),
+    sessionSidebarToggle: configShortcut(props.api, "session.sidebar.toggle"),
+    sessionTimeline: configShortcut(props.api, "session.timeline"),
+    sessionToggleRecent: configShortcut(props.api, "session.toggle.recent"),
+    statusView: useCommandShortcut("opencode.status"),
+    terminalSuspend: useCommandShortcut("terminal.suspend"),
+    themeList: useCommandShortcut("theme.switch"),
+  }
+  const tip = createMemo(() => {
+    if (props.connected === false) return NO_MODELS_TIP
+    const tips = TIPS.flatMap((item) => {
+      const value = typeof item === "string" ? item : item(shortcuts)
+      return value ? [value] : []
+    })
+    return tips[Math.floor(tipOffset * tips.length)] ?? NO_MODELS_TIP
+  })
+  const parts = createMemo(() => parse(tip()))
 
   return (
     <box flexDirection="row" maxWidth="100%">
       <text flexShrink={0} style={{ fg: theme.warning }}>
         ● Tip{" "}
       </text>
-      <text flexShrink={1}>
+      <text flexShrink={1} wrapMode="word">
         <For each={parts()}>
           {(part) => <span style={{ fg: part.highlight ? theme.text : theme.textMuted }}>{part.text}</span>}
         </For>
@@ -52,46 +162,66 @@ export function Tips(props: { connected?: boolean }) {
   )
 }
 
-const TIPS = [
+const TIPS: Tip[] = [
   "Type {highlight}@{/highlight} followed by a filename to fuzzy search and attach files",
   "Start a message with {highlight}!{/highlight} to run shell commands directly (e.g., {highlight}!ls -la{/highlight})",
-  "Press {highlight}Tab{/highlight} to cycle between Build and Plan agents",
+  (shortcuts) => press(shortcuts.agentCycle(), "to cycle between Build and Plan agents"),
   "Use {highlight}/undo{/highlight} to revert the last message and file changes",
   "Use {highlight}/redo{/highlight} to restore previously undone messages and file changes",
   "Run {highlight}/share{/highlight} to create a public link to your conversation at opencode.ai",
   "Drag and drop images or PDFs into the terminal to add them as context",
-  "Press {highlight}Ctrl+V{/highlight} to paste images from your clipboard into the prompt",
-  "Press {highlight}Ctrl+X E{/highlight} or {highlight}/editor{/highlight} to compose messages in your external editor",
+  (shortcuts) => press(shortcuts.inputPaste(), "to paste images from your clipboard into the prompt"),
+  (shortcuts) => `Use ${commandText("/editor", shortcuts.editorOpen())} to compose messages in your external editor`,
   "Run {highlight}/init{/highlight} to auto-generate project rules based on your codebase",
-  "Run {highlight}/models{/highlight} or {highlight}Ctrl+X M{/highlight} to see and switch between available AI models",
-  themeTip,
-  "Press {highlight}Ctrl+X N{/highlight} or {highlight}/new{/highlight} to start a fresh conversation session",
-  "Use {highlight}/sessions{/highlight} or {highlight}Ctrl+X L{/highlight} to list and continue previous conversations",
+  (shortcuts) => `Use ${commandText("/models", shortcuts.modelList())} to see and switch between available AI models`,
+  (shortcuts) => `Use ${commandText("/themes", shortcuts.themeList())} to switch between ${themeCount} built-in themes`,
+  (shortcuts) => `Use ${commandText("/new", shortcuts.sessionNew())} to start a fresh conversation session`,
+  (shortcuts) => `Use ${commandText("/sessions", shortcuts.sessionList())} to list and continue previous conversations`,
   ...(Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
-    ? [
-        "Press {highlight}Ctrl+F{/highlight} in the session list to pin a session so it stays at the top",
-        "Pinned and recent sessions are bound to {highlight}Ctrl+X 1{/highlight} through {highlight}Ctrl+X 9{/highlight} for one-press switching",
-        "Press {highlight}Ctrl+X ]{/highlight} / {highlight}Ctrl+X [{/highlight} to cycle through recently visited sessions",
-        "Press {highlight}Ctrl+H{/highlight} in the session list to show or hide a session in the Recent group",
-      ]
+    ? ([
+        (shortcuts) =>
+          press(shortcuts.sessionPinToggle(), "in the session list to pin a session so it stays at the top"),
+        (shortcuts) =>
+          shortcuts.sessionQuickSwitch1() && shortcuts.sessionQuickSwitch9()
+            ? `Pinned and recent sessions are bound to ${shortcutText(shortcuts.sessionQuickSwitch1())} through ${shortcutText(shortcuts.sessionQuickSwitch9())} for one-press switching`
+            : undefined,
+        (shortcuts) =>
+          shortcuts.sessionCycleRecent() && shortcuts.sessionCycleRecentReverse()
+            ? `Press ${shortcutText(shortcuts.sessionCycleRecent())} / ${shortcutText(shortcuts.sessionCycleRecentReverse())} to cycle through recently visited sessions`
+            : undefined,
+        (shortcuts) =>
+          press(shortcuts.sessionToggleRecent(), "in the session list to show or hide a session in the Recent group"),
+      ] satisfies Tip[])
     : []),
   "Run {highlight}/compact{/highlight} to summarize long sessions near context limits",
-  "Press {highlight}Ctrl+X X{/highlight} or {highlight}/export{/highlight} to save the conversation as Markdown",
-  "Press {highlight}Ctrl+X Y{/highlight} to copy the assistant's last message to clipboard",
-  "Press {highlight}Ctrl+P{/highlight} to see all available actions and commands",
+  (shortcuts) => `Use ${commandText("/export", shortcuts.sessionExport())} to save the conversation as Markdown`,
+  (shortcuts) => press(shortcuts.messagesCopy(), "to copy the assistant's last message to clipboard"),
+  (shortcuts) => press(shortcuts.commandList(), "to see all available actions and commands"),
   "Run {highlight}/connect{/highlight} to add API keys for 75+ supported LLM providers",
-  "The leader key is {highlight}Ctrl+X{/highlight}; combine with other keys for quick actions",
-  "Press {highlight}F2{/highlight} to quickly switch between recently used models",
-  "Press {highlight}Ctrl+X B{/highlight} to show/hide the sidebar panel",
-  "Use {highlight}PageUp{/highlight}/{highlight}PageDown{/highlight} to navigate through conversation history",
-  "Press {highlight}Ctrl+G{/highlight} or {highlight}Home{/highlight} to jump to the beginning of the conversation",
-  "Press {highlight}Ctrl+Alt+G{/highlight} or {highlight}End{/highlight} to jump to the most recent message",
-  "Press {highlight}Shift+Enter{/highlight} or {highlight}Ctrl+J{/highlight} to add newlines in your prompt",
-  "Press {highlight}Ctrl+C{/highlight} when typing to clear the input field",
-  "Press {highlight}Escape{/highlight} to stop the AI mid-response",
+  (shortcuts) => `The leader key is ${shortcutText(shortcuts.leader())}; combine with other keys for quick actions`,
+  (shortcuts) => press(shortcuts.modelCycleRecent(), "to quickly switch between recently used models"),
+  (shortcuts) => press(shortcuts.sessionSidebarToggle(), "in a session to show or hide the sidebar panel"),
+  (shortcuts) =>
+    shortcuts.messagesPageUp() && shortcuts.messagesPageDown()
+      ? `Use ${shortcutText(shortcuts.messagesPageUp())}/${shortcutText(shortcuts.messagesPageDown())} to navigate through conversation history`
+      : undefined,
+  (shortcuts) => press(shortcuts.messagesFirst(), "to jump to the beginning of the conversation"),
+  (shortcuts) => press(shortcuts.messagesLast(), "to jump to the most recent message"),
+  (shortcuts) => press(shortcuts.inputNewline(), "to add newlines in your prompt"),
+  (shortcuts) => press(shortcuts.inputClear(), "when typing to clear the input field"),
+  (shortcuts) => press(shortcuts.sessionInterrupt(), "to stop the AI mid-response"),
   "Switch to {highlight}Plan{/highlight} agent to get suggestions without making actual changes",
   "Use {highlight}@agent-name{/highlight} in prompts to invoke specialized subagents",
-  "Press {highlight}Ctrl+X Right/Left{/highlight} to cycle through parent and child sessions",
+  (shortcuts) => {
+    const items = [
+      shortcuts.sessionParent(),
+      shortcuts.childFirst(),
+      shortcuts.childPrevious(),
+      shortcuts.childNext(),
+    ].filter(Boolean)
+    if (!items.length) return undefined
+    return `Use ${items.map(shortcutText).join(" / ")} to move between parent and child sessions`
+  },
   "Create {highlight}opencode.json{/highlight} for server settings and {highlight}tui.json{/highlight} for TUI settings",
   "Place TUI settings in {highlight}~/.config/opencode/tui.json{/highlight} for global config",
   "Add {highlight}$schema{/highlight} to your config for autocomplete in your editor",
@@ -99,22 +229,21 @@ const TIPS = [
   "Override any keybind in {highlight}tui.json{/highlight} via the {highlight}keybinds{/highlight} section",
   "Set any keybind to {highlight}none{/highlight} to disable it completely",
   "Configure local or remote MCP servers in the {highlight}mcp{/highlight} config section",
-  "OpenCode auto-handles OAuth for remote MCP servers requiring auth",
-  "Add {highlight}.md{/highlight} files to {highlight}.opencode/command/{/highlight} to define reusable custom prompts",
+  "Add {highlight}.md{/highlight} files to {highlight}.opencode/commands/{/highlight} to define reusable custom prompts",
   "Use {highlight}$ARGUMENTS{/highlight}, {highlight}$1{/highlight}, {highlight}$2{/highlight} in custom commands for dynamic input",
   "Use backticks in commands to inject shell output (e.g., {highlight}`git status`{/highlight})",
-  "Add {highlight}.md{/highlight} files to {highlight}.opencode/agent/{/highlight} for specialized AI personas",
+  "Add {highlight}.md{/highlight} files to {highlight}.opencode/agents/{/highlight} for specialized AI personas",
   "Configure per-agent permissions for {highlight}edit{/highlight}, {highlight}bash{/highlight}, and {highlight}webfetch{/highlight} tools",
   'Use patterns like {highlight}"git *": "allow"{/highlight} for granular bash permissions',
   'Set {highlight}"rm -rf *": "deny"{/highlight} to block destructive commands',
   'Configure {highlight}"git push": "ask"{/highlight} to require approval before pushing',
-  "OpenCode auto-formats files using prettier, gofmt, ruff, and more",
-  'Set {highlight}"formatter": false{/highlight} in config to disable all auto-formatting',
+  'Set {highlight}"formatter": true{/highlight} in config to enable built-in formatters like prettier, gofmt, and ruff',
+  'Set {highlight}"formatter": false{/highlight} in config to disable formatters enabled by another config layer',
   "Define custom formatter commands with file extensions in config",
-  "OpenCode uses LSP servers for intelligent code analysis",
+  'Set {highlight}"lsp": true{/highlight} in config to enable built-in LSP servers for code analysis',
   "Create {highlight}.ts{/highlight} files in {highlight}.opencode/tools/{/highlight} to define new LLM tools",
   "Tool definitions can invoke scripts written in Python, Go, etc",
-  "Add {highlight}.ts{/highlight} files to {highlight}.opencode/plugin/{/highlight} for event hooks",
+  "Add {highlight}.ts{/highlight} files to {highlight}.opencode/plugins/{/highlight} for event hooks",
   "Use plugins to send OS notifications when sessions complete",
   "Create a plugin to prevent OpenCode from reading sensitive files",
   "Use {highlight}opencode run{/highlight} for non-interactive scripting",
@@ -133,7 +262,7 @@ const TIPS = [
   'Use {highlight}"theme": "system"{/highlight} to match your terminal\'s colors',
   "Create JSON theme files in {highlight}.opencode/themes/{/highlight} directory",
   "Themes support dark/light variants for both modes",
-  "Reference ANSI colors 0-255 in custom themes",
+  "Use numeric xterm color codes 0-255 in custom theme JSON",
   "Use {highlight}{env:VAR_NAME}{/highlight} syntax to reference environment variables in config",
   "Use {highlight}{file:path}{/highlight} to include file contents in config values",
   "Use {highlight}instructions{/highlight} in config to load additional rules files",
@@ -149,18 +278,23 @@ const TIPS = [
   "Permission {highlight}external_directory{/highlight} protects files outside project",
   "Run {highlight}opencode debug config{/highlight} to troubleshoot configuration",
   "Use {highlight}--print-logs{/highlight} flag to see detailed logs in stderr",
-  "Press {highlight}Ctrl+X G{/highlight} or {highlight}/timeline{/highlight} to jump to specific messages",
-  "Press {highlight}Ctrl+X H{/highlight} to toggle code block visibility in messages",
-  "Press {highlight}Ctrl+X S{/highlight} or {highlight}/status{/highlight} to see system status info",
+  (shortcuts) => `Use ${commandText("/timeline", shortcuts.sessionTimeline())} to jump to specific messages`,
+  (shortcuts) => press(shortcuts.messagesToggleConceal(), "to toggle code block visibility in messages"),
+  (shortcuts) => `Use ${commandText("/status", shortcuts.statusView())} to see system status info`,
   "Enable {highlight}scroll_acceleration{/highlight} in {highlight}tui.json{/highlight} for smooth macOS-style scrolling",
-  "Toggle username display in chat via command palette ({highlight}Ctrl+P{/highlight})",
+  (shortcuts) =>
+    shortcuts.commandList()
+      ? `Toggle username display in chat via the command palette (${shortcutText(shortcuts.commandList())})`
+      : "Toggle username display in chat via the command palette",
   "Run {highlight}docker run -it --rm ghcr.io/anomalyco/opencode{/highlight} for containerized use",
   "Use {highlight}/connect{/highlight} with OpenCode Zen for curated, tested models",
   "Commit your project's {highlight}AGENTS.md{/highlight} file to Git for team sharing",
   "Use {highlight}/review{/highlight} to review uncommitted changes, branches, or PRs",
-  "Run {highlight}/help{/highlight} or {highlight}Ctrl+X H{/highlight} to show the help dialog",
+  (shortcuts) => `Use ${commandText("/help", shortcuts.helpShow())} to show the help dialog`,
   "Use {highlight}/rename{/highlight} to rename the current session",
   ...(process.platform === "win32"
-    ? ["Press {highlight}Ctrl+Z{/highlight} to undo changes in your prompt"]
-    : ["Press {highlight}Ctrl+Z{/highlight} to suspend the terminal and return to your shell"]),
+    ? ([(shortcuts) => press(shortcuts.inputUndo(), "to undo changes in your prompt")] satisfies Tip[])
+    : ([
+        (shortcuts) => press(shortcuts.terminalSuspend(), "to suspend the terminal and return to your shell"),
+      ] satisfies Tip[])),
 ]

packages/opencode/src/cli/cmd/tui/feature-plugins/home/tips.tsx

@@ -24,9 +24,9 @@ function View(props: { api: TuiPluginApi; hidden: boolean; show: boolean; connec
   }))
 
   return (
-    <box height={4} minHeight={0} width="100%" maxWidth={75} alignItems="center" paddingTop={3} flexShrink={1}>
+    <box width="100%" maxWidth={75} alignItems="center" paddingTop={3} flexShrink={1}>
       <Show when={props.show}>
-        <Tips connected={props.connected} />
+        <Tips api={props.api} connected={props.connected} />
       </Show>
     </box>
   )

packages/opencode/src/cli/cmd/tui/feature-plugins/system/notifications.ts

@@ -0,0 +1,94 @@
+import type { Event } from "@opencode-ai/sdk/v2"
+import type { TuiAttentionSoundName, TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { InternalTuiPlugin } from "../../plugin/internal"
+
+const id = "internal:notifications"
+
+type SessionError = Extract<Event, { type: "session.error" }>["properties"]["error"]
+
+function notify(api: TuiPluginApi, sessionID: string | undefined, message: string, sound: TuiAttentionSoundName) {
+  const session = sessionID ? api.state.session.get(sessionID) : undefined
+  const isSubagent = session?.parentID !== undefined
+  void api.attention.notify({
+    title: session?.title,
+    message,
+    notification: isSubagent ? false : { when: "blurred" },
+    sound: { name: sound, when: "always" },
+  })
+}
+
+function sessionErrorMessage(error: SessionError) {
+  if (error?.name === "MessageAbortedError") return "Session aborted"
+  const data = error?.data
+  if (data && typeof data === "object" && "message" in data && data.message === "SSE read timed out") {
+    return "Model stopped responding"
+  }
+  return "Session error"
+}
+
+const tui: TuiPlugin = async (api) => {
+  const active = new Set<string>()
+  const errored = new Set<string>()
+  const questions = new Set<string>()
+  const permissions = new Set<string>()
+
+  api.event.on("question.asked", (event) => {
+    if (questions.has(event.properties.id)) return
+    questions.add(event.properties.id)
+    notify(api, event.properties.sessionID, "Question needs input", "question")
+  })
+
+  api.event.on("question.replied", (event) => {
+    questions.delete(event.properties.requestID)
+  })
+
+  api.event.on("question.rejected", (event) => {
+    questions.delete(event.properties.requestID)
+  })
+
+  api.event.on("permission.asked", (event) => {
+    if (permissions.has(event.properties.id)) return
+    permissions.add(event.properties.id)
+    notify(api, event.properties.sessionID, "Permission needs input", "permission")
+  })
+
+  api.event.on("permission.replied", (event) => {
+    permissions.delete(event.properties.requestID)
+  })
+
+  api.event.on("session.status", (event) => {
+    const sessionID = event.properties.sessionID
+    if (event.properties.status.type === "busy" || event.properties.status.type === "retry") {
+      active.add(sessionID)
+      errored.delete(sessionID)
+      return
+    }
+
+    if (event.properties.status.type !== "idle") return
+    if (!active.has(sessionID)) return
+    active.delete(sessionID)
+
+    if (errored.has(sessionID)) {
+      errored.delete(sessionID)
+      return
+    }
+
+    const session = api.state.session.get(sessionID)
+    notify(api, sessionID, "Session done", session?.parentID ? "subagent_done" : "done")
+  })
+
+  api.event.on("session.error", (event) => {
+    const sessionID = event.properties.sessionID
+    if (!sessionID) return
+    if (!active.has(sessionID)) return
+    errored.add(sessionID)
+    notify(api, sessionID, sessionErrorMessage(event.properties.error), "error")
+  })
+}
+
+const plugin: InternalTuiPlugin = {
+  id,
+  tui,
+}
+
+export default plugin

packages/opencode/src/cli/cmd/tui/plugin/api.tsx

@@ -40,6 +40,7 @@ type Input = {
   theme: ReturnType<typeof useTheme>
   toast: ReturnType<typeof useToast>
   renderer: TuiPluginApi["renderer"]
+  attention: TuiPluginApi["attention"]
 }
 
 function routeRegister(routes: RouteMap, list: TuiRouteDefinition[], bump: () => void) {
@@ -206,6 +207,7 @@ export function createTuiApi(input: Input): TuiPluginApi {
   }
   return {
     app: appApi(),
+    attention: input.attention,
     // Keep deprecated `api.command` working for v1 plugins; remove in v2.
     command: createCommandShim(input.keymap, input.dialog, input.tuiConfig.keybinds),
     keys: {

packages/opencode/src/cli/cmd/tui/plugin/internal.ts

@@ -7,6 +7,7 @@ import SidebarTodo from "../feature-plugins/sidebar/todo"
 import SidebarFiles from "../feature-plugins/sidebar/files"
 import SidebarFooter from "../feature-plugins/sidebar/footer"
 import PluginManager from "../feature-plugins/system/plugins"
+import Notifications from "../feature-plugins/system/notifications"
 import SessionV2Debug from "../feature-plugins/system/session-v2"
 import WhichKey from "../feature-plugins/system/which-key"
 import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
@@ -27,6 +28,7 @@ export const INTERNAL_TUI_PLUGINS: InternalTuiPlugin[] = [
   SidebarTodo,
   SidebarFiles,
   SidebarFooter,
+  Notifications,
   PluginManager,
   WhichKey,
   ...(Flag.OPENCODE_EXPERIMENTAL_EVENT_SYSTEM ? [SessionV2Debug] : []),

packages/opencode/src/cli/cmd/tui/plugin/runtime.ts

@@ -17,6 +17,7 @@ import { TuiConfig } from "@/cli/cmd/tui/config/tui"
 import * as Log from "@opencode-ai/core/util/log"
 import { errorData, errorMessage } from "@/util/error"
 import { isRecord } from "@/util/record"
+import { resolveAttentionSoundPaths } from "../config/tui-schema"
 import {
   readPackageThemes,
   readPluginId,
@@ -51,7 +52,7 @@ type PluginLoad = {
   id: string
   module: TuiPluginModule
   origin: ConfigPlugin.Origin
-  theme_root: string
+  plugin_root: string
   theme_files: string[]
 }
 
@@ -106,6 +107,7 @@ const ScopedKeymapMethods = new Set<PropertyKey>([
 type RuntimeState = {
   directory: string
   api: Api
+  dispose?: () => void
   slots: HostSlots
   plugins: PluginEntry[]
   plugins_by_id: Map<string, PluginEntry>
@@ -156,6 +158,37 @@ function createScopedKeymap(keymap: TuiPluginApi["keymap"], scope: PluginScope):
   })
 }
 
+function createScopedAttention(
+  attention: TuiPluginApi["attention"],
+  scope: PluginScope,
+  root: string,
+): TuiPluginApi["attention"] {
+  return {
+    notify(input) {
+      return attention.notify(input)
+    },
+    soundboard: {
+      registerPack(pack) {
+        return scope.track(
+          attention.soundboard.registerPack({
+            ...pack,
+            sounds: resolveAttentionSoundPaths(root, pack.sounds, { trim: true }),
+          }),
+        )
+      },
+      activate(id, options) {
+        return attention.soundboard.activate(id, options)
+      },
+      current() {
+        return attention.soundboard.current()
+      },
+      list() {
+        return attention.soundboard.list()
+      },
+    },
+  }
+}
+
 type CleanupResult = { type: "ok" } | { type: "error"; error: unknown } | { type: "timeout" }
 
 function runCleanup(fn: () => unknown, ms: number): Promise<CleanupResult> {
@@ -204,8 +237,7 @@ function createThemeInstaller(
   plugin: PluginEntry,
 ): TuiTheme["install"] {
   return async (file) => {
-    const raw = file.startsWith("file://") ? fileURLToPath(file) : file
-    const src = path.isAbsolute(raw) ? raw : path.resolve(root, raw)
+    const src = Filesystem.resolveFilePath(root, file)
     const name = path.basename(src, path.extname(src))
     const source_dir = path.dirname(meta.source)
     const local_dir =
@@ -330,7 +362,7 @@ function loadInternalPlugin(item: InternalTuiPlugin): PluginLoad {
       scope: "global",
       source: target,
     },
-    theme_root: process.cwd(),
+    plugin_root: process.cwd(),
     theme_files: [],
   }
 }
@@ -352,7 +384,7 @@ async function readThemeFiles(spec: string, pkg?: PluginPackage) {
 async function syncPluginThemes(plugin: PluginEntry) {
   if (!plugin.load.theme_files.length) return
   if (plugin.meta.state === "same") return
-  const install = createThemeInstaller(plugin.load.origin, plugin.load.theme_root, plugin.load.spec, plugin)
+  const install = createThemeInstaller(plugin.load.origin, plugin.load.plugin_root, plugin.load.spec, plugin)
   for (const file of plugin.load.theme_files) {
     await install(file).catch((error) => {
       warn("failed to sync tui plugin oc-themes", { path: plugin.load.spec, id: plugin.id, theme: file, error })
@@ -552,7 +584,7 @@ function pluginApi(runtime: RuntimeState, plugin: PluginEntry, scope: PluginScop
   }
 
   const theme: TuiPluginApi["theme"] = Object.assign(Object.create(api.theme), {
-    install: createThemeInstaller(load.origin, load.theme_root, load.spec, plugin),
+    install: createThemeInstaller(load.origin, load.plugin_root, load.spec, plugin),
   })
 
   const event: TuiPluginApi["event"] = {
@@ -576,6 +608,7 @@ function pluginApi(runtime: RuntimeState, plugin: PluginEntry, scope: PluginScop
 
   return {
     app: api.app,
+    attention: createScopedAttention(api.attention, scope, load.plugin_root),
     // Keep deprecated `api.command` working for v1 plugins; remove in v2.
     command: createCommandShim(keymap, api.ui.dialog, api.tuiConfig.keybinds),
     keys: api.keys,
@@ -682,7 +715,7 @@ async function resolveExternalPlugins(list: ConfigPlugin.Origin[], wait: () => P
         id,
         module: mod,
         origin,
-        theme_root: loaded.pkg?.dir ?? resolveRoot(loaded.target),
+        plugin_root: loaded.pkg?.dir ?? resolveRoot(loaded.target),
         theme_files,
       }
     },
@@ -709,7 +742,7 @@ async function resolveExternalPlugins(list: ConfigPlugin.Origin[], wait: () => P
         id,
         module: EMPTY_TUI,
         origin,
-        theme_root: loaded.pkg?.dir ?? resolveRoot(loaded.target),
+        plugin_root: loaded.pkg?.dir ?? resolveRoot(loaded.target),
         theme_files,
       }
     },
@@ -967,7 +1000,7 @@ let loaded: Promise<void> | undefined
 let runtime: RuntimeState | undefined
 export const Slot = View
 
-export async function init(input: { api: HostPluginApi; config: TuiConfig.Resolved }) {
+export async function init(input: { api: HostPluginApi; config: TuiConfig.Resolved; dispose?: () => void }) {
   const cwd = process.cwd()
   if (loaded) {
     if (dir !== cwd) {
@@ -1014,15 +1047,17 @@ export async function dispose() {
   for (const plugin of queue) {
     await deactivatePluginEntry(state, plugin, false)
   }
+  state.dispose?.()
 }
 
-async function load(input: { api: Api; config: TuiConfig.Resolved }) {
+async function load(input: { api: Api; config: TuiConfig.Resolved; dispose?: () => void }) {
   const { api, config } = input
   const cwd = process.cwd()
   const slots = setupSlots(api)
   const next: RuntimeState = {
     directory: cwd,
     api,
+    dispose: input.dispose,
     slots,
     plugins: [],
     plugins_by_id: new Map(),

packages/opencode/src/cli/cmd/tui/util/audio.ts

@@ -0,0 +1,58 @@
+import { Audio, type AudioErrorContext, type AudioPlayOptions, type AudioSound, type AudioVoice } from "@opentui/core"
+import * as Log from "@opencode-ai/core/util/log"
+
+const log = Log.create({ service: "tui.audio" })
+
+let audio: Audio | null | undefined
+const sounds = new Map<string, Promise<AudioSound | null>>()
+
+function getAudio() {
+  if (audio !== undefined) return audio
+  try {
+    const next = Audio.create({ autoStart: false })
+    next.on("error", (error: Error, context: AudioErrorContext) => {
+      log.debug("tui audio error", { error, context })
+    })
+    audio = next
+    return next
+  } catch (error) {
+    log.debug("failed to create tui audio", { error })
+    audio = null
+    return null
+  }
+}
+
+export function loadSoundFile(file: string) {
+  const current = getAudio()
+  if (!current) return Promise.resolve(null)
+  const cached = sounds.get(file)
+  if (cached) return cached
+  const task = Bun.file(file)
+    .bytes()
+    .then((bytes) => current.loadSound(bytes))
+    .catch((error) => {
+      log.debug("failed to load tui sound", { file, error })
+      return null
+    })
+  sounds.set(file, task)
+  return task
+}
+
+export function play(sound: AudioSound, options?: AudioPlayOptions) {
+  const current = getAudio()
+  if (!current) return null
+  if (!current.isStarted() && !current.start()) return null
+  return current.play(sound, options)
+}
+
+export function stopVoice(voice: AudioVoice) {
+  return audio?.stopVoice(voice) ?? false
+}
+
+export function dispose() {
+  audio?.dispose()
+  audio = undefined
+  sounds.clear()
+}
+
+export * as TuiAudio from "./audio"

packages/opencode/src/util/filesystem.ts

@@ -1,10 +1,11 @@
 import { chmod, mkdir, readFile, stat as statFile, writeFile } from "fs/promises"
 import { createWriteStream, existsSync, statSync } from "fs"
 import { realpathSync } from "fs"
-import { dirname, join, relative, resolve as pathResolve, win32 } from "path"
+import { dirname, isAbsolute, join, relative, resolve as pathResolve, win32 } from "path"
 import { Readable } from "stream"
 import { pipeline } from "stream/promises"
 import { Glob } from "@opencode-ai/core/util/glob"
+import { fileURLToPath } from "url"
 
 // Fast sync version for metadata checks
 export async function exists(p: string): Promise<boolean> {
@@ -142,6 +143,12 @@ export function resolve(p: string): string {
   }
 }
 
+export function resolveFilePath(root: string, file: string): string {
+  const raw = file.startsWith("file://") ? fileURLToPath(file) : file
+  if (isAbsolute(raw)) return raw
+  return pathResolve(root, raw)
+}
+
 export function windowsPath(p: string): string {
   if (process.platform !== "win32") return p
   return (

packages/opencode/test/cli/cmd/tui/attention.test.ts

@@ -0,0 +1,484 @@
+import { describe, expect, test } from "bun:test"
+import type { AudioPlayOptions, AudioSound } from "@opentui/core"
+import { createTuiAttention } from "@/cli/cmd/tui/attention"
+import type { TuiConfig } from "@/cli/cmd/tui/config/tui"
+
+type FocusEvent = "focus" | "blur"
+
+type AttentionConfig = Pick<TuiConfig.Resolved, "attention">
+
+class FakeRenderer {
+  isDestroyed = false
+  notificationResult = true
+  notificationThrows = false
+  notifications: { message: string; title: string | undefined }[] = []
+  listeners: Record<FocusEvent, Set<() => void>> = {
+    focus: new Set(),
+    blur: new Set(),
+  }
+
+  on(event: FocusEvent, listener: () => void) {
+    this.listeners[event].add(listener)
+    return this
+  }
+
+  off(event: FocusEvent, listener: () => void) {
+    this.listeners[event].delete(listener)
+    return this
+  }
+
+  emit(event: FocusEvent) {
+    for (const listener of this.listeners[event]) listener()
+  }
+
+  listenerCount(event: FocusEvent) {
+    return this.listeners[event].size
+  }
+
+  triggerNotification(message: string, title?: string) {
+    if (this.notificationThrows) throw new Error("notification failed")
+    this.notifications.push({ message, title })
+    return this.notificationResult
+  }
+}
+
+class FakeAudioEngine {
+  loadResult: AudioSound | null = 1
+  playResult: number | null = 1
+  loadCalls = 0
+  playCalls = 0
+  volumes: (number | undefined)[] = []
+  loadPaths: string[] = []
+  rejectLoad = false
+  rejectPaths = new Set<string>()
+
+  async loadSoundFile(path: string) {
+    this.loadCalls += 1
+    this.loadPaths.push(path)
+    if (this.rejectLoad || this.rejectPaths.has(path)) throw new Error("decode failed")
+    return this.loadResult
+  }
+
+  play(_sound: AudioSound, options?: AudioPlayOptions) {
+    this.playCalls += 1
+    this.volumes.push(options?.volume)
+    return this.playResult
+  }
+}
+
+class FakeKV {
+  store: Record<string, unknown> = {}
+
+  get ready() {
+    return true
+  }
+
+  get<Value = unknown>(key: string, fallback?: Value) {
+    return (this.store[key] ?? fallback) as Value
+  }
+
+  set(key: string, value: unknown) {
+    this.store[key] = value
+  }
+}
+
+function config(attention: Partial<AttentionConfig["attention"]> = {}): AttentionConfig {
+  return {
+    attention: {
+      enabled: true,
+      notifications: true,
+      sound: true,
+      volume: 0.4,
+      sound_pack: "opencode.default",
+      sounds: {},
+      ...attention,
+    },
+  }
+}
+
+describe("createTuiAttention", () => {
+  test("defaults to sound always and notification blurred", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+
+    expect(await attention.notify({ message: "hello" })).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.playCalls).toBe(1)
+  })
+
+  test("supports blurred-only requests", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+
+    expect(await attention.notify({ message: "unknown", sound: { when: "blurred" } })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "focus_unknown",
+    })
+    renderer.emit("focus")
+    expect(await attention.notify({ message: "focused", sound: { when: "blurred" } })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "focused",
+    })
+    renderer.emit("blur")
+    expect(await attention.notify({ message: "blurred", sound: { when: "blurred" } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.playCalls).toBe(1)
+  })
+
+  test("supports focused-only requests", async () => {
+    const renderer = new FakeRenderer()
+    const attention = createTuiAttention({ renderer, config: config(), audio: new FakeAudioEngine() })
+
+    expect(await attention.notify({ message: "unknown", notification: { when: "focused" }, sound: false })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "focus_unknown",
+    })
+    renderer.emit("blur")
+    expect(await attention.notify({ message: "blurred", notification: { when: "focused" }, sound: false })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "blurred",
+    })
+    renderer.emit("focus")
+    expect(await attention.notify({ message: "focused", notification: { when: "focused" }, sound: false })).toEqual({
+      ok: true,
+      notification: true,
+      sound: false,
+    })
+    expect(renderer.notifications).toEqual([{ title: "opencode", message: "focused" }])
+  })
+
+  test("notification can deliver while focused when requested", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("focus")
+
+    expect(await attention.notify({ message: "hello", notification: { when: "always" } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.playCalls).toBe(1)
+    expect(renderer.notifications).toEqual([{ title: "opencode", message: "hello" }])
+  })
+
+  test("notifies while blurred", async () => {
+    const renderer = new FakeRenderer()
+    const attention = createTuiAttention({ renderer, config: config(), audio: new FakeAudioEngine() })
+    renderer.emit("blur")
+
+    expect(await attention.notify({ title: "opencode", message: "hello", sound: false })).toEqual({
+      ok: true,
+      notification: true,
+      sound: false,
+    })
+    expect(renderer.notifications).toEqual([{ title: "opencode", message: "hello" }])
+  })
+
+  test("when requested, blurred-only calls do not notify or play sound while focused", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("focus")
+
+    expect(await attention.notify({ message: "hello", sound: { when: "blurred" } })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "focused",
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.loadCalls).toBe(0)
+  })
+
+  test("can play sound always while notification is blurred-only", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("focus")
+
+    expect(
+      await attention.notify({
+        message: "hello",
+        sound: { name: "question" },
+      }),
+    ).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.playCalls).toBe(1)
+
+    renderer.emit("blur")
+    expect(
+      await attention.notify({
+        message: "hello again",
+        sound: { name: "question" },
+      }),
+    ).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(renderer.notifications).toEqual([{ title: "opencode", message: "hello again" }])
+  })
+
+  test("can disable notification per call while still playing sound", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+
+    expect(await attention.notify({ message: "hello", notification: false })).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.playCalls).toBe(1)
+  })
+
+  test("skips empty messages and disabled attention", async () => {
+    const empty = new FakeRenderer()
+    empty.emit("blur")
+    const disabled = new FakeRenderer()
+    disabled.emit("blur")
+
+    expect(await createTuiAttention({ renderer: empty, config: config() }).notify({ message: " \n " })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "empty_message",
+    })
+    expect(
+      await createTuiAttention({ renderer: disabled, config: config({ enabled: false }) }).notify({ message: "hello" }),
+    ).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "attention_disabled",
+    })
+  })
+
+  test("respects notification and sound config independently", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config({ notifications: false }), audio })
+    renderer.emit("blur")
+
+    expect(await attention.notify({ message: "hello", sound: true })).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.playCalls).toBe(1)
+
+    const soundDisabledRenderer = new FakeRenderer()
+    const soundDisabledAudio = new FakeAudioEngine()
+    const soundDisabled = createTuiAttention({
+      renderer: soundDisabledRenderer,
+      config: config({ sound: false }),
+      audio: soundDisabledAudio,
+    })
+    soundDisabledRenderer.emit("blur")
+
+    expect(await soundDisabled.notify({ message: "hello", sound: true })).toEqual({
+      ok: true,
+      notification: true,
+      sound: false,
+    })
+    expect(soundDisabledAudio.loadCalls).toBe(0)
+  })
+
+  test("loads audio lazily only for eligible sound requests", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+
+    await attention.notify({ message: "unknown", sound: { when: "blurred" } })
+    expect(audio.loadCalls).toBe(0)
+
+    renderer.emit("blur")
+    expect(await attention.notify({ message: "blurred", sound: { volume: 2 } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.loadCalls).toBe(1)
+    expect(audio.volumes).toEqual([1])
+  })
+
+  test("handles unavailable playback and delegates sound loading", async () => {
+    const unavailableRenderer = new FakeRenderer()
+    const unavailableAudio = new FakeAudioEngine()
+    unavailableAudio.playResult = null
+    const unavailable = createTuiAttention({ renderer: unavailableRenderer, config: config(), audio: unavailableAudio })
+    unavailableRenderer.emit("blur")
+
+    expect(await unavailable.notify({ message: "hello", sound: true })).toEqual({
+      ok: true,
+      notification: true,
+      sound: false,
+    })
+    expect(unavailableAudio.loadCalls).toBe(1)
+    expect(unavailableAudio.playCalls).toBe(1)
+
+    const repeatedRenderer = new FakeRenderer()
+    const repeatedAudio = new FakeAudioEngine()
+    const repeated = createTuiAttention({ renderer: repeatedRenderer, config: config(), audio: repeatedAudio })
+    repeatedRenderer.emit("blur")
+
+    await repeated.notify({ message: "one", sound: true })
+    await repeated.notify({ message: "two", sound: true })
+    expect(repeatedAudio.loadCalls).toBe(2)
+    expect(repeatedAudio.playCalls).toBe(2)
+  })
+
+  test("plays named sounds from the active sound pack", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("blur")
+
+    const dispose = attention.soundboard.registerPack({
+      id: "acme.soft",
+      name: "Soft Alerts",
+      sounds: {
+        question: "/tmp/question.mp3",
+      },
+    })
+
+    expect(attention.soundboard.activate("acme.soft")).toBe(true)
+    expect(attention.soundboard.current()).toBe("acme.soft")
+    expect(attention.soundboard.list()).toContainEqual({
+      id: "acme.soft",
+      name: "Soft Alerts",
+      active: true,
+      builtin: false,
+    })
+
+    expect(await attention.notify({ message: "question", sound: { name: "question" } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.loadPaths).toEqual(["/tmp/question.mp3"])
+
+    dispose()
+    expect(attention.soundboard.current()).toBe("opencode.default")
+  })
+
+  test("uses config sound overrides before active pack sounds and falls back on load failure", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    audio.rejectPaths.add("/tmp/bad-question.mp3")
+    const attention = createTuiAttention({
+      renderer,
+      config: config({ sounds: { question: "/tmp/bad-question.mp3" } }),
+      audio,
+    })
+    renderer.emit("blur")
+
+    attention.soundboard.registerPack({
+      id: "acme.soft",
+      sounds: {
+        question: "/tmp/good-question.mp3",
+      },
+    })
+    attention.soundboard.activate("acme.soft")
+
+    expect(await attention.notify({ message: "question", sound: { name: "question" } })).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(audio.loadPaths).toEqual(["/tmp/bad-question.mp3", "/tmp/good-question.mp3"])
+  })
+
+  test("persists activated sound pack in KV", () => {
+    const kv = new FakeKV()
+    const renderer = new FakeRenderer()
+    const attention = createTuiAttention({ renderer, config: config(), kv })
+
+    attention.soundboard.registerPack({ id: "acme.soft", sounds: { done: "/tmp/done.mp3" } })
+
+    expect(attention.soundboard.activate("missing", { persist: true })).toBe(false)
+    expect(kv.store.attention_sound_pack).toBeUndefined()
+    expect(attention.soundboard.activate("acme.soft", { persist: true })).toBe(true)
+    expect(kv.store.attention_sound_pack).toBe("acme.soft")
+
+    const next = createTuiAttention({ renderer: new FakeRenderer(), config: config(), kv })
+    next.soundboard.registerPack({ id: "acme.soft", sounds: { done: "/tmp/done.mp3" } })
+    expect(next.soundboard.current()).toBe("acme.soft")
+  })
+
+  test("does not throw for notification or sound failures", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    renderer.notificationThrows = true
+    audio.rejectLoad = true
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("blur")
+
+    expect(await attention.notify({ message: "hello", sound: true })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+    })
+  })
+
+  test("strips unsafe notification text", async () => {
+    const renderer = new FakeRenderer()
+    const attention = createTuiAttention({ renderer, config: config(), audio: new FakeAudioEngine() })
+    renderer.emit("blur")
+
+    await attention.notify({
+      title: "\u001b[31m danger\n title\u0007",
+      message: "\u001b[32m hello\n world\u0000",
+    })
+
+    expect(renderer.notifications).toEqual([{ title: "danger title", message: "hello world" }])
+  })
+
+  test("disposes renderer listeners", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudioEngine()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("blur")
+    await attention.notify({ message: "hello", sound: true })
+
+    expect(renderer.listenerCount("focus")).toBe(1)
+    expect(renderer.listenerCount("blur")).toBe(1)
+
+    attention.dispose()
+    renderer.isDestroyed = true
+
+    expect(renderer.listenerCount("focus")).toBe(0)
+    expect(renderer.listenerCount("blur")).toBe(0)
+    expect(audio.loadCalls).toBe(1)
+    expect(await attention.notify({ message: "hello" })).toEqual({
+      ok: false,
+      notification: false,
+      sound: false,
+      skipped: "renderer_destroyed",
+    })
+  })
+})

packages/opencode/test/cli/cmd/tui/notifications.test.ts

@@ -0,0 +1,267 @@
+import { describe, expect, test } from "bun:test"
+import Notifications from "@/cli/cmd/tui/feature-plugins/system/notifications"
+import type { Event, PermissionRequest, QuestionRequest, Session } from "@opencode-ai/sdk/v2"
+import type { TuiAttentionNotifyInput } from "@opencode-ai/plugin/tui"
+import { createTuiPluginApi } from "../../../fixture/tui-plugin"
+
+async function setup() {
+  const notifications: TuiAttentionNotifyInput[] = []
+  const handlers = new Map<Event["type"], ((event: Event) => void)[]>()
+  const session = (id: string, title: string, parentID?: string): Session => ({
+    id,
+    title,
+    slug: id,
+    projectID: "project",
+    directory: "/workspace",
+    ...(parentID && { parentID }),
+    version: "0.0.0-test",
+    time: { created: 0, updated: 0 },
+  })
+  const sessions: Record<string, Session> = {
+    session: session("session", "Demo session"),
+    subagent: session("subagent", "Subagent session", "session"),
+    abort: session("abort", "Abort session"),
+    timeout: session("timeout", "Timeout session"),
+  }
+
+  await Notifications.tui(
+    createTuiPluginApi({
+      attention: {
+        async notify(input) {
+          notifications.push(input)
+          return { ok: true, notification: true, sound: true }
+        },
+      },
+      event: {
+        on: <Type extends Event["type"]>(type: Type, handler: (event: Extract<Event, { type: Type }>) => void) => {
+          const list = handlers.get(type) ?? []
+          const wrapped = handler as (event: Event) => void
+          list.push(wrapped)
+          handlers.set(type, list)
+          return () => {
+            handlers.set(
+              type,
+              (handlers.get(type) ?? []).filter((item) => item !== wrapped),
+            )
+          }
+        },
+      },
+      state: {
+        session: {
+          get: (sessionID: string) => sessions[sessionID],
+        },
+      },
+    }),
+    undefined,
+    {} as never,
+  )
+
+  return {
+    notifications,
+    emit(event: Event) {
+      for (const handler of handlers.get(event.type) ?? []) handler(event)
+    },
+  }
+}
+
+function question(id: string, sessionID = "session"): QuestionRequest {
+  return {
+    id,
+    sessionID,
+    questions: [],
+  }
+}
+
+function permission(id: string, sessionID = "session"): PermissionRequest {
+  return {
+    id,
+    sessionID,
+    permission: "edit",
+    patterns: [],
+    metadata: {},
+    always: [],
+  }
+}
+
+const questionNotification: TuiAttentionNotifyInput = {
+  title: "Demo session",
+  message: "Question needs input",
+  notification: { when: "blurred" },
+  sound: { name: "question", when: "always" },
+}
+
+const permissionNotification: TuiAttentionNotifyInput = {
+  title: "Demo session",
+  message: "Permission needs input",
+  notification: { when: "blurred" },
+  sound: { name: "permission", when: "always" },
+}
+
+describe("internal notifications TUI plugin", () => {
+  test("notifies for question and permission requests with blurred notifications and always-on sounds", async () => {
+    const harness = await setup()
+
+    harness.emit({ id: "event-1", type: "question.asked", properties: question("question-1") })
+    harness.emit({ id: "event-2", type: "permission.asked", properties: permission("permission-1") })
+
+    expect(harness.notifications).toEqual([questionNotification, permissionNotification])
+  })
+
+  test("dedupes pending questions and permissions until they are resolved", async () => {
+    const harness = await setup()
+
+    harness.emit({ id: "event-1", type: "question.asked", properties: question("question-1") })
+    harness.emit({ id: "event-2", type: "question.asked", properties: question("question-1") })
+    harness.emit({
+      id: "event-3",
+      type: "question.replied",
+      properties: { sessionID: "session", requestID: "question-1", answers: [] },
+    })
+    harness.emit({ id: "event-4", type: "question.asked", properties: question("question-1") })
+
+    harness.emit({ id: "event-5", type: "permission.asked", properties: permission("permission-1") })
+    harness.emit({ id: "event-6", type: "permission.asked", properties: permission("permission-1") })
+    harness.emit({
+      id: "event-7",
+      type: "permission.replied",
+      properties: { sessionID: "session", requestID: "permission-1", reply: "once" },
+    })
+    harness.emit({ id: "event-8", type: "permission.asked", properties: permission("permission-1") })
+
+    expect(harness.notifications).toEqual([
+      questionNotification,
+      questionNotification,
+      permissionNotification,
+      permissionNotification,
+    ])
+  })
+
+  test("notifies when an active session becomes idle and suppresses no-op idle", async () => {
+    const harness = await setup()
+
+    harness.emit({
+      id: "event-1",
+      type: "session.status",
+      properties: { sessionID: "session", status: { type: "idle" } },
+    })
+    harness.emit({
+      id: "event-2",
+      type: "session.status",
+      properties: { sessionID: "session", status: { type: "busy" } },
+    })
+    harness.emit({
+      id: "event-3",
+      type: "session.status",
+      properties: { sessionID: "session", status: { type: "idle" } },
+    })
+
+    expect(harness.notifications).toEqual([
+      {
+        title: "Demo session",
+        message: "Session done",
+        notification: { when: "blurred" },
+        sound: { name: "done", when: "always" },
+      },
+    ])
+  })
+
+  test("uses sound-only notifications and subagent_done sound for subagent sessions", async () => {
+    const harness = await setup()
+
+    harness.emit({ id: "event-1", type: "question.asked", properties: question("question-1", "subagent") })
+    harness.emit({
+      id: "event-2",
+      type: "session.status",
+      properties: { sessionID: "subagent", status: { type: "busy" } },
+    })
+    harness.emit({
+      id: "event-3",
+      type: "session.status",
+      properties: { sessionID: "subagent", status: { type: "idle" } },
+    })
+
+    expect(harness.notifications).toEqual([
+      {
+        title: "Subagent session",
+        message: "Question needs input",
+        notification: false,
+        sound: { name: "question", when: "always" },
+      },
+      {
+        title: "Subagent session",
+        message: "Session done",
+        notification: false,
+        sound: { name: "subagent_done", when: "always" },
+      },
+    ])
+  })
+
+  test("notifies session errors once and suppresses the following idle done notification", async () => {
+    const harness = await setup()
+
+    harness.emit({
+      id: "event-1",
+      type: "session.status",
+      properties: { sessionID: "session", status: { type: "busy" } },
+    })
+    harness.emit({
+      id: "event-2",
+      type: "session.error",
+      properties: { sessionID: "session", error: { name: "UnknownError", data: { message: "boom" } } },
+    })
+    harness.emit({
+      id: "event-3",
+      type: "session.status",
+      properties: { sessionID: "session", status: { type: "idle" } },
+    })
+
+    expect(harness.notifications).toEqual([
+      {
+        title: "Demo session",
+        message: "Session error",
+        notification: { when: "blurred" },
+        sound: { name: "error", when: "always" },
+      },
+    ])
+  })
+
+  test("special-cases aborts and model response timeouts", async () => {
+    const harness = await setup()
+
+    harness.emit({
+      id: "event-1",
+      type: "session.status",
+      properties: { sessionID: "abort", status: { type: "busy" } },
+    })
+    harness.emit({
+      id: "event-2",
+      type: "session.error",
+      properties: { sessionID: "abort", error: { name: "MessageAbortedError", data: { message: "Aborted" } } },
+    })
+    harness.emit({
+      id: "event-3",
+      type: "session.status",
+      properties: { sessionID: "timeout", status: { type: "busy" } },
+    })
+    harness.emit({
+      id: "event-4",
+      type: "session.error",
+      properties: { sessionID: "timeout", error: { name: "UnknownError", data: { message: "SSE read timed out" } } },
+    })
+
+    expect(harness.notifications).toEqual([
+      {
+        title: "Abort session",
+        message: "Session aborted",
+        notification: { when: "blurred" },
+        sound: { name: "error", when: "always" },
+      },
+      {
+        title: "Timeout session",
+        message: "Model stopped responding",
+        notification: { when: "blurred" },
+        sound: { name: "error", when: "always" },
+      },
+    ])
+  })
+})

packages/opencode/test/cli/run/runtime.boot.test.ts

@@ -1,14 +1,9 @@
 import { afterEach, describe, expect, mock, spyOn, test } from "bun:test"
-import type { KeyEvent, Renderable } from "@opentui/core"
-import type { Binding } from "@opentui/keymap"
-import { createBindingLookup } from "@opentui/keymap/extras"
 import { OpencodeClient, type Provider } from "@opencode-ai/sdk/v2"
 import { TuiConfig, type Resolved } from "@/cli/cmd/tui/config/tui"
 import { formatBindings } from "@/cli/cmd/run/keymap.shared"
-import { TuiKeybind } from "@/cli/cmd/tui/config/keybind"
 import { resolveDiffStyle, resolveFooterKeybinds, resolveModelInfo } from "@/cli/cmd/run/runtime.boot"
-
-type RunBinding = Binding<Renderable, KeyEvent>
+import { createTuiResolvedConfig } from "../../fixture/tui-runtime"
 
 function model(id: string, providerID: string, context: number, variants?: Record<string, Record<string, never>>) {
   return {
@@ -61,45 +56,37 @@ function model(id: string, providerID: string, context: number, variants?: Recor
   }
 }
 
-function bindings(...keys: string[]) {
-  return keys.map((key) => ({ key }))
-}
-
 function config(input?: {
   leader?: string
   leaderTimeout?: number
   diff_style?: "auto" | "stacked"
   bindings?: Partial<{
-    commandList: RunBinding[]
-    variantCycle: RunBinding[]
-    interrupt: RunBinding[]
-    historyPrevious: RunBinding[]
-    historyNext: RunBinding[]
-    inputClear: RunBinding[]
-    inputSubmit: RunBinding[]
-    inputNewline: RunBinding[]
+    commandList: string[]
+    variantCycle: string[]
+    interrupt: string[]
+    historyPrevious: string[]
+    historyNext: string[]
+    inputClear: string[]
+    inputSubmit: string[]
+    inputNewline: string[]
   }>
 }): Resolved {
   const bind = input?.bindings
-  const keybinds = TuiKeybind.Keybinds.parse({
-    ...(input?.leader && { leader: input.leader }),
-    ...(bind?.commandList && { command_list: bind.commandList }),
-    ...(bind?.variantCycle && { variant_cycle: bind.variantCycle }),
-    ...(bind?.interrupt && { session_interrupt: bind.interrupt }),
-    ...(bind?.historyPrevious && { history_previous: bind.historyPrevious }),
-    ...(bind?.historyNext && { history_next: bind.historyNext }),
-    ...(bind?.inputClear && { input_clear: bind.inputClear }),
-    ...(bind?.inputSubmit && { input_submit: bind.inputSubmit }),
-    ...(bind?.inputNewline && { input_newline: bind.inputNewline }),
-  })
-  return {
+  return createTuiResolvedConfig({
     diff_style: input?.diff_style,
-    keybinds: createBindingLookup(TuiKeybind.toBindingConfig(keybinds), {
-      commandMap: TuiKeybind.CommandMap,
-      bindingDefaults: TuiKeybind.bindingDefaults(),
-    }),
-    leader_timeout: input?.leaderTimeout ?? 2000,
-  }
+    leader_timeout: input?.leaderTimeout,
+    keybinds: {
+      ...(input?.leader && { leader: input.leader }),
+      ...(bind?.commandList && { command_list: bind.commandList }),
+      ...(bind?.variantCycle && { variant_cycle: bind.variantCycle }),
+      ...(bind?.interrupt && { session_interrupt: bind.interrupt }),
+      ...(bind?.historyPrevious && { history_previous: bind.historyPrevious }),
+      ...(bind?.historyNext && { history_next: bind.historyNext }),
+      ...(bind?.inputClear && { input_clear: bind.inputClear }),
+      ...(bind?.inputSubmit && { input_submit: bind.inputSubmit }),
+      ...(bind?.inputNewline && { input_newline: bind.inputNewline }),
+    },
+  })
 }
 
 describe("run runtime boot", () => {
@@ -112,14 +99,14 @@ describe("run runtime boot", () => {
       config({
         leader: "ctrl+g",
         bindings: {
-          commandList: bindings("ctrl+p"),
-          variantCycle: bindings("ctrl+t", "alt+t"),
-          interrupt: bindings("ctrl+c"),
-          historyPrevious: bindings("k"),
-          historyNext: bindings("j"),
-          inputClear: bindings("ctrl+l"),
-          inputSubmit: bindings("ctrl+s"),
-          inputNewline: bindings("alt+return"),
+          commandList: ["ctrl+p"],
+          variantCycle: ["ctrl+t", "alt+t"],
+          interrupt: ["ctrl+c"],
+          historyPrevious: ["k"],
+          historyNext: ["j"],
+          inputClear: ["ctrl+l"],
+          inputSubmit: ["ctrl+s"],
+          inputNewline: ["alt+return"],
         },
       }),
     )

packages/opencode/test/cli/tui/plugin-loader.test.ts

@@ -3,6 +3,7 @@ import fs from "fs/promises"
 import path from "path"
 import { pathToFileURL } from "url"
 import { createTestKeymap } from "@opentui/keymap/testing"
+import type { TuiAttentionSoundPack } from "@opencode-ai/plugin/tui"
 import { tmpdir } from "../../fixture/fixture"
 import { createTuiPluginApi } from "../../fixture/tui-plugin"
 import { createTuiResolvedConfig, mockTuiRuntime } from "../../fixture/tui-runtime"
@@ -854,6 +855,85 @@ test("plugin keymap proxy preserves real keymap receiver", async () => {
   }
 })
 
+test("auto-disposes plugin attention sound packs and resolves sound paths", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      const file = path.join(dir, "attention-soundpack-plugin.ts")
+      const spec = pathToFileURL(file).href
+      const absolute = path.join(dir, "sounds", "default.mp3")
+      const url = pathToFileURL(path.join(dir, "sounds", "error.mp3")).href
+
+      await Bun.write(
+        file,
+        `export default {
+  id: "demo.attention.soundpack",
+  tui: async (api) => {
+    api.attention.soundboard.registerPack({
+      id: "demo.pack",
+      sounds: {
+        default: ${JSON.stringify(absolute)},
+        question: "sounds/question.mp3",
+        done: "  sounds/done.mp3  ",
+        subagent_done: "sounds/subagent-done.mp3",
+        error: ${JSON.stringify(url)},
+        nope: "sounds/nope.mp3",
+        permission: "",
+      },
+    })
+  },
+}
+`,
+      )
+
+      return { spec }
+    },
+  })
+
+  const packs: TuiAttentionSoundPack[] = []
+  let dropped = 0
+  const attention = {
+    soundboard: {
+      registerPack(pack: TuiAttentionSoundPack) {
+        packs.push(pack)
+        return () => {
+          dropped += 1
+        }
+      },
+    },
+  }
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => tmp.path)
+
+  try {
+    await TuiPluginRuntime.init({
+      api: createTuiPluginApi({ attention }),
+      config: createTuiResolvedConfig({
+        plugin: [tmp.extra.spec],
+        plugin_origins: [{ spec: tmp.extra.spec, scope: "local", source: path.join(tmp.path, "tui.json") }],
+      }),
+    })
+
+    expect(packs).toEqual([
+      {
+        id: "demo.pack",
+        sounds: {
+          default: path.join(tmp.path, "sounds", "default.mp3"),
+          question: path.join(tmp.path, "sounds", "question.mp3"),
+          done: path.join(tmp.path, "sounds", "done.mp3"),
+          subagent_done: path.join(tmp.path, "sounds", "subagent-done.mp3"),
+          error: path.join(tmp.path, "sounds", "error.mp3"),
+        },
+      },
+    ])
+    expect(dropped).toBe(0)
+  } finally {
+    await TuiPluginRuntime.dispose()
+    expect(dropped).toBe(1)
+    cwd.mockRestore()
+    wait.mockRestore()
+  }
+})
+
 test("auto-disposes plugin keymap transformers", async () => {
   await using tmp = await tmpdir({
     init: async (dir) => {

packages/opencode/test/config/tui.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, expect, test } from "bun:test"
 import path from "path"
 import fs from "fs/promises"
+import { pathToFileURL } from "url"
 import { provideTestInstance, tmpdir } from "../fixture/fixture"
 import { InstanceRuntime } from "@/project/instance-runtime"
 import { TuiConfig } from "../../src/cli/cmd/tui/config/tui"
@@ -142,6 +143,59 @@ test("loads tui config with the same precedence order as server config paths", a
   expect(config.diff_style).toBe("stacked")
 })
 
+test("resolves attention config defaults and overrides", async () => {
+  await using defaults = await tmpdir()
+  expect((await getTuiConfig(defaults.path)).attention).toEqual({
+    enabled: false,
+    notifications: true,
+    sound: true,
+    volume: 0.4,
+    sound_pack: "opencode.default",
+    sounds: {},
+  })
+
+  await using overridden = await tmpdir({
+    init: async (dir) => {
+      await Bun.write(
+        path.join(dir, "tui.json"),
+        JSON.stringify(
+          {
+            attention: {
+              enabled: false,
+              notifications: false,
+              sound: false,
+              volume: 0.7,
+              sound_pack: "acme.soft",
+              sounds: {
+                default: path.join(dir, "default.mp3"),
+                question: pathToFileURL(path.join(dir, "question.mp3")).href,
+                error: "./error.mp3",
+                subagent_done: "./subagent-done.mp3",
+              },
+            },
+          },
+          null,
+          2,
+        ),
+      )
+    },
+  })
+
+  expect((await getTuiConfig(overridden.path)).attention).toEqual({
+    enabled: false,
+    notifications: false,
+    sound: false,
+    volume: 0.7,
+    sound_pack: "acme.soft",
+    sounds: {
+      default: path.join(overridden.path, "default.mp3"),
+      question: path.join(overridden.path, "question.mp3"),
+      error: path.join(overridden.path, "error.mp3"),
+      subagent_done: path.join(overridden.path, "subagent-done.mp3"),
+    },
+  })
+})
+
 test("migrates tui-specific keys from opencode.json when tui.json does not exist", async () => {
   await using tmp = await tmpdir({
     init: async (dir) => {

packages/opencode/test/fixture/tui-plugin.ts

@@ -12,6 +12,10 @@ type Count = {
   command_drop: number
 }
 
+type AttentionOpts = Partial<Omit<HostPluginApi["attention"], "soundboard">> & {
+  soundboard?: Partial<HostPluginApi["attention"]["soundboard"]>
+}
+
 function themeCurrent(): HostPluginApi["theme"]["current"] {
   const a = RGBA.fromInts(0, 120, 240)
   const b = RGBA.fromInts(120, 120, 120)
@@ -83,6 +87,8 @@ function themeCurrent(): HostPluginApi["theme"]["current"] {
 type Opts = {
   client?: HostPluginApi["client"] | (() => HostPluginApi["client"])
   renderer?: HostPluginApi["renderer"]
+  attention?: AttentionOpts
+  event?: HostPluginApi["event"]
   count?: Count
   keymap?: HostPluginApi["keymap"]
   tuiConfig?: Partial<HostPluginApi["tuiConfig"]>
@@ -183,6 +189,17 @@ export function createTuiPluginApi(opts: Opts = {}): HostPluginApi {
         return opts.app?.version ?? "0.0.0-test"
       },
     },
+    attention: {
+      async notify(input) {
+        return opts.attention?.notify?.(input) ?? { ok: false, notification: false, sound: false }
+      },
+      soundboard: {
+        registerPack: (pack) => opts.attention?.soundboard?.registerPack?.(pack) ?? (() => {}),
+        activate: (id, options) => opts.attention?.soundboard?.activate?.(id, options) ?? false,
+        current: () => opts.attention?.soundboard?.current?.() ?? "opencode.default",
+        list: () => opts.attention?.soundboard?.list?.() ?? [],
+      },
+    },
     keys: {
       formatSequence: () => "",
       formatBindings: () => undefined,
@@ -190,7 +207,7 @@ export function createTuiPluginApi(opts: Opts = {}): HostPluginApi {
     get client() {
       return client()
     },
-    event: {
+    event: opts.event ?? {
       on: () => {
         if (count) count.event_add += 1
         return () => {

packages/opencode/test/fixture/tui-runtime.ts

@@ -5,7 +5,8 @@ import { TuiConfig } from "../../src/cli/cmd/tui/config/tui"
 import { TuiKeybind } from "../../src/cli/cmd/tui/config/keybind"
 
 type PluginSpec = string | [string, Record<string, unknown>]
-type ResolvedInput = Omit<TuiConfig.Resolved, "keybinds" | "leader_timeout"> & {
+type ResolvedInput = Omit<TuiConfig.Resolved, "attention" | "keybinds" | "leader_timeout"> & {
+  attention?: Partial<TuiConfig.Resolved["attention"]>
   keybinds?: Partial<TuiKeybind.Keybinds>
   leader_timeout?: number
 }
@@ -22,6 +23,15 @@ export function createTuiResolvedConfig(input: ResolvedInput = {}): TuiConfig.Re
   const keybinds = TuiKeybind.Keybinds.parse(input.keybinds ?? {})
   return {
     ...input,
+    attention: {
+      enabled: false,
+      notifications: true,
+      sound: true,
+      volume: 0.4,
+      sound_pack: "opencode.default",
+      sounds: {},
+      ...input.attention,
+    },
     keybinds: createTuiResolvedKeybinds(keybinds),
     leader_timeout: input.leader_timeout ?? 2000,
   }