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:

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.

Backend Configuration Properties

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

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

Default Values

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

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