opencode-tmux-signal

Signal opencode agent state in tmux — recolor the session's window when it needs you or finishes, and name it after the session.

---

Run OpenCode inside tmux and a row of identical opencode windows becomes legible at a glance. Each window is recolored by agent state — yellow when it wants permission, purple on a question, soft red when it finishes — and named after the session. The highlight only shows while the window is in the background, and clears the moment you open it.

Highlights

• State at a glance — permission (yellow), question (purple), done/error (soft red); nothing while working or focused.
• Smart window names — names follow a priority: an old/resumed session uses its title, a brand-new session uses your first prompt, and the project directory name is only a fallback when an old session has no title. Names are short deterministic slugs (≤ 8 characters), and a name you set yourself is never overwritten.
• Mark-as-read — opening the window clears the highlight (on keyboard and mouse, via focus-events + reset hooks).
• Sub-agent aware — child-session events never flash the main window.
• Zero ceremony — drives tmux at runtime from $TMUX_PANE, and sets up the small bit of tmux config it needs for you.

Install

opencode plugin opencode-tmux-signal -g

This installs the package globally and updates your opencode.json automatically.

Or manually:

npm install -g opencode-tmux-signal

Then add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-tmux-signal"]
}

Requires tmux 3.0+. On first run it adds a small managed block to your ~/.tmux.conf (focus events + a reset hook) so the highlight clears reliably; disable with OPENCODE_TMUX_SIGNAL_MANAGE_TMUX_CONF=off.

Configuration

Everything is optional and set via environment variables. Defaults are a mellow palette that pairs with a green status bar.

Variable	Default	Description
OPENCODE_TMUX_SIGNAL_PERMISSION_BG / _FG	colour179 / black	Permission-request colors (yellow)
OPENCODE_TMUX_SIGNAL_QUESTION_BG / _FG	colour97 / white	Question colors (purple)
OPENCODE_TMUX_SIGNAL_DONE_BG / _FG	colour131 / white	Done/error colors (soft red)
OPENCODE_TMUX_SIGNAL_WINDOW_NAME	llm	llm (model slug with deterministic fallback), dir (project directory), or off
OPENCODE_TMUX_SIGNAL_NAME_MODEL	github-copilot/gpt-4o-mini	Direct model used for window naming. Currently supports GitHub Copilot auth from opencode's auth store
OPENCODE_TMUX_SIGNAL_NAME_TIMEOUT_MS	2500	Maximum time for the direct naming model call, clamped to 500-10000 ms
OPENCODE_TMUX_SIGNAL_RESET_ON_FOCUS	on	Clear the highlight when you open the window
OPENCODE_TMUX_SIGNAL_MANAGE_TMUX_CONF	on	Manage the ~/.tmux.conf block
OPENCODE_TMUX_SIGNAL_DEBUG	(unset)	Log decisions to /tmp/opencode-tmux-signal.log

Colors accept any tmux color: red, brightblue, or colour0–colour255.

How it works

• The window is resolved once from $TMUX_PANE, so multi-pane layouts target the right window.
• State is colored with window-status-style. It's only applied when the window is in the background — if you're already on the window when the state changes, it stays unhighlighted — and a pane-focus-in / after-select hook clears it when you return to a highlighted window.
• Names use a direct GitHub Copilot model call with a short timeout, then deterministic local fallback. The plugin does not create hidden opencode sessions or call client.session.prompt for naming, so naming does not write messages/parts into opencode's session database.
• It only renames a window whose name is still a bare process name (opencode, nano, …) or one it set itself — never a custom name.
• Sub-agent sessions (those with a parentID) are tracked and ignored, so a finishing sub-agent never flashes the main window.

Development

bun install
bun run typecheck
bun run build

Releasing

npm version patch && git push --follow-tags

The publish workflow handles npm (Trusted Publishing + provenance) and the GitHub Release.

License

MIT