opencode-tmux-callback

OpenCode plugin that converts tmux-task observer callbacks into visible session updates inside TUI / serve-hosted sessions.

It solves the "main session launched a tmux task, but cannot tell whether it is running, stalled, blocked, failed, or done" gap without adding network RPC between the main session and the tmux worker.

What It Does

• injects TMUX_TASK_NOTIFY_SCRIPT into shell / bash tool executions automatically
• creates a per-session notify script that observer sidecars can call
• appends callback events into a project-local inbox under .opencode/tmux-task-callback/
• watches that inbox inside the OpenCode process
• injects visible callback messages back into the originating session

The underlying status source remains the filesystem:

• tmux-observer.state.json
• tmux-observer.final.json
• tmux-observer.events.jsonl

This plugin only turns those facts into an active callback channel for the session host.

Installation

Add it to your OpenCode config:

{
  "plugin": [
    "[email protected]"
  ]
}

Callback Flow

main session shell tool
  -> plugin shell.env injects TMUX_TASK_NOTIFY_SCRIPT
  -> tmux observer calls notify script on status transition
  -> notify script appends JSONL event to project inbox
  -> plugin watcher consumes inbox event
  -> plugin injects callback into the same session

Default Message Policy

• running: visible callback note via session/:id/message with noReply: true
• done, blocked, failed, stalled（含 stall=suspect）: actionable callback via session/:id/prompt_async

Actionable callbacks intentionally trigger a fresh model round so the main session can immediately inspect the callback's run_dir and continue handling, instead of only showing a queued note. stalled:suspect 也会触发自动处理，因为“疑似卡住”本身就是需要宿主会话立即判断的异常事件。

当项目同时安装 opencode-tool-liveness 与 opencode-stability-guard 时，actionable callback 还会附带 .opencode/tool-liveness/{state,guard}.json 的摘要，帮助主会话在进入 run_dir 前先看到最近错误、孤儿 pending 和最近恢复动作。

Files Written

• <project>/.opencode/tmux-task-callback/events.jsonl
• <project>/.opencode/tmux-task-callback/notify/<session-id>.sh

Compatibility

This plugin is host-side only. It works with:

• root-repo TUI sessions that offload to tmux -> gpt-supervisor
• serve-hosted sessions where the session remains alive after offload

Heartbeat runner flows can continue to use wake-runner.sh; both mechanisms can coexist because they share the same observer callback instruction format:

• tmux task running(...)
• tmux task stalled(...)
• tmux task failed(...)
• tmux task blocked(...)
• tmux task done(...)