@erzhtor/opencode-tmux-notify 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# opencode-tmux-notify
+
+Shows OpenCode agent activity status in your tmux window name — without overwriting it.
+
+Instead of replacing the window name, this plugin **prepends** a status icon:
+
+![demo](demo.gif)
+
+## Install
+
+```sh
+opencode plugin @erzhtor/opencode-tmux-notify --global
+```
+
+Or add to `opencode.json`:
+
+```json
+{ "plugin": ["@erzhtor/opencode-tmux-notify"] }
+```
+
+## Configure
+
+```ts
+type Options {
+  working?: string | { spinner: string; spinMs?: number }
+  done?:    string | { icon: string; clearMs?: number }
+}
+```
+
+- **`working`** — string for static icon, or `{ spinner, spinMs }` for animation. Default: braille spinner at 80ms.
+- **`done`** — string for icon, or `{ icon, clearMs }` to control the auto-clear. Default: `✔`, 5000ms.
+
+### Examples
+
+Use defaults:
+
+```jsonc
+{ "plugin": ["@erzhtor/opencode-tmux-notify"] }
+```
+
+Static icon:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": "⏳", "done": "✅" }]
+```
+
+Custom spinner + timing:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", {
+  "working": { "spinner": "◐◓◑◒", "spinMs": 120 },
+  "done":    { "icon": "✓", "clearMs": 10000 }
+}]
+```
+
+### Spinner presets
+
+braille *(default)* — dots walking around:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": { "spinner": "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏" } }]
+```
+
+half-circles — rotating circle fills:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": { "spinner": "◐◓◑◒" } }]
+```
+
+quadrant squares — corner fills rotating:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": { "spinner": "◰◳◲◱" } }]
+```
+
+quadrant circles — quadrant fills rotating:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": { "spinner": "◴◷◶◵" } }]
+```
+
+quadrant blocks — block fills rotating:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": { "spinner": "▖▘▝▗" } }]
+```
+
+triangles — corners rotating:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": { "spinner": "◢◣◤◥" } }]
+```
+
+block pulse — growing/shrinking bar:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": { "spinner": "▁▂▃▄▅▆▇█▇▆▅▄▃▂" } }]
+```
+
+arrows — compass cycle:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": { "spinner": "←↖↑↗→↘↓↙" } }]
+```
+
+classic ascii — universal:
+
+```jsonc
+["@erzhtor/opencode-tmux-notify", { "working": { "spinner": "|/-\\" } }]
+```
+
+## How it works
+
+| State   | Icon | Trigger                          |
+| ------- | ---- | -------------------------------- |
+| Working | ⠋    | Agent starts generating a response  |
+| Done    | ✔   | Session becomes idle             |
+| Clean   | —    | 5 seconds after done, or on exit |
+
+- **Multi-instance safe**: Uses `$TMUX_PANE` with `-t` targeting — each OpenCode instance only modifies its own window
+- **No-op outside tmux**: Silently returns if `$TMUX_PANE` is not set
+- **No shell injection**: Uses `execFileSync` (no shell interpolation)
+- **Exit cleanup**: Strips the icon when OpenCode exits
+- **Debounced**: Only sets the working icon once per agent turn

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@erzhtor/opencode-tmux-notify",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that shows agent activity status in tmux window names",
+  "type": "module",
+  "main": "tmux-notify.ts",
+  "files": ["tmux-notify.ts"],
+  "keywords": ["opencode", "opencode-plugin", "tmux", "notify", "notification", "status"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/erzhtor/opencode-tmux-notify"
+  }
+}

package/tmux-notify.ts

@@ -0,0 +1,124 @@
+import { execFileSync } from "child_process";
+
+// Spinner presets for the `working.spinner` option:
+//   braille (default):       "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+//   half-circles:             "◐◓◑◒"
+//   quadrant squares:         "◰◳◲◱"
+//   quadrant circles:         "◴◷◶◵"
+//   quadrant blocks:          "▖▘▝▗"
+//   triangles:                "◢◣◤◥"
+//   block pulse:              "▁▂▃▄▅▆▇█▇▆▅▄▃▂"
+//   arrows:                   "←↖↑↗→↘↓↙"
+//   classic ascii:            "|/-\\"
+const DEFAULT_SPINNER = "\u280b\u2819\u2839\u2838\u283c\u2834\u2826\u2827\u2807\u280f"; // ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏
+
+type Options = {
+  working?: string | { spinner: string; spinMs?: number };
+  done?: string | { icon: string; clearMs?: number };
+};
+
+type Resolved = {
+  spinner: string;
+  spinnerMs: number;
+  useSpinner: boolean;
+  iconWorking: string;
+  iconDone: string;
+  clearMs: number;
+};
+
+export const TmuxNotifyPlugin = async (
+  _input: any,
+  options?: Options,
+) => {
+  if (!process.env.TMUX_PANE) return {};
+
+  const w = options?.working;
+  const useSpinner = w == null || typeof w === "object";
+
+  const cfg: Resolved = {
+    spinner: useSpinner ? (typeof w === "object" ? w.spinner : DEFAULT_SPINNER) : DEFAULT_SPINNER,
+    spinnerMs: typeof w === "object" ? (w.spinMs ?? 80) : 80,
+    useSpinner,
+    iconWorking: typeof w === "string" ? w : "",
+    iconDone:
+      options?.done == null ? "\u2714" // ✔
+      : typeof options.done === "object" ? options.done.icon
+      : options.done,
+    clearMs:
+      options?.done == null ? 5000
+      : typeof options.done === "object" ? (options.done.clearMs ?? 5000)
+      : 5000,
+  };
+
+  const pane = process.env.TMUX_PANE;
+  let working = false;
+  let clearTimer: any = null;
+  let spinnerId: any = null;
+  let spinnerIdx = 0;
+  let baseName: string | null = null;
+
+  const tmux = (...args: string[]) => {
+    try {
+      return execFileSync("tmux", args, { encoding: "utf-8" }).trim();
+    } catch {
+      return null;
+    }
+  };
+
+  const getName = () => tmux("display-message", "-t", pane, "-p", "#W");
+  const setName = (n: string) => tmux("rename-window", "-t", pane, n);
+
+  const base = () => {
+    if (baseName !== null) return baseName;
+    const n = getName();
+    if (!n) return null;
+    baseName = n;
+    return baseName;
+  };
+
+  const set = (icon?: string) => {
+    const b = base();
+    if (!b) return;
+    setName(icon ? `${icon} ${b}` : b);
+  };
+
+  const stopSpinner = () => {
+    if (spinnerId) {
+      clearInterval(spinnerId);
+      spinnerId = null;
+    }
+  };
+
+  process.on("exit", () => {
+    stopSpinner();
+    set();
+  });
+
+  return {
+    event: async ({ event }: { event: any }) => {
+      if (event.type === "message.part.updated" && !working) {
+        working = true;
+        if (clearTimer) {
+          clearTimeout(clearTimer);
+          clearTimer = null;
+        }
+        if (cfg.useSpinner) {
+          spinnerIdx = 0;
+          spinnerId = setInterval(() => {
+            set(cfg.spinner[spinnerIdx]);
+            spinnerIdx = (spinnerIdx + 1) % cfg.spinner.length;
+          }, cfg.spinnerMs);
+          set(cfg.spinner[0]);
+        } else {
+          set(cfg.iconWorking);
+        }
+      }
+      if (event.type === "session.idle") {
+        working = false;
+        stopSpinner();
+        set(cfg.iconDone);
+        clearTimer = setTimeout(() => set(), cfg.clearMs);
+      }
+    },
+  };
+};