Get notified when OpenCode finishes (macOS)

OpenCode's TUI happily works through a long task and then sits there, done, while you're in another window. Here are your options, from a one-line shell trick to a full watcher, honestly compared.

Option 1 — shell chaining (one-shot runs, free)

If you run OpenCode non-interactively with opencode run, the shell already knows when it's done. No config needed:

opencode run "refactor the parser" ; afplay /System/Library/Sounds/Glass.aiff

Honest limits: this only works for one-shot prompts — in an interactive TUI session the process doesn't exit between turns, so nothing plays. And the sound tells you nothing about whether it worked.

Option 2 — a tiny official plugin (DIY, free)

OpenCode loads local plugins from ~/.config/opencode/plugins/ (official docs). The session.idle event fires when a session stops working — a minimal plugin that plays a sound:

// ~/.config/opencode/plugins/notify.ts
export const Notify = async ({ $ }) => {
  return {
    event: async ({ event }) => {
      if (event.type === "session.idle") {
        await $`afplay /System/Library/Sounds/Glass.aiff`
      }
    },
  }
}

Restart OpenCode after adding it. Honest limits: one sound for every idle — no distinction between finished, failed, and waiting-for-permission (you'd handle permission.asked separately for that); and nothing tells you which session when you run several.

Option 3 — a watcher that treats OpenCode as one of your agents

Sleepwing (free beta) writes one owned plugin to ~/.config/opencode/plugins/perch.ts that listens to OpenCode's official local events — session.status, session.idle, and permission.asked — reversibly: it never overwrites an unrelated existing perch.ts, and removal deletes only a file carrying the Sleepwing ownership marker. It puts one pet on your desktop that:

distinguishes working / waiting-for-you / finished / failed, per session;
brings you back to the exact terminal tab with one click, and covers your other agents too (Claude Code, Cursor, Codex, Gemini CLI, TRAE, pi) with the same pet;
turns agent work time into small real breaks — paused the moment OpenCode waits on you;
makes zero outbound network requests — no account, no telemetry; events are reduced locally so prompts, code, and paths never leave: only the provider, an opaque session ID, the phase, a timestamp, a bounded task label, and a local resume route remain. Grep the source.

Verified on OpenCode 1.18.4 for plugin loading and working traffic; restart OpenCode after connecting.

⬇ Download the notarized beta (macOS 14+, Apple Silicon)

Pick by situation: scripted one-shot opencode run commands → shell chaining is enough, don't install anything. Comfortable with TypeScript and only OpenCode → the DIY plugin is genuinely good, OpenCode's plugin API is pleasant. Multiple agents a day, or you want failed and waiting-for-you to sound different from done → that's what Sleepwing is for.

中文速览

OpenCode 跑长任务结束时不会主动提醒你。方案：一次性任务直接用 shell 串联 opencode run "…" ; afplay …（交互式 TUI 无效）；或在 ~/.config/opencode/plugins/ 放一个小插件，监听官方 session.idle 事件播音效（上面有例子，加完重启 OpenCode）；或用 Sleepwing 桌宠——写入一个可逆的专属插件 perch.ts，监听 session.status/session.idle/permission.asked，区分「工作中/等你/完成/失败」，一键跳回终端标签页，还同时看管 Claude Code、Cursor、Codex 等其他 Agent。事件在本地裁剪，提示词和代码不会离开本机、零外联。免费 Beta。