opencode-status-tab 0.4.0

package/README.md

@@ -0,0 +1,74 @@
+# opencode-zellij-indicator
+
+**Know which of your OpenCode agents needs you — without switching tabs.**
+
+When you run several [OpenCode](https://opencode.ai) sessions across
+[Zellij](https://zellij.dev) tabs, they all look identical. You can't see which
+one is still grinding, which is silently waiting for you to approve something,
+and which finished five minutes ago. So you keep clicking through them.
+
+## The four states
+
+| Icon | When | What it means for you |
+|------|------|-----------------------|
+| ⏳ | working | OpenCode is busy — ignore it for now |
+| ❓ | needs you | blocked on a permission prompt or a question — go unblock it |
+| 🔔 | done, unseen | it finished while you were away — go check the result |
+| ✅ | done, seen | finished, and you've already looked |
+
+## Example
+
+![OpenCode status icons on each Zellij tab](docs/tab-states.png)
+
+## Naming
+
+OpenCode gives each session an auto-generated title, and the plugin uses that as the Zellij tab name. To change it, run OpenCode's built-in `/rename` slash command.
+
+## Install
+
+**1. Install Zellij and OpenCode.**  
+Requires Zellij ≥ 0.44.0
+
+**2. Enable the plugin.**   
+Add the following to your `opencode.json`
+```json
+{
+  "plugin": ["opencode-zellij-indicator"]
+}
+```
+Outside Zellij the plugin does nothing (it exits immediately), so it's safe to leave enabled everywhere at no cost.
+
+**3. Run OpenCode inside Zellij.**
+```sh
+zellij      # opens the Zellij workspace
+opencode    # run this inside Zellij
+```
+
+That single tab now shows OpenCode's status. To feel the point of the plugin,
+open more tabs and run OpenCode in each — press `Ctrl t` then `n` for a new
+tab (`Ctrl t` then the arrow keys to switch between them).
+
+### Agent Setup 
+Prefer to let an agent do it? Copy this into your prompt:
+```
+Fetch https://raw.githubusercontent.com/aidan-gallagher/opencode-zellij-indicator/master/docs/agent-setup.md and follow the setup steps.
+```
+
+## Configuration
+
+Set these as [environment variables](https://askubuntu.com/questions/730/how-do-i-set-environment-variables) before launching OpenCode.
+
+### Stopwatch
+
+`OPENCODE_ZELLIJ_STOPWATCH=1`   
+Show how long a session has been running. After a minute, the elapsed minutes appear next to the icon:
+
+![Stopwatch on a running tab](docs/stopwatch.png)
+
+### Sound
+
+`OPENCODE_ZELLIJ_SOUND=1`   
+Play a sound when OpenCode finishes in a background tab.
+
+`OPENCODE_ZELLIJ_SOUND_CMD="pw-play ~/alert.wav"`  
+Override the default sound with your own command.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "opencode-status-tab",
+  "version": "0.4.0",
+  "description": "Show each opencode session's status (running / needs-you / done-unseen / done-seen) and title on its Zellij tab",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "sounds",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "zellij",
+    "terminal",
+    "tab",
+    "status"
+  ],
+  "author": "Aidan Gallagher",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aidan-gallagher/opencode-zellij-indicator.git"
+  },
+  "homepage": "https://github.com/aidan-gallagher/opencode-zellij-indicator#readme",
+  "bugs": {
+    "url": "https://github.com/aidan-gallagher/opencode-zellij-indicator/issues"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.4.8",
+    "@types/node": "^22",
+    "typescript": "^5"
+  }
+}

package/src/config.ts

@@ -0,0 +1,46 @@
+// ---------------------------------------------------------------------------
+// Environment-derived configuration + shared logging.
+//
+// Everything here is read once at module load from env vars, has no runtime
+// state, and depends on nothing else in the plugin.
+// ---------------------------------------------------------------------------
+
+export type Phase = "running" | "permission" | "done"
+
+const env = (key: string, def: string) => {
+  const v = process.env[key]
+  return v && v.length > 0 ? v : def
+}
+
+// The four icons. Defaults: hourglass = busy, question = needs you, bell =
+// finished and wants your eyes, tick = you've since reviewed it. Override any of
+// them with env vars for other glyphs.
+export const ICON_RUNNING = env("OPENCODE_ZELLIJ_ICON_RUNNING", "⏳")
+export const ICON_PERMISSION = env("OPENCODE_ZELLIJ_ICON_PERMISSION", "❓")
+export const ICON_UNSEEN = env("OPENCODE_ZELLIJ_ICON_ATTENTION", "🔔")
+export const ICON_SEEN = env("OPENCODE_ZELLIJ_ICON_SEEN", "✅")
+export const ALL_ICONS = [
+  ICON_RUNNING,
+  ICON_PERMISSION,
+  ICON_UNSEEN,
+  ICON_SEEN,
+].filter((i) => i.length)
+
+export const STOPWATCH_ENABLED = process.env.OPENCODE_ZELLIJ_STOPWATCH === "1"
+
+const DEFAULT_POLL_MS = 1500
+const pollParsed = Number.parseInt(env("OPENCODE_ZELLIJ_POLL_MS", String(DEFAULT_POLL_MS)), 10)
+export const POLL_MS = Number.isFinite(pollParsed) ? pollParsed : DEFAULT_POLL_MS
+
+// Tools that block waiting for the user (opencode's interactive question / the
+// plan-mode "switch to build agent?" prompt). While one of these runs, the
+// session is really waiting on you, so show the permission icon rather than the
+// running one.
+export const ASK_TOOLS = new Set(["question", "plan_exit"])
+
+// Debug logging (set OPENCODE_ZELLIJ_DEBUG=1). Goes to opencode's server log,
+// not the TUI. Invaluable for diagnosing "why isn't my tab renaming?".
+const DEBUG = process.env.OPENCODE_ZELLIJ_DEBUG === "1"
+export const log = (msg: string) => {
+  if (DEBUG) console.error(`[zellij-indicator] ${msg}`)
+}

package/src/format.ts

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// Pure presentation helpers: turning state into the strings we render on the
+// tab. No runtime state, no side effects, no `$`.
+// ---------------------------------------------------------------------------
+
+import {
+  ALL_ICONS,
+  ICON_PERMISSION,
+  ICON_RUNNING,
+  ICON_SEEN,
+  ICON_UNSEEN,
+  STOPWATCH_ENABLED,
+  type Phase,
+} from "./config"
+
+// Strip any trailing status icon(s) so we recover the clean base tab name.
+export function stripIcons(s: string): string {
+  let out = s.trimEnd()
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const ic of ALL_ICONS) {
+      if (out.endsWith(ic)) {
+        out = out.slice(0, -ic.length).trimEnd()
+        changed = true
+      }
+    }
+  }
+  return out
+}
+
+export function iconFor(phase: Phase, seen: boolean): string {
+  if (phase === "running") return ICON_RUNNING
+  if (phase === "permission") return ICON_PERMISSION
+  return seen ? ICON_SEEN : ICON_UNSEEN
+}
+
+// Returns compact stopwatch string once >= 1 min, or undefined if not yet / not
+// applicable (feature disabled, not running, or no start time).
+export function formatStopwatch(runStartedAt: number | undefined, phase: Phase): string | undefined {
+  if (!STOPWATCH_ENABLED || !runStartedAt || phase !== "running") return undefined
+  const mins = Math.floor((Date.now() - runStartedAt) / 60_000)
+  if (mins < 1) return undefined
+  if (mins < 60) return `${mins}`
+  const h = Math.floor(mins / 60)
+  const m = mins % 60
+  return m === 0 ? `${h}h` : `${h}h${m}`
+}

package/src/index.ts

@@ -0,0 +1,248 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { ASK_TOOLS, POLL_MS, STOPWATCH_ENABLED, log, type Phase } from "./config"
+import { formatStopwatch, iconFor, stripIcons } from "./format"
+import { playSound } from "./sound"
+import { isFocused, renameTab, resolvePane } from "./zellij"
+
+// ---------------------------------------------------------------------------
+// opencode-zellij-indicator
+//
+// A pure opencode plugin that shows each opencode session's state on its Zellij
+// tab. No fork, no WASM, no status-bar replacement — it just shells out to the
+// `zellij` CLI (`rename-tab-by-id`) and no-ops when not running inside Zellij.
+//
+// Four states, each a configurable icon:
+//   1. running       — opencode is working
+//   2. permission    — waiting for you to approve/deny (always stands out)
+//   3. done, unseen  — finished and you haven't looked yet
+//   4. done, seen    — finished and you've since focused that tab
+//
+// The tab label becomes "<opencode session title> <icon>". Config, presentation
+// helpers, the zellij CLI wrappers and the completion sound live in sibling modules; this
+// file owns the runtime state machine and event wiring.
+// ---------------------------------------------------------------------------
+
+export const ZellijStatus: Plugin = async ({ $ }) => {
+  const paneIdRaw = process.env.ZELLIJ_PANE_ID
+  const paneId = paneIdRaw ? Number.parseInt(paneIdRaw, 10) : NaN
+  if (!process.env.ZELLIJ_SESSION_NAME || Number.isNaN(paneId)) {
+    log(
+      `not inside Zellij (ZELLIJ_SESSION_NAME=${process.env.ZELLIJ_SESSION_NAME}, ZELLIJ_PANE_ID=${paneIdRaw}) — disabled`,
+    )
+    return {} // not inside Zellij — do nothing
+  }
+  log(`init: pane=${paneId} session=${process.env.ZELLIJ_SESSION_NAME}`)
+
+  let phase: Phase = "done"
+  let seen = true
+  let title: string | undefined
+  let baseName: string | undefined
+  let tabId: number | undefined
+  const subagents = new Set<string>()
+  // Permission prompts currently awaiting an answer (by permission id). opencode
+  // asks permission *before* firing tool.execute.before, so we track the pending
+  // prompts to stop that running-transition from clobbering the permission icon.
+  const pendingPerms = new Set<string>()
+  let lastName: string | undefined
+  let pollTimer: ReturnType<typeof setInterval> | undefined
+  let runStartedAt: number | undefined
+  let stopwatchTimer: ReturnType<typeof setTimeout> | undefined
+
+  function endStopwatch() {
+    if (stopwatchTimer) {
+      clearTimeout(stopwatchTimer)
+      stopwatchTimer = undefined
+    }
+  }
+
+  function scheduleStopwatch() {
+    if (!STOPWATCH_ENABLED || stopwatchTimer) return
+    // Fire on the next minute boundary from runStartedAt.
+    const elapsed = Date.now() - (runStartedAt ?? Date.now())
+    const msUntilNextMinute = 60_000 - (elapsed % 60_000)
+    stopwatchTimer = setTimeout(async () => {
+      stopwatchTimer = undefined
+      if (phase !== "running") return
+      await render()
+      scheduleStopwatch() // reschedule for the following minute
+    }, msUntilNextMinute)
+    stopwatchTimer.unref?.()
+  }
+
+  async function refreshTab() {
+    const resolved = await resolvePane($, paneId)
+    if (!resolved) return
+    tabId = resolved.tabId
+    if (baseName === undefined) {
+      baseName = stripIcons(resolved.tabName)
+      log(`resolved tab: id=${tabId} baseName=${JSON.stringify(baseName)}`)
+    }
+  }
+
+  async function render() {
+    await refreshTab()
+    if (tabId === undefined) return
+    const label = (title && title.trim()) || (baseName && baseName.trim()) || ""
+    const stopwatch = formatStopwatch(runStartedAt, phase)
+    const icon = iconFor(phase, seen)
+    const name = label
+      ? stopwatch ? `${label} ${icon} (⏱ ${stopwatch})` : `${label} ${icon}`
+      : stopwatch ? `${icon} (⏱ ${stopwatch})` : icon
+    if (name === lastName) return
+    lastName = name
+    log(`rename tab ${tabId} -> ${JSON.stringify(name)} (phase=${phase} seen=${seen} stopwatch=${stopwatch})`)
+    await renameTab($, tabId, name)
+  }
+
+  function stopPoll() {
+    if (pollTimer) {
+      clearInterval(pollTimer)
+      pollTimer = undefined
+    }
+  }
+
+  function startPoll() {
+    if (pollTimer) return
+    pollTimer = setInterval(async () => {
+      if (phase !== "done" || seen) return stopPoll()
+      if (await isFocused($, paneId)) {
+        log("tab focused while done+unseen -> seen")
+        seen = true
+        await render()
+        stopPoll()
+      }
+    }, POLL_MS)
+    pollTimer.unref?.()
+  }
+
+  async function setRunning() {
+    if (phase !== "running") {
+      runStartedAt = Date.now()
+      scheduleStopwatch()
+    }
+    phase = "running"
+    stopPoll()
+    await render()
+  }
+
+  // "done" covers finished turns and errors.
+  async function setDone() {
+    const wasDone = phase === "done"
+    phase = "done"
+    runStartedAt = undefined
+    endStopwatch()
+    seen = await isFocused($, paneId) // if you're already looking, it's immediately "seen"
+    await render()
+    if (!seen) {
+      startPoll()
+      // Finished while you were away — alert once, on the transition only (so
+      // a following session.error can't play the sound twice for the same finished turn).
+      if (!wasDone) void playSound($)
+    }
+  }
+
+  // Waiting on a permission prompt — always stands out, regardless of focus.
+  async function setPermission() {
+    phase = "permission"
+    runStartedAt = undefined
+    endStopwatch()
+    seen = false
+    stopPoll()
+    await render()
+  }
+
+  return {
+    event: async ({ event }) => {
+      // Permission events are handled here rather than via the `permission.ask`
+      // hook (which doesn't fire in this opencode) and are read loosely because
+      // the SDK types lag the runtime: the real events are `permission.asked`
+      // (props: id, sessionID) and `permission.replied` (props: requestID, reply)
+      // — not the `permission.updated` / `permissionID` the .d.ts declares.
+      const type = event.type as string
+      const props = (event as { properties?: Record<string, unknown> }).properties ?? {}
+      if (type === "permission.asked") {
+        const sessionID = props.sessionID as string | undefined
+        if (!sessionID || !subagents.has(sessionID)) {
+          pendingPerms.add(String(props.id))
+          await setPermission()
+        }
+        return
+      }
+      if (type === "permission.replied") {
+        pendingPerms.delete(String(props.requestID))
+        // Prompt answered — resume "running"; a follow-up session.idle/error
+        // will settle it to done if the turn is actually finished.
+        if (pendingPerms.size === 0 && phase === "permission") await setRunning()
+        return
+      }
+
+      switch (event.type) {
+        case "session.created":
+        case "session.updated": {
+          const info = event.properties.info
+          if (info.parentID) {
+            subagents.add(info.id)
+          } else if (info.title && info.title !== title) {
+            title = info.title
+            await render()
+          }
+          break
+        }
+        case "session.idle": {
+          if (subagents.has(event.properties.sessionID)) break // subagent only
+          await setDone()
+          break
+        }
+        case "session.error": {
+          await setDone()
+          break
+        }
+        case "session.deleted": {
+          const info = event.properties.info
+          if (info.parentID) {
+            subagents.delete(info.id)
+            break
+          }
+          stopPoll()
+          if (tabId !== undefined && baseName !== undefined) {
+            lastName = undefined
+            log(`session deleted -> restore base name ${JSON.stringify(baseName)}`)
+            await renameTab($, tabId, baseName)
+          }
+          break
+        }
+      }
+    },
+
+    "chat.message": async () => {
+      await setRunning()
+    },
+
+    "tool.execute.before": async (input) => {
+      log(`tool.execute.before tool=${JSON.stringify(input.tool)}`)
+      // Interactive prompts (question / plan_exit) are waiting on the user.
+      if (ASK_TOOLS.has(input.tool)) await setPermission()
+      // Safety net: if a permission prompt is already open for this tool, don't
+      // clobber the ❓ icon with "running". (Normally this hook fires just
+      // before `permission.asked`, so pendingPerms is still empty here and the
+      // asked event repaints ❓ a beat later — but guard against either order.)
+      else if (pendingPerms.size > 0) log("tool.execute.before while permission pending — not clobbering")
+      else await setRunning()
+    },
+
+    // Once an interactive prompt is answered, we're processing again.
+    "tool.execute.after": async (input) => {
+      if (ASK_TOOLS.has(input.tool)) await setRunning()
+    },
+
+    // Belt-and-braces for opencode versions that fire this hook (the current
+    // one drives permission state from the `permission.asked` event instead).
+    "permission.ask": async () => {
+      await setPermission()
+    },
+  }
+}
+
+// Export both named and default — opencode discovers named plugin exports, and a
+// default export is belt-and-braces for loader compatibility across versions.
+export default ZellijStatus

package/src/sound.ts

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Sound notification when a turn finishes while you're NOT looking at its tab
+// (the 🔔 "done, unseen" state). Opt-in, off by default.
+//   OPENCODE_ZELLIJ_SOUND=1           enable
+//   OPENCODE_ZELLIJ_SOUND_CMD="..."   run this command instead of the built-in
+//                                     player (e.g. "pw-play ~/alert.wav")
+// When SOUND_CMD is unset we play the bundled WAV via the first audio player we
+// find. If no player exists we silently do nothing — audio is never guaranteed.
+// ---------------------------------------------------------------------------
+
+import { fileURLToPath } from "node:url"
+import { log } from "./config"
+import type { Shell } from "./zellij"
+
+const SOUND_ENABLED = process.env.OPENCODE_ZELLIJ_SOUND === "1"
+const SOUND_CMD = (() => {
+  const v = process.env.OPENCODE_ZELLIJ_SOUND_CMD
+  return v && v.length > 0 ? v : undefined
+})()
+const BUNDLED_SOUND = fileURLToPath(new URL("../sounds/complete.wav", import.meta.url))
+// Ordered by preference; the first one present on the system wins. aplay/paplay
+// handle WAV; ffplay is the catch-all. macOS uses afplay.
+const SOUND_PLAYERS: Array<[string, string[]]> =
+  process.platform === "darwin"
+    ? [["afplay", [BUNDLED_SOUND]]]
+    : [
+        ["paplay", [BUNDLED_SOUND]],
+        ["pw-play", [BUNDLED_SOUND]],
+        ["aplay", ["-q", BUNDLED_SOUND]],
+        ["ffplay", ["-nodisp", "-autoexit", "-loglevel", "quiet", BUNDLED_SOUND]],
+      ]
+
+let lastPlayedAt = 0
+
+// Fire-and-forget notification sound. Fully swallows errors and never blocks
+// the event loop, so a missing player or audio glitch can never break the
+// plugin. A short time-guard stops accidental duplicate plays.
+export async function playSound($: Shell) {
+  if (!SOUND_ENABLED) return
+  const now = Date.now()
+  if (now - lastPlayedAt < 2000) return
+  lastPlayedAt = now
+  try {
+    if (SOUND_CMD) {
+      log(`sound via SOUND_CMD: ${SOUND_CMD}`)
+      await $`sh -c ${SOUND_CMD}`.quiet().nothrow()
+      return
+    }
+    for (const [cmd, args] of SOUND_PLAYERS) {
+      try {
+        const res = await $`${cmd} ${args}`.quiet().nothrow()
+        if (res.exitCode === 0) {
+          log(`sound via ${cmd}`)
+          return
+        }
+      } catch {
+        // try the next player
+      }
+    }
+    log("sound: no working audio player found")
+  } catch (e) {
+    log(`sound failed: ${e instanceof Error ? e.message : "unknown"}`)
+  }
+}

package/src/zellij.ts

@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------------
+// Thin wrappers around the `zellij` CLI. Each takes the Bun shell (`$`) that
+// opencode hands the plugin, so this module holds no state of its own.
+// ---------------------------------------------------------------------------
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { log } from "./config"
+
+// The Bun shell type, derived from the plugin input so we don't depend on a
+// deep/private import path from the SDK.
+export type Shell = Parameters<Plugin>[0]["$"]
+
+export function renameTab($: Shell, id: number, name: string) {
+  return $`zellij action rename-tab-by-id ${id} ${name}`.quiet().nothrow()
+}
+
+// Locate our own pane among all panes and return its tab id + raw tab name.
+// Returns undefined if we can't find it (or the CLI call fails).
+export async function resolvePane(
+  $: Shell,
+  paneId: number,
+): Promise<{ tabId: number; tabName: string } | undefined> {
+  try {
+    const out = await $`zellij action list-panes --json --all`.quiet().nothrow().text()
+    const panes = JSON.parse(out) as Array<{
+      id: number
+      is_plugin: boolean
+      tab_id: number
+      tab_name?: string
+    }>
+    const mine = panes.find((p) => !p.is_plugin && p.id === paneId)
+    if (!mine) {
+      log(`could not find own pane (id=${paneId}) among ${panes.length} panes`)
+      return undefined
+    }
+    return { tabId: mine.tab_id, tabName: String(mine.tab_name ?? "") }
+  } catch (e) {
+    log(`list-panes failed: ${e instanceof Error ? e.message : "unknown"}`)
+    return undefined
+  }
+}
+
+// Whether the client is currently focused on our pane's tab.
+export async function isFocused($: Shell, paneId: number): Promise<boolean> {
+  try {
+    const out = await $`zellij action list-clients`.quiet().nothrow().text()
+    return new RegExp(`\\bterminal_${paneId}\\b`).test(out)
+  } catch {
+    return false
+  }
+}