opencode-tmux-alert 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Halberthal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+<div align="center">
+
+# opencode-tmux-alert
+
+**Tmux alert plugin for [OpenCode](https://opencode.ai) — get notified when your AI agent needs attention.**
+
+[![npm](https://img.shields.io/npm/v/opencode-tmux-alert?style=flat&logo=npm)](https://www.npmjs.com/package/opencode-tmux-alert)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![OpenCode](https://img.shields.io/badge/OpenCode-Plugin-green.svg?style=flat)](https://opencode.ai/docs/plugins/)
+
+[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Events](#events) · [Customisation](#customisation)
+
+</div>
+
+---
+
+## Quick Start
+
+### Package
+
+Install in your OpenCode config directory:
+
+```bash
+bun install opencode-tmux-alert
+```
+
+Then add the plugin to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-tmux-alert"]
+}
+```
+
+### Local file
+
+Copy `src/index.ts` into your OpenCode plugins directory:
+
+```bash
+cp src/index.ts ~/.config/opencode/plugins/opencode-tmux-alert.ts
+```
+
+---
+
+## How It Works
+
+When OpenCode needs your attention — a task finishes, a permission is requested, or a question is asked — the plugin triggers a tmux alert on the current window. When you respond, the alert clears automatically.
+
+The bundled scripts do two things:
+
+1. **Set a tmux user option** (`@opencode-alert`) that you can reference in your status line
+2. **Send a bell character** (`\a`) which triggers tmux's built-in `monitor-bell` notification
+
+This means alerts work out of the box with a standard tmux config, and can be further customised with status line formatting.
+
+---
+
+## Events
+
+| Event | Trigger | Action |
+|-------|---------|--------|
+| `session.idle` | Task completed, agent waiting | Alert |
+| `permission.updated` | Agent needs permission to proceed | Alert |
+| `message.part.updated` | Tool pending approval | Alert |
+| `tui.prompt.append` | Agent asking a question | Alert |
+| `message.updated` (user) | User submits a message | Clear |
+
+---
+
+## Customisation
+
+### Status line indicator
+
+Use the `@opencode-alert` user option in your tmux status format to show a visual indicator:
+
+```bash
+# In tmux.conf — show an indicator when OpenCode needs attention
+set -g status-right "#{?@opencode-alert,#[fg=yellow] OpenCode,} ..."
+```
+
+### Custom scripts
+
+Override the bundled alert and clear scripts with your own via environment variables:
+
+```bash
+export OPENCODE_ALERT_SCRIPT="$HOME/my-scripts/alert.sh"
+export OPENCODE_CLEAR_SCRIPT="$HOME/my-scripts/clear.sh"
+```
+
+Your scripts receive no arguments. The `TMUX_PANE` environment variable is available if you need to target the current window.
+
+### tmux bell monitoring
+
+To use the bell-based alerts, enable monitoring in your `tmux.conf`:
+
+```bash
+set -g monitor-bell on
+set -g visual-bell off    # optional — suppress the visual flash
+```
+
+---
+
+## Requirements
+
+- [OpenCode](https://opencode.ai) with plugin support
+- [tmux](https://github.com/tmux/tmux) — the plugin disables itself gracefully if not running inside tmux
+
+---
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * Tmux alert plugin for OpenCode.
+ *
+ * Sends visual alerts to tmux when OpenCode needs attention:
+ * - Task completed (session idle)
+ * - Permission requested
+ * - Question asked (prompt append)
+ *
+ * Clears the alert when the user submits a message.
+ *
+ * Customise alert/clear scripts via environment variables:
+ *   OPENCODE_ALERT_SCRIPT — path to a custom alert script
+ *   OPENCODE_CLEAR_SCRIPT — path to a custom clear script
+ */
+export declare const TmuxAlertPlugin: Plugin;

package/dist/index.js

@@ -0,0 +1,64 @@
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+/**
+ * Tmux alert plugin for OpenCode.
+ *
+ * Sends visual alerts to tmux when OpenCode needs attention:
+ * - Task completed (session idle)
+ * - Permission requested
+ * - Question asked (prompt append)
+ *
+ * Clears the alert when the user submits a message.
+ *
+ * Customise alert/clear scripts via environment variables:
+ *   OPENCODE_ALERT_SCRIPT — path to a custom alert script
+ *   OPENCODE_CLEAR_SCRIPT — path to a custom clear script
+ */
+export const TmuxAlertPlugin = async ({ $ }) => {
+    const pluginDir = dirname(fileURLToPath(import.meta.url));
+    const scriptsDir = resolve(pluginDir, "../scripts");
+    const alertScript = process.env.OPENCODE_ALERT_SCRIPT ?? resolve(scriptsDir, "alert.sh");
+    const clearScript = process.env.OPENCODE_CLEAR_SCRIPT ?? resolve(scriptsDir, "clear.sh");
+    if (!process.env.TMUX) {
+        console.error("[opencode-tmux-alert] Not running inside tmux — plugin disabled");
+        return {};
+    }
+    const alert = async () => {
+        await $ `${alertScript}`;
+    };
+    const clear = async () => {
+        await $ `${clearScript}`;
+    };
+    return {
+        event: async ({ event }) => {
+            try {
+                // Task completed — session is now idle
+                if (event.type === "session.idle") {
+                    await alert();
+                }
+                // Permission requested
+                if (event.type === "permission.updated") {
+                    await alert();
+                }
+                // Tool pending permission approval
+                if (event.type === "message.part.updated" &&
+                    event.properties.part.type === "tool" &&
+                    event.properties.part.state.status === "pending") {
+                    await alert();
+                }
+                // Agent asking a question
+                if (event.type === "tui.prompt.append") {
+                    await alert();
+                }
+                // User submitted a message — clear the alert
+                if (event.type === "message.updated" &&
+                    event.properties.info.role === "user") {
+                    await clear();
+                }
+            }
+            catch (error) {
+                console.error("[opencode-tmux-alert] Error:", error);
+            }
+        },
+    };
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "opencode-tmux-alert",
+  "version": "0.1.0",
+  "description": "Tmux alert plugin for OpenCode — get notified when your AI agent needs attention",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "prepublishOnly": "bun test && bun run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tmux",
+    "alert",
+    "notification"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seanhalberthal/opencode-tmux-alert.git"
+  },
+  "homepage": "https://github.com/seanhalberthal/opencode-tmux-alert",
+  "bugs": {
+    "url": "https://github.com/seanhalberthal/opencode-tmux-alert/issues"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.2.10"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/scripts/alert.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Trigger a tmux alert for the current window.
+#
+# Sets the user option @opencode-alert to "1" and sends a bell character.
+# Use #{@opencode-alert} in your tmux status format to show a visual indicator.
+
+set -euo pipefail
+
+PANE_ID="${TMUX_PANE:-}"
+[ -z "$PANE_ID" ] && exit 0
+
+# Set a user option that can be read from the tmux status line
+tmux set-option -w -t "$PANE_ID" @opencode-alert 1 2>/dev/null || true
+
+# Send bell — triggers tmux monitor-bell and visual-bell
+printf '\a'

package/scripts/clear.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Clear the tmux alert for the current window.
+
+set -euo pipefail
+
+PANE_ID="${TMUX_PANE:-}"
+[ -z "$PANE_ID" ] && exit 0
+
+tmux set-option -w -t "$PANE_ID" @opencode-alert 0 2>/dev/null || true