opencode-ntfy.sh

An OpenCode notification backend plugin for ntfy.sh. Built on the opencode-notification-sdk, this plugin delivers push notifications to your phone or desktop when your AI coding session finishes, encounters an error, or needs permission. Start a long-running task, walk away, and get notified when it needs your attention.

How It Works

This plugin is a notification backend for the opencode-notification-sdk. The SDK handles common notification logic:

• Event routing -- classifying OpenCode events into notification types
• Subagent suppression -- silently suppressing notifications from sub-agent (child) sessions for session.idle and session.error events
• Configuration loading -- reading and parsing the config file, handling the enabled and events sections

This plugin is responsible for the ntfy.sh-specific concerns: producing notification content (title and message), formatting and sending the HTTP POST request, validating ntfy-specific configuration, and resolving the notification icon URL.

Notifications

The plugin sends notifications for three events:

• Session Idle -- The AI agent has finished its work and is waiting for input.
• Session Error -- The session encountered an error.
• Permission Asked -- The agent needs permission to perform an action.

Default Tags

Each event type has a default tag corresponding to an emoji shortcode supported by ntfy.sh:

| Event | Default Tag | Emoji | |---|---|---| | session.idle | hourglass_done | ⌛ | | session.error | warning | ⚠️ | | permission.asked | lock | 🔒 |

Install

Add the package name to the plugin array in your OpenCode config file.

opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-ntfy.sh"]
}

Configuration

Configuration is done through a JSON file at ~/.config/opencode/notification-ntfy.json.

You can reference the bundled JSON Schema for editor autocompletion and validation by adding a $schema property:

{
  "$schema": "node_modules/opencode-ntfy.sh/notification-ntfy.schema.json",
  "backend": {
    "topic": "my-notifications"
  }
}

Full Configuration Structure

The config file follows the SDK's configuration schema at the top level, with ntfy-specific settings under the backend key.

| Property | Type | Required | Default | Description | |---|---|---|---|---| | enabled | boolean | No | true | Global kill switch for all notifications (handled by SDK). | | events | object | No | (all enabled) | Per-event enable/disable toggles (handled by SDK). | | events.<type>.enabled | boolean | No | true | Whether this event type triggers notifications (handled by SDK). | | backend | object | No | {} | ntfy.sh-specific configuration (see below). |

Backend Configuration Properties

The backend object contains all ntfy.sh-specific settings:

| Property | Type | Required | Default | Description | |---|---|---|---|---| | backend.topic | string | Yes | -- | The ntfy.sh topic to publish to. | | backend.server | string | No | https://ntfy.sh | The ntfy server URL. | | backend.token | string | No | -- | Bearer token for authentication. | | backend.priority | string | No | default | Notification priority (min, low, default, high, max). | | backend.icon | object | No | -- | Icon configuration object. | | backend.icon.mode | string | No | dark | Whether the target device uses light or dark mode. | | backend.icon.variant | object | No | -- | Custom icon URL overrides per mode variant. | | backend.icon.variant.light | string | No | -- | Custom icon URL override for light mode. | | backend.icon.variant.dark | string | No | -- | Custom icon URL override for dark mode. | | backend.fetchTimeout | string | No | -- | ISO 8601 duration for the HTTP request timeout (e.g., PT10S). | | backend.title | object | No | (see defaults) | Title configuration per event type. | | backend.title.<event> | object | No | (see defaults) | Content template for the notification title. Must contain exactly one of value or command. | | backend.title.<event>.value | string | No | -- | A template string rendered with {var_name} substitution. | | backend.title.<event>.command | string | No | -- | A template string rendered and executed as a shell command; stdout is used as the title. | | backend.message | object | No | (see defaults) | Message configuration per event type. | | backend.message.<event> | object | No | (see defaults) | Content template for the notification message. Must contain exactly one of value or command. | | backend.message.<event>.value | string | No | -- | A template string rendered with {var_name} substitution. | | backend.message.<event>.command | string | No | -- | A template string rendered and executed as a shell command; stdout is used as the message. |

Variable Substitution

All string values in the config file support two placeholder syntaxes, expanded by the SDK before validation:

• {env:VAR_NAME} -- replaced with the value of the corresponding environment variable. If the variable is not set, the placeholder is replaced with an empty string.
• {file:path/to/file} -- replaced with the trimmed contents of the specified file. Paths can be absolute (/), home-relative (~), or relative to the config file's directory. If the file does not exist or cannot be read, the placeholder is replaced with an empty string.

This allows sensitive values like topics and tokens to be externalized, making the config safe to commit to version control:

{
  "backend": {
    "topic": "{env:NTFY_TOPIC}",
    "token": "{file:~/.secrets/ntfy-token}"
  }
}

Notification Content

The notification title and message are configurable per event type via backend.title and backend.message. Each key is an event type (session.idle, session.error, permission.asked), and the value specifies how to produce the content:

• value -- A template string with {var_name} placeholders, resolved via the SDK's renderTemplate. No shell execution.
• command -- A template string with {var_name} placeholders, resolved and then executed as a shell command. The trimmed stdout is used as the content.

Each per-event object must contain exactly one of value or command.

Available Template Variables

| Variable | Description | |---|---| | {event} | Event type (e.g., session.idle) | | {time} | ISO 8601 timestamp | | {project} | Project directory basename | | {session_id} | Session ID (empty if unavailable) | | {error} | Error message (empty if not an error event) | | {permission_type} | Permission type (empty if not a permission event) | | {permission_patterns} | Comma-separated patterns (empty if not a permission event) |

Default Values

When no title or message template is configured for an event type, these defaults are used:

| Event | Default Title | Default Message | |---|---|---| | session.idle | Agent Idle | The agent has finished and is waiting for input. | | session.error | Agent Error | An error has occurred. Check the session for details. | | permission.asked | Permission Asked | The agent needs permission to continue. Review and respond. |

Example Configurations

Minimal configuration (~/.config/opencode/notification-ntfy.json):

{
  "backend": {
    "topic": "my-opencode-notifications"
  }
}

With authentication and a self-hosted server:

{
  "backend": {
    "topic": "my-opencode-notifications",
    "server": "https://ntfy.example.com",
    "token": "tk_mytoken",
    "priority": "high"
  }
}

Full configuration:

{
  "enabled": true,
  "events": {
    "session.idle": { "enabled": true },
    "session.error": { "enabled": true },
    "permission.asked": { "enabled": true }
  },
  "backend": {
    "topic": "{env:NTFY_TOPIC}",
    "server": "https://ntfy.sh",
    "priority": "default",
    "token": "{file:~/.secrets/ntfy-token}",
    "title": {
      "session.idle": { "value": "{project}: Agent Idle" },
      "session.error": { "value": "{project}: Agent Error" }
    },
    "message": {
      "session.error": { "value": "Error in {project}: {error}" }
    },
    "icon": {
      "mode": "dark"
    },
    "fetchTimeout": "PT10S"
  }
}

With command templates:

{
  "backend": {
    "topic": "my-notifications",
    "title": {
      "session.idle": { "command": "echo Agent finished in {project}" }
    },
    "message": {
      "permission.asked": { "command": "echo Permission {permission_type} requested" }
    }
  }
}

Subscribing to Notifications

To receive notifications, subscribe to your topic using any ntfy client:

• Phone: Install the ntfy app (Android, iOS) and subscribe to your topic.
• Desktop: Open https://ntfy.sh/<your-topic> in a browser.
• CLI: curl -s ntfy.sh/<your-topic>/json

Development

Prerequisites

• Bun

Setup

git clone https://github.com/lannuttia/opencode-ntfy.sh.git
cd opencode-ntfy.sh
bun install

Build

bun run build

This compiles TypeScript from src/ to dist/ via tsc.

Test

bun run test

Or in watch mode:

bun run test:watch

License

MIT