Skip to content

fix(sixel): let tmux place sixel images itself when it can - #394

Closed
stubbedev wants to merge 1 commit into
3rd:masterfrom
stubbedev:fix/tmux-native-sixel
Closed

stubbedev wants to merge 1 commit into
3rd:masterfrom
stubbedev:fix/tmux-native-sixel

Conversation

@stubbedev

@stubbedev stubbedev commented Nov 19, 2026 •

Copy link
Copy Markdown

Problem

Since #366 the sixel backend always wraps images in tmux passthrough when running inside tmux. That helps tmux builds without sixel support, but when tmux renders sixel itself (tmux ≥ 3.4 built with --enable-sixel, with the outer terminal advertising sixel), passthrough sends the image untouched to the outer terminal. The backend's cursor move (ESC [ y;x H) is not wrapped, so tmux applies it inside the pane, but the outer terminal draws the image at its own cursor. Every image ends up at the top-left of the whole terminal window, stacked on top of each other and over other panes.

Seen with tmux 3.8 (--enable-sixel) and a sixel-capable alacritty build; tmux display -p '#{client_termfeatures}' reports bpaste,hyperlinks,focus,RGB,sixel,sync,title.

Fix

  • utils/tmux.lua reads the attached client's #{client_termfeatures} once at load and exposes has_native_sixel.
  • The sixel backend skips the passthrough wrapping when has_native_sixel is true. The DCS sequence then goes straight to the pane: tmux maps it into the pane at the pane-relative position the backend already moves to, clips it to the pane, and keeps it in place across splits.
  • The "passthrough may not be enabled" warning is not shown when tmux renders sixel natively, since passthrough is not needed then.

tmux without native sixel keeps the #366 behaviour unchanged.

Testing

  • Inside tmux 3.8 with sixel, has_native_sixel is true, so the image is written without the passthrough wrapper.
  • Outside tmux: is_tmux and has_native_sixel are both false and the code path is unchanged.

tmux 3.4+ built with sixel renders sixel output from panes on its own,
mapping it into the pane and keeping it in place across splits. Wrapping
the image in passthrough instead sends it untouched to the outer terminal,
where it is drawn at that terminal's cursor, not the pane-relative cursor
position the backend just moved to: images land at the top-left of the
whole window and stack on each other. When the attached client's
termfeatures include sixel, the DCS sequence now goes straight to the pane;
passthrough stays for tmux without native sixel.
@stubbedev

Copy link
Copy Markdown
Author

Closing this: I moved my setup to a terminal with the Kitty graphics protocol, so I can no longer test the sixel path and won't be maintaining this branch. The diagnosis in the description should still hold if someone wants to pick it up.

@stubbedev stubbedev closed this Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant