opencode-tmux-status

opencode-tmux-status is a small OpenCode plugin that mirrors OpenCode session state onto tmux window options.

It sets two window-local tmux options:

• @opencode_state=busy|ready|error
• @opencode_managed=1

That keeps the plugin theme-agnostic. Your tmux config decides how to render those states.

What it does

• listens to OpenCode session events through @opencode-ai/plugin
• sets the current tmux window to busy when OpenCode reports session.status with status.type === "busy"
• sets the current tmux window to ready on session.idle
• sets the current tmux window to error on session.error
• resolves the target window automatically from TMUX_PANE
• stays silent outside tmux
• clears its window markers when the OpenCode process exits

Install

From npm

If you want to load the plugin from the OpenCode plugin list, publishing to npm is the normal path.

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

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

OpenCode installs npm plugins automatically with Bun on startup.

Local development

bun install
bun run build

For local development, symlink the built plugin into ~/.config/opencode/plugins/.

Release flow

This repo includes GitHub Actions similar to the setup you used in blippy, but simplified for a single Bun package.

• .github/workflows/ci.yml runs bun run typecheck and bun run build on PRs and pushes to main
• .github/workflows/release.yml publishes to npm when you push a v*.*.* tag
• the release workflow also creates a GitHub Release from that tag

What you need to do once

1. Create an npm access token with publish permission
2. Add it to GitHub as repository secret NPM_TOKEN
3. Make sure the npm package name opencode-tmux-status belongs to your npm account or org
4. Push the repo to GitHub with Actions enabled

How to publish a release

1. Update package.json version
2. Commit and push that version change to main
3. Create and push a matching git tag:

git tag v0.1.0
git push origin main --tags

The workflow validates that package.json version matches the tag, publishes to npm, and creates a GitHub Release.

tmux integration

The plugin only writes tmux options. You choose how those options look.

Generic tmux example

This colors inactive OpenCode windows only and leaves non-OpenCode windows alone.

set -g window-status-format '#{?@opencode_managed,#{?#{==:#{@opencode_state},busy},#[fg=yellow]#W,#{?#{==:#{@opencode_state},ready},#[fg=green]#W,#{?#{==:#{@opencode_state},error},#[fg=red]#W,#W}}},#W}'

Keep your existing window-status-current-format if you already style the active window separately.

Swap yellow, green, and red for any tmux color names or #RRGGBB values that fit your theme.

Catppuccin tmux example

This keeps the active window styling under Catppuccin and only recolors inactive OpenCode windows.

set -g @catppuccin_window_default_text '#{?@opencode_managed,#{?#{==:#{@opencode_state},busy},#[fg=#{@thm_yellow}]#W,#{?#{==:#{@opencode_state},ready},#[fg=#{@thm_green}]#W,#{?#{==:#{@opencode_state},error},#[fg=#{@thm_red}]#W,#W}}},#W}'
set -g @catppuccin_window_current_text '#W#{?window_zoomed_flag,(),}'

For your current config, those two lines can replace:

• ~/.config/tmux/tmux.conf

set -g @catppuccin_window_default_text "#W"
set -g @catppuccin_window_current_text "#W#{?window_zoomed_flag,(),}"

Local dev workflow

Build the plugin and symlink it into your OpenCode plugins directory:

bun run build
ln -sf "$PWD/dist/index.js" ~/.config/opencode/plugins/opencode-tmux-status.js

OpenCode auto-loads files in ~/.config/opencode/plugins/, so rebuilding updates the linked plugin.

Caveats

• this is window-level state, not pane-level state
• stale state is cleared on normal process exit, but SIGKILL or hard crashes can still leave old tmux options behind until the next OpenCode start or manual reset
• the plugin only marks the tmux window that owns the current TMUX_PANE
• multiple OpenCode panes inside the same tmux window share one window state, so the last event wins
• @opencode_managed is intentionally separate so non-OpenCode windows can stay unstyled

Manual reset

If you ever want to clear a window by hand:

tmux set-window-option -u @opencode_state
tmux set-window-option -u @opencode_managed

Events used

• session.status
• session.idle
• session.error