opencode-terminal-notifier

Get notified when OpenCode needs your attention - even when you've switched to another app.

This plugin alerts you with a sound, dock bounce, or desktop notification when:

• OpenCode needs permission to proceed
• A task finishes
• An error occurs
• OpenCode has a question for you

No setup required for most users. Just install and go.

Installation

Add one line to your OpenCode config file (opencode.json or opencode.jsonc):

{
  "plugin": ["@mathew-cf/[email protected]"]
}

Then restart OpenCode. That's it!

Where's my config file? It's usually at ~/.config/opencode/opencode.json (Mac/Linux) or in your project folder.

How It Works

When you switch away from your terminal to do other work, this plugin will get your attention when OpenCode needs you:

• Sound or dock bounce - Works in any terminal
• Desktop notifications - Appear in your notification center (supported terminals only)

The plugin automatically detects your terminal and uses the best notification method available.

Supported Terminals

| Terminal | What You'll Get | |----------|-----------------| | Ghostty | Desktop notifications | | iTerm2 | Desktop notifications | | Kitty | Desktop notifications | | WezTerm | Desktop notifications | | All others | Sound + dock bounce |

Configuration (Optional)

The plugin works without any configuration. But if you want to customize it, create a file at ~/.config/opencode/terminal-notifier.json:

{
  "enabled": true,
  "events": {
    "permission": true,
    "complete": false,
    "subagent_complete": false,
    "error": true,
    "question": true
  }
}

Turn Off Specific Notifications

Don't want to be notified when tasks complete? Just disable that event:

{
  "events": {
    "complete": false
  }
}

Customize Notification Messages

{
  "messages": {
    "permission": "Action required",
    "complete": "Done!",
    "error": "Something went wrong",
    "question": "Input needed"
  }
}

All Options

| Option | Default | Description | |--------|---------|-------------| | enabled | true | Turn all notifications on/off | | method | "auto" | How to notify (usually leave as auto) | | showProjectName | true | Show project folder name in notifications |

Troubleshooting

I don't hear anything

1. Make sure your system volume isn't muted
2. Check your terminal's sound/bell settings (look in Preferences)
3. Some terminals flash the screen instead of playing a sound - this is called "visual bell"

Desktop notifications aren't showing

1. Make sure your terminal has notification permissions (check System Settings > Notifications on Mac)
2. Your terminal might not support desktop notifications - the plugin will fall back to sound/dock bounce

Test if it's working

Run this command, then quickly switch to another app:

sleep 2 && echo -e "\a"

If your terminal is set up correctly, you'll hear a sound or see your dock icon bounce after 2 seconds.

Advanced Configuration

Notification Methods

The plugin supports several notification methods:

| Method | Description | Terminals | |--------|-------------|-----------| | auto | Automatically choose the best method | All | | bell | Terminal bell (sound/visual) | All | | osc9 | Desktop notifications | iTerm2 | | osc777 | Desktop notifications | Ghostty, rxvt-unicode | | osc99 | Desktop notifications | Kitty, WezTerm, foot |

Per-Event Method Override

Use a different notification method for specific events:

{
  "events": {
    "permission": { "enabled": true, "method": "osc9" },
    "complete": { "enabled": true },
    "error": { "enabled": true, "method": "bell" },
    "question": { "enabled": true }
  }
}

Terminal-Specific Setup

iTerm2

1. Open iTerm2 > Preferences > Profiles > Terminal
2. Enable "Notifications" or configure notification triggers

Kitty

Works automatically. See Kitty Desktop Notifications for advanced options.

Ghostty

Works automatically with OSC 777 notifications.

Check Your Terminal Type

To see what terminal the plugin detects:

echo $TERM_PROGRAM

Test Specific Notification Methods

Switch to another app after running these commands:

# Test bell
sleep 2 && echo -e "\a"

# Test OSC 9 (iTerm2)
sleep 2 && echo -e "\e]9;Test notification\e\\"

# Test OSC 99 (Kitty)
sleep 2 && echo -e "\e]99;d=0;Test notification\e\\"

Development

Want to contribute or modify this plugin? Here's how to set it up locally.

Prerequisites

• Bun v1.0 or later

Setup

git clone https://github.com/mathew-cf/opencode-terminal-notifier.git
cd opencode-terminal-notifier
bun install

Build

bun run build

Type Check

bun run typecheck

Project Structure

src/
  index.ts     # Plugin entry point and event handlers
  config.ts    # Configuration loading and validation
  notify.ts    # Notification methods (bell, OSC sequences)
dist/          # Compiled output (generated by build)

Test Locally

1. Build the plugin: bun run build
2. Point OpenCode to your local copy:

   {
     "plugin": ["/path/to/opencode-terminal-notifier"]
   }

3. Restart OpenCode

Acknowledgments

Inspired by opencode-notifier. This plugin uses terminal-native notifications instead of AppleScript/osascript, so clicking a notification activates the specific terminal session that created it.

License

Apache 2.0