opencode-tmux-alert

Tmux alert plugin for OpenCode — get notified when your AI agent needs attention.

Quick Start · How It Works · Events · Customisation

Quick Start

Package

Install in your OpenCode config directory:

bun install opencode-tmux-alert

Then add the plugin to your opencode.json:

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

Local file

Copy src/index.ts into your OpenCode plugins directory:

cp src/index.ts ~/.config/opencode/plugins/opencode-tmux-alert.ts

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.updated | Agent needs permission to proceed | Alert | | message.part.updated | Tool pending approval | Alert | | tui.prompt.append | Agent asking a question | Alert | | message.updated (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 with plugin support
• tmux — the plugin disables itself gracefully if not running inside tmux

License

MIT