[FEATURE] Kitty graphics (Image element) inside tmux with allow-passthrough
Status Open
Reported on v2.1.292
Maintainer reply None cached
Activity 1 comment · opened Oct 7, 2026
Summary
Inside tmux, Claude Code never enables kitty graphics, even when tmux has allow-passthrough on and the outer terminal supports the protocol (Ghostty, kitty). Images drawn by the Image element, including from function-hook plugins, fall back to their alt text.
Two parts of the capability check fail under tmux:
- The graphics query (
ESC _ Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA ESC \) is sent unwrapped. tmux does not pass a bare APC to the outer terminal; it treats it as a pane title instead (#99005). XTVERSION(CSI > q) is answered by tmux itself (tmux 3.7c), not by the outer terminal, so the kitty/ghostty name allowlist rejects it (the same allowlist #99566 describes).
Environment
- Claude Code 2.1.292, macOS
- tmux 3.7c,
set -g allow-passthrough on,TERM=tmux-256color - Ghostty 1.3.1 (kitty graphics with Unicode placeholders works through this tmux: a Textual app using
textual-image's TGP renderer shows images in a pane)
Steps to reproduce
- In tmux with
allow-passthrough on, inside Ghostty, startclaudewith a function-hook plugin whoseui.renderhook returns<Image source={{ file: '/abs/path.png', format: 'png' }} columns={40} rows={10} alt="diagram" />. - The transcript shows the dim alt text
diagram, not the picture.
Request
When $TMUX is set and allow-passthrough is on (tmux show -gv allow-passthrough):
- Send the graphics query and all kitty graphics APC sequences wrapped for passthrough (
ESC P tmux; …with each ESC doubled… ESC \). - Trust a positive answer to the graphics query rather than the
XTVERSIONname (see #99566). - Offer an explicit override for setups the probe cannot read, for example
CLAUDE_CODE_TERMINAL_GRAPHICS=kitty.
Since Claude Code already draws images with Unicode placeholders, the placeholder cells pass through tmux as ordinary text; only the APC transmissions need the passthrough wrapper.
Related: #99005, #99566, #79706.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗