Skip to content

Conversation

@ogulcancelik
Copy link
Contributor

Adds support for rendering inline images inside tmux using the Kitty graphics protocol's unicode placeholder mode.

Problem

When running pi inside tmux + Ghostty/Kitty/WezTerm:

  • Direct Kitty graphics sequences get eaten by tmux (without passthrough) or cause "stuck" images (with passthrough)
  • Images orphan on screen redraws, pane switches, or scrolling

Solution

Implement the protocol's multiplexer-safe mode:

  • Detect tmux via TMUX env var
  • Check allow-passthrough setting before attempting image display
  • Wrap sequences in tmux passthrough escapes
  • Use virtual placement (U=1) with unicode placeholders (U+10EEEE)
  • Encode row positions via diacritics (per official spec)

Backward Compatibility

  • Outside tmux: behavior unchanged, direct placement as before
  • Inside tmux without allow-passthrough: gracefully falls back to text description ([Image: foo.png 800x600])
  • Inside tmux with allow-passthrough all: full image rendering

User Requirement

For images to render in tmux, users need in their tmux.conf:

set -g allow-passthrough all

use unicode placeholders and passthrough escapes to render
inline images correctly inside tmux without orphaning on redraws
@ogulcancelik ogulcancelik force-pushed the feat/tmux-kitty-images branch from a7a7ad1 to 046ea9d Compare January 22, 2026 18:01
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