opencode-bell

Never miss an OpenCode prompt again.

• Zero dependencies — single-file plugin
• Privacy-friendly — no message content, no external commands, no network calls
• Configurable — choose which events trigger the bell
• Smart debounce — avoids bell spam for the same event type per session

Install

npm (recommended)

Add the plugin to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["[email protected]"]
}

Restart OpenCode. It will auto-install the package and cache it under ~/.cache/opencode/node_modules/.

Local file

Copy index.js into ~/.config/opencode/plugins/ and restart OpenCode.

Configuration

Two environment variables control behavior:

| Variable | Default | Description | |---|---|---| | OPENCODE_BELL_EVENTS | permission.asked,question.asked,session.idle,session.error | Comma-separated list of events that trigger the bell | | OPENCODE_BELL_OUTPUTS | bell | Comma-separated output methods: bell and/or osc | | OPENCODE_BELL_DEBOUNCE | 1200 | Minimum ms between repeated bells for the same event type and session. Must be >= 1; 0 or negative falls back to default |

Example — bell only on permission requests, with a 5-second debounce:

export OPENCODE_BELL_EVENTS="permission.asked"
export OPENCODE_BELL_DEBOUNCE="5000"

Example — terminal notification plus bell, similar to Claude Code's iterm2_with_bell style:

export OPENCODE_BELL_OUTPUTS="bell,osc"

Supported Events

| Event | Fires when | |---|---| | permission.asked | OpenCode needs approval to run a tool | | question.asked | OpenCode asks the user a question | | session.idle | A session completes and is waiting for input | | session.error | A session encounters an error |

How it works

The plugin writes the BEL character (\x07) to stdout by default. Your terminal emulator interprets it — typically as an audio beep, a visual flash, or a dock badge, depending on your terminal settings.

When OPENCODE_BELL_OUTPUTS includes osc, the plugin also writes an OSC 9 terminal notification escape sequence. Terminals that support OSC 9 can turn it into a native-looking notification; unsupported terminals usually ignore it.

Troubleshooting

No sound or flash? Check your terminal bell settings:

• Terminal.app: Settings -> Profiles -> Bell

Uninstall

• Remove opencode-bell from opencode.json and restart OpenCode.
• If you used the local-file method, delete ~/.config/opencode/plugins/index.js (or whichever filename you used).

License

MIT