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

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"