DOCSEARCHbyAlgolia
Submit Docs

opencode-notifier

repository·main·Indexed 20 days ago

https://github.com/mohak34/opencode-notifier

An OpenCode plugin that provides system notifications and audio alerts for lifecycle events such as permission requests, task completion, and errors. Supports macOS, Linux, and Windows, with customizable sounds, notification messages, and the ability to execute custom commands on specific events.

Tokens
9K
Snippets
26
Records
34
Agent score
66%

What's inside @mohak34/opencode-notifier

  1. Use Ghostty Native Notifications

    main

    If you use the Ghostty terminal, you can use its native notification system via OSC 9 escape sequences. This works on any platform where Ghostty is running.

    Setup:

    1. Set notificationSystem to "ghostty" in your config.
    2. macOS Users: To prevent duplicate audio (from macOS Notification Center), set suppressGhosttySound: true.
    3. tmux Users: You must enable passthrough in your .tmux.conf to allow OSC 9 sequences to pass through:
    set -g allow-passthrough on

    Then reload the config: tmux source-file ~/.tmux.conf.

    {
  "notificationSystem": "ghostty",
  "suppressGhosttySound": true
}

  2. Clear OpenCode plugin cache to update versions

    main

    OpenCode caches plugins under ~/.cache/opencode. If you switch between latest, beta, or pinned versions and the changes aren't reflecting, you must manually clear the cache and restart OpenCode.

    To avoid cache issues during testing, it is recommended to pin an exact version in your opencode.json instead of using a moving tag:

    {
  "plugin": ["@mohak34/opencode-notifier@x.y.z"]
}
    ### Linux/macOS
```bash
rm -rf ~/.cache/opencode/packages/@mohak34/opencode-notifier*
rm -rf ~/.cache/opencode/node_modules/@mohak34/opencode-notifier
rm -f ~/.cache/opencode/bun.lock

    Windows PowerShell

    Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\packages\@mohak34\opencode-notifier*" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\node_modules\@mohak34\opencode-notifier" -ErrorAction SilentlyContinue
Remove-Item -Force "$env:USERPROFILE\.cache\opencode\bun.lock" -ErrorAction SilentlyContinue

  3. Configure opencode-notifier via config file

    main

    You can customize the behavior of the notifier by creating a configuration file at ~/.config/opencode/opencode-notifier.json. This file allows you to control sounds, notifications, custom commands, and event-specific settings like volumes and messages.

    {
  "sound": true,
  "notification": true,
  "bell": false,
  "timeout": 5,
  "showProjectName": true,
  "showFullPath": false,
  "showSessionTitle": false,
  "showIcon": true,
  "customIconPath": null,
  "suppressWhenFocused": true,
  "enableOnDesktop": false,
  "notificationSystem": "osascript",
  "suppressGhosttySound": false,
  "linux": {
    "grouping": false
  },
  "minDuration": 0,
  "command": {
    "enabled": false,
    "path": "/path/to/command",
    "args": ["--event", "{event}", "--message", "{message}"],
    "minDuration": 0
  },
  "events": {
    "permission": { "sound": true, "notification": true, "command": true, "bell": false },
    "complete": { "sound": true, "notification": true, "command": true, "bell": false },
    "subagent_complete": { "sound": false, "notification": false, "command": true, "bell": false },
    "error": { "sound": true, "notification": true, "command": true, "bell": false },
    "question": { "sound": true, "notification": true, "command": true, "bell": false },
    "user_cancelled": { "sound": false, "notification": false, "command": true, "bell": false },
    "plan_exit": { "sound": true, "notification": true, "command": true, "bell": false },
    "session_started": { "sound": true, "notification": false, "command": true, "bell": false },
    "user_message": { "sound": true, "notification": false, "command": true, "bell": false },
    "client_connected": { "sound": true, "notification": false, "command": true, "bell": false }
  },
  "messages": {
    "permission": "Session needs permission: {sessionTitle}",
    "complete": "Session has finished: {sessionTitle}",
    "subagent_complete": "Subagent task completed: {sessionTitle}",
    "error": "Session encountered an error: {sessionTitle}",
    "question": "Session has a question: {sessionTitle}",
    "user_cancelled": "Session was cancelled by user: {sessionTitle}",
    "plan_exit": "Plan ready for review: {sessionTitle}",
    "session_started": "Session started: {sessionTitle}",
    "user_message": "User sent a message: {sessionTitle}",
    "client_connected": "OpenCode connected"
  },
  "sounds": {
    "permission": null,
    "complete": null,
    "subagent_complete": null,
    "error": null,
    "question": null,
    "user_cancelled": null,
    "plan_exit": null,
    "session_started": null,
    "user_message": null,
    "client_connected": null
  },
  "volumes": {
    "permission": 1,
    "complete": 1,
    "subagent_complete": 1,
    "error": 1,
    "question": 1,
    "user_cancelled": 1,
    "plan_exit": 1,
    "session_started": 1,
    "user_message": 1,
    "client_connected": 1
  }
}

  5. Setup opencode-notifier on Windows and WSL

    main

    Windows

    • Works out of the box.
    • Important: Only .wav files are supported for sounds (not .mp3).
    • Use absolute paths (e.g., C:/Users/You/sounds/alert.wav) instead of tilde ~/ notation.

    WSL

    Due to path translation issues, it is recommended to set customIconPath to a file located on the Windows filesystem. This path is passed to snoretoast-*.exe.

    Example configuration for WSL:

    {
  "showIcon": true,
  "customIconPath": "C:\\Users\\jhon\\Documents\\opencode-logo-dark.png"
}

  6. Setup opencode-notifier on Linux

    main

    On Linux, ensure you have a notification system installed. If not, install libnotify using your package manager:

    sudo apt install libnotify-bin  # Ubuntu/Debian
sudo dnf install libnotify       # Fedora  
sudo pacman -S libnotify         # Arch

    For sound playback, you must have one of the following installed: paplay, aplay, mpv, or ffplay.

  7. Use the 'Jump to terminal' feature on KDE Plasma

    main

    On KDE Plasma/Wayland, the plugin provides an explicit Jump to terminal action button on the notification card. Clicking this button runs the terminal-focus path.

    If kdotool is installed, the plugin automatically captures the startup terminal window ID and jumps back to that specific pinned window.

    Manual Override: If the automatic jump fails or targets the wrong window, you can manually pin a window ID using the OPENCODE_NOTIFIER_WINDOW_ID environment variable before running OpenCode:

    export OPENCODE_NOTIFIER_WINDOW_ID="$(kdotool getactivewindow)"
opencode

  8. Locate the configuration and state files

    main

    The notifier uses a JSON configuration file to manage settings. You can override the default location by setting the OPENCODE_NOTIFIER_CONFIG_PATH environment variable.

    • Default Config Path: ~/.config/opencode/opencode-notifier.json (on Unix-like systems)
    • Default State Path: ~/.config/opencode/opencode-notifier-state.json (located in the same directory as the config file)
    export OPENCODE_NOTIFIER_CONFIG_PATH="/path/to/your/custom-config.json"
# Then run your application

  9. Configure Custom Sounds and Volumes

    main

    You can specify custom audio files for each event and set individual volumes.

    Sound Files:

    • macOS/Linux: .wav or .mp3 supported.
    • Windows: Only .wav supported.
    • If a file is missing, it falls back to the bundled sound.

    Volumes:

    • Range: 0 (mute) to 1 (full volume).
    • Values outside 0..1 are automatically clamped.
    • Note: On Windows, custom volume may not be honored by the default player.
    {
  "sounds": {
    "permission": "/path/to/alert.wav",
    "complete": "/path/to/done.wav"
  },
  "volumes": {
    "permission": 0.6,
    "complete": 0.3
  }
}

  10. Configure Event-Specific Behaviors

    main

    You can control sound, notification, command, and bell settings for each specific event type. This allows you to, for example, trigger a custom command for a user_cancelled event without playing a sound or showing a notification.

    Supported events:

    • permission
    • complete
    • subagent_complete
    • error
    • question
    • user_cancelled (Fires when ESC is pressed; silent by default)
    • plan_exit
    • session_started
    • user_message
    • client_connected
    {
  "events": {
    "permission": { "sound": true, "notification": true, "command": true, "bell": false },
    "complete": { "sound": true, "notification": true, "command": true, "bell": false },
    "subagent_complete": { "sound": false, "notification": false, "command": true, "bell": false },
    "error": { "sound": true, "notification": true, "command": true, "bell": false },
    "question": { "sound": true, "notification": true, "command": true, "bell": false },
    "user_cancelled": { "sound": false, "notification": false, "command": true, "bell": false },
    "plan_exit": { "sound": true, "notification": true, "command": true, "bell": false },
    "session_started": { "sound": true, "notification": false, "command": true, "bell": false },
    "user_message": { "sound": true, "notification": false, "command": true, "bell": false },
    "client_connected": { "sound": true, "notification": false, "command": true, "bell": false }
  }
}

  11. Configure Windows/WSL fallback for notifications and crashes

    main

    On Windows, native notifications may fail in WSL or cause OpenCode to crash due to known Bun issues. To resolve this, disable native notifications and use a PowerShell popup command instead.

    Configuration for WSL/Crash Prevention:

    {
  "notification": false,
  "sound": true,
  "command": {
    "enabled": true,
    "path": "powershell.exe",
    "args": [
      "-Command",
      "$wshell = New-Object -ComObject Wscript.Shell; $wshell.Popup('{message}', 5, 'OpenCode - {event}', 0+64)"
    ]
  }
}

  12. Configure macOS Notification Systems

    main

    On macOS, you can choose between different notification engines via the notificationSystem key:

    1. osascript (Default): Reliable, but shows the Script Editor icon.
    2. node-notifier: Shows the OpenCode icon, but may occasionally miss notifications.
    3. ghostty: Uses native OSC 9 escape sequences if using the Ghostty terminal.
    {
  "notificationSystem": "osascript"
}