opencode-tmux-status

Note

This has been heavily vibe coded. Use at your own risk. It works for me, but your mileage may vary.

Show your opencode session status as a small colored ASCII circle next to the window name in your tmux status bar.

When an opencode session is running in a tmux window, the window gets a circle whose glyph and color reflect what opencode is doing:

State	Glyph	Color	Meaning
ready	○	green	Idle / done — waiting for your next prompt
working	◐	yellow	Generating output or running tools
blocked	●	red	Blocked — needs you to approve a permission or answer a question

Windows without an opencode session show nothing extra.

How it works

The repo ships a small opencode plugin. Because the plugin runs inside the opencode process, and that process lives in a tmux pane, it can read its own $TMUX_PANE environment variable.

On every status-changing event, the plugin runs:

tmux set-option -w -t "$TMUX_PANE" @opencode_status <state>

This sets a per-window user option (@opencode_status) on the window that owns the pane. Your tmux.conf then renders that option as a colored circle in the window-status-format. tmux evaluates the format independently per window, so each window shows its own opencode status.

The plugin only writes the state name. The glyph and color live entirely in your tmux.conf, so you can customize the look without touching the plugin.

Install

1. Clone and copy the plugin

git clone https://github.com/MikaelStave/opencode-tmux-status.git
mkdir -p ~/.config/opencode/plugins
cp opencode-tmux-status/plugin/tmux-status.ts ~/.config/opencode/plugins/

Local plugins in ~/.config/opencode/plugins/ are loaded automatically at startup.

2. Add the tmux format snippet

Add the circle to both the inactive and active window formats in your ~/.tmux.conf. The snippet below reads @opencode_status and picks a glyph + color per state, rendering nothing when the option is unset:

# opencode-tmux-status: colored circle reflecting opencode session state
# ○ green = ready/done, ◐ yellow = working, ● red = blocked (needs input)
setw -g window-status-format         " #[fg=#a6accd]#I:#W #{?@opencode_status,#{?#{==:#{@opencode_status},blocked},#[fg=#ff5370]●#[default],#{?#{==:#{@opencode_status},working},#[fg=#ffcb6b]◐#[default],#[fg=#c3e88d]○#[default]}} ,}"
setw -g window-status-current-format " #[fg=#1e1e2e,bg=#82aaff,bold] #I:#W #{?@opencode_status,#{?#{==:#{@opencode_status},blocked},#[fg=#ff5370]●,#{?#{==:#{@opencode_status},working},#[fg=#ffcb6b]◐,#[fg=#c3e88d]○}} ,}#[default]"

Adjust the window-status-format / window-status-current-format bodies to match your existing theme — the important bit is appending the #{?@opencode_status,...} conditional that renders the circle.

Reload tmux:

tmux source-file ~/.tmux.conf

(or prefix + r if you have a reload binding).

Customize

Everything visual lives in the window-status-format conditionals in your tmux.conf.

• Change glyphs: replace ●, ◐, ○.
• Change colors: edit the #[fg=...] hex codes.
• Move it: put the #{?@opencode_status,...} block before #I:#W to render it on the left of the window name.

The plugin's job is only to set @opencode_status to ready, working, or blocked.

Limitations

• If opencode is killed hard (e.g. kill -9, or the terminal/kitty tab is closed without a clean exit), the plugin can't run its cleanup, so a stale circle may remain. It is reset the next time an opencode session runs in that window. Normal quits (Ctrl-C, exiting the TUI) clean up correctly.

Uninstall

1. Remove the plugin:

   rm ~/.config/opencode/plugins/tmux-status.ts

2. Remove the opencode-tmux-status lines (the #{?@opencode_status,...} conditional) from your ~/.tmux.conf window-status formats, then reload tmux.

License

MIT — see LICENSE.