opencode-ntfy.sh 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Lannutti
+
+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,127 @@
+# opencode-ntfy.sh
+
+An [OpenCode](https://opencode.ai) plugin that sends push notifications via
+[ntfy.sh](https://ntfy.sh) when your AI coding session finishes or encounters
+an error. Start a long-running task, walk away, and get notified on your phone
+or desktop when it needs your attention.
+
+## Notifications
+
+The plugin sends notifications for two events:
+
+- **Session Idle** -- The AI agent has finished its work and is waiting for
+  input. Includes the project name and timestamp.
+- **Session Error** -- The session encountered an error. Includes the project
+  name, timestamp, and error message (when available).
+
+If `NTFY_TOPIC` is not set, the plugin does nothing.
+
+## Install
+
+Add the package name to the `plugin` array in your OpenCode config file.
+
+opencode.json:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-ntfy.sh"]
+}
+```
+
+## Configuration
+
+Configuration is done through environment variables.
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `NTFY_TOPIC` | Yes | -- | The ntfy.sh topic to publish to. |
+| `NTFY_SERVER` | No | `https://ntfy.sh` | The ntfy server URL. Set this to use a self-hosted instance. |
+| `NTFY_TOKEN` | No | -- | Bearer token for authenticated topics. |
+| `NTFY_PRIORITY` | No | `default` | Notification priority. One of: `min`, `low`, `default`, `high`, `max`. |
+
+### Subscribing to notifications
+
+To receive notifications, subscribe to your topic using any
+[ntfy client](https://docs.ntfy.sh/subscribe/):
+
+- **Phone**: Install the ntfy app
+  ([Android](https://play.google.com/store/apps/details?id=io.heckel.ntfy),
+  [iOS](https://apps.apple.com/us/app/ntfy/id1625396347)) and subscribe to
+  your topic.
+- **Desktop**: Open `https://ntfy.sh/<your-topic>` in a browser.
+- **CLI**: `curl -s ntfy.sh/<your-topic>/json`
+
+### Example
+
+```sh
+export NTFY_TOPIC="my-opencode-notifications"
+opencode
+```
+
+With authentication and a self-hosted server:
+
+```sh
+export NTFY_TOPIC="my-opencode-notifications"
+export NTFY_SERVER="https://ntfy.example.com"
+export NTFY_TOKEN="tk_mytoken"
+export NTFY_PRIORITY="high"
+opencode
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js (v18+ for native `fetch` support)
+- npm
+
+### Setup
+
+```sh
+git clone https://github.com/lannuttia/opencode-ntfy.sh.git
+cd opencode-ntfy.sh
+npm install
+```
+
+### Build
+
+```sh
+npm run build
+```
+
+This compiles TypeScript from `src/` to `dist/` via `tsc`.
+
+### Test
+
+```sh
+npm test
+```
+
+Or in watch mode:
+
+```sh
+npm run test:watch
+```
+
+### Using a development build with OpenCode
+
+To use a local development build as a plugin, place or symlink the project
+directory into the OpenCode plugins folder:
+
+```sh
+# Build first
+npm run build
+
+# Project-level (applies to a single project)
+ln -s /path/to/opencode-ntfy.sh .opencode/plugins/opencode-ntfy.sh
+
+# Or global (applies to all projects)
+ln -s /path/to/opencode-ntfy.sh ~/.config/opencode/plugins/opencode-ntfy.sh
+```
+
+Then set the required environment variables and start OpenCode as usual.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+export interface NtfyConfig {
+    topic: string;
+    server: string;
+    token?: string;
+    priority: string;
+}
+export declare function loadConfig(env: Record<string, string | undefined>): NtfyConfig;

package/dist/config.js

@@ -0,0 +1,17 @@
+const VALID_PRIORITIES = ["min", "low", "default", "high", "max"];
+export function loadConfig(env) {
+    const topic = env.NTFY_TOPIC;
+    if (!topic) {
+        throw new Error("NTFY_TOPIC environment variable is required");
+    }
+    const priority = env.NTFY_PRIORITY || "default";
+    if (!VALID_PRIORITIES.includes(priority)) {
+        throw new Error(`NTFY_PRIORITY must be one of: ${VALID_PRIORITIES.join(", ")}`);
+    }
+    return {
+        topic,
+        server: env.NTFY_SERVER || "https://ntfy.sh",
+        token: env.NTFY_TOKEN,
+        priority,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const plugin: Plugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,55 @@
+import { loadConfig } from "./config.js";
+import { sendNotification } from "./notify.js";
+function getProjectName(directory) {
+    return directory.split("/").pop() || directory;
+}
+export const plugin = async (input) => {
+    if (!process.env.NTFY_TOPIC) {
+        return {};
+    }
+    const config = loadConfig(process.env);
+    const project = getProjectName(input.directory);
+    return {
+        event: async ({ event }) => {
+            if (event.type === "session.idle") {
+                await sendNotification(config, {
+                    title: `${project} - Session Idle`,
+                    message: `Event: session.idle\nProject: ${project}\nTime: ${new Date().toISOString()}`,
+                    tags: "hourglass_done",
+                });
+            }
+            else if (event.type === "session.error") {
+                const error = event.properties.error;
+                const errorMsg = error && "data" in error && "message" in error.data
+                    ? `\nError: ${error.data.message}`
+                    : "";
+                await sendNotification(config, {
+                    title: `${project} - Session Error`,
+                    message: `Event: session.error\nProject: ${project}\nTime: ${new Date().toISOString()}${errorMsg}`,
+                    tags: "warning",
+                });
+            }
+            else if (event.type === "permission.asked") {
+                const props = event.properties;
+                const permission = props.permission || "";
+                const patterns = props.patterns?.join(", ") || "";
+                const detail = permission
+                    ? `\nPermission: ${permission}${patterns ? ` (${patterns})` : ""}`
+                    : "";
+                await sendNotification(config, {
+                    title: `${project} - Permission Requested`,
+                    message: `Event: permission.asked\nProject: ${project}\nTime: ${new Date().toISOString()}${detail}`,
+                    tags: "lock",
+                });
+            }
+        },
+        "permission.ask": async (permission) => {
+            await sendNotification(config, {
+                title: `${project} - Permission Requested`,
+                message: `Event: permission.asked\nProject: ${project}\nTime: ${new Date().toISOString()}\nPermission: ${permission.title}`,
+                tags: "lock",
+            });
+        },
+    };
+};
+export default plugin;

package/dist/notify.d.ts

@@ -0,0 +1,7 @@
+import type { NtfyConfig } from "./config.js";
+export interface NotificationPayload {
+    title: string;
+    message: string;
+    tags: string;
+}
+export declare function sendNotification(config: NtfyConfig, payload: NotificationPayload): Promise<void>;

package/dist/notify.js

@@ -0,0 +1,19 @@
+export async function sendNotification(config, payload) {
+    const url = `${config.server}/${config.topic}`;
+    const headers = {
+        Title: payload.title,
+        Priority: config.priority,
+        Tags: payload.tags,
+    };
+    if (config.token) {
+        headers.Authorization = `Bearer ${config.token}`;
+    }
+    const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: payload.message,
+    });
+    if (!response.ok) {
+        throw new Error(`ntfy request failed: ${response.status} ${response.statusText}`);
+    }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "opencode-ntfy.sh",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that sends push notifications via ntfy.sh",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.1.63",
+    "@types/node": "^25.2.3",
+    "msw": "^2.12.10",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "yaml": "^2.8.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT"
+}