Tmux Alert

---

Quick Start

Package

Install in your OpenCode config directory:

bun install opencode-tmux-alert

Then add the plugin to your opencode.json:

{
  "plugins": ["opencode-tmux-alert"]
}

Requires OpenCode V2.

---

How It Works

When OpenCode needs your attention (a task finishes, a permission is requested, or a question is asked), the plugin triggers a tmux alert on the current window. When you respond, the alert clears automatically.

The bundled scripts do two things:

1. Set a tmux user option (@opencode-alert) that you can reference in your status line
2. Send a bell character (\a) which triggers tmux's built-in monitor-bell notification

This means alerts work out of the box with a standard tmux config, and can be further customised with status line formatting.

---

Events

Event	Trigger	Action
session.idle	Task completed, agent waiting	Alert
permission.asked	Agent needs permission to proceed	Alert
session.tool.called (not executed)	Tool pending approval	Alert
tui.prompt.append	Agent asking a question	Alert
session.inbox.enqueued (user)	User submits a message	Clear

---

Customisation

Status line indicator

Use the @opencode-alert user option in your tmux status format to show a visual indicator:

# In tmux.conf, show an indicator when OpenCode needs attention
set -g status-right "#{?@opencode-alert,#[fg=yellow] OpenCode,} ..."

Custom scripts

Override the bundled alert and clear scripts with your own via environment variables:

export OPENCODE_ALERT_SCRIPT="$HOME/my-scripts/alert.sh"
export OPENCODE_CLEAR_SCRIPT="$HOME/my-scripts/clear.sh"

Your scripts receive no arguments. The TMUX_PANE environment variable is available if you need to target the current window.

tmux bell monitoring

To use the bell-based alerts, enable monitoring in your tmux.conf:

set -g monitor-bell on
set -g visual-bell off    # optional, suppress the visual flash

---

Requirements

• OpenCode V2
• tmux (the plugin disables itself gracefully if not running inside tmux)

---

Licence

MIT