Termux Notify

Termux notification plugin for OpenCode on Android. Routes OpenCode attention events to termux-notification and termux-media-player via the OpenCode V2 plugin API (@opencode-ai/plugin/v2/promise).

Features

• 6 notification kinds (default, question, permission, error, done, subagent_done) with distinct vibration and audio via termux-media-player
• Cross-instance deduplication via shared JSON file and stable notification IDs
• Spam prevention via event TTL (60s), per-session cooldown (5s), and global throttle (1s)
• Session-aware titles resolved from OpenCode session metadata
• Fully configurable: binaries, vibration, priority, cooldowns, kinds, and subagent handling

Requirements

• Android + Termux with termux-api (pkg install termux-api and install Termux:API app
• Node >= 20, Opencode V2(V2 plugin API)

Install

opencode plugin add opencode-termux-notify

Add to opencode.jsonc:

// ~/.config/opencode/opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-termux-notify"]
}

Local path (this repo):

// opencode.jsonc
{
  "plugins": ["/data/data/com.termux/files/home/opencode-termux-notify"]
}

Usage

With options:

// opencode.jsonc
{
  "plugins": [{
    "package": "opencode-termux-notify",
    "options": {
      "kinds": ["question", "permission", "error", "done", "subagent_done"],
      "notifySubagents": true,
      "priority": "high"
    }
  }]
}

Restart OpenCode after editing config:

opencode service restart

Grant notification permission on Android 13+ under Settings > Apps > Termux > Notifications. Verify with:

termux-notification --title test --content test --priority high --vibrate "400,200,400" --sound --id test

Configuration

Option	Type	Default	Description
bin	string	/data/data/com.termux/files/usr/bin/termux-notification	Notification binary
mediaBin	string	/data/data/com.termux/files/usr/bin/termux-media-player	Audio player binary
sharedPath	string	os.tmpdir()/termux-notify-shared.json	Deduplication file
seenTTL	number	60000	Event ID TTL (ms)
sessionCooldown	number	5000	Per-session debounce (ms)
globalCooldown	number	1000	Global throttle (ms)
priority	string	per-kind	Notification priority
sound	boolean	true	Enable sound
playSound	boolean	true	Play bundled mp3
vibrate	boolean	true	Enable vibration
requireTermux	boolean	true	Warn if not in Termux
kinds	string[]	all kinds	Enabled event kinds
notifySubagents	boolean	true	Notify for subagents (false = sound only)
title_<kind> / content_<kind>	string	per-kind	Title/content override

Development

npm install
npm run typecheck
npm run build

License

MIT