[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:

  1. 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).
  2. 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

  1. In tmux with allow-passthrough on, inside Ghostty, start claude with a function-hook plugin whose ui.render hook returns <Image source={{ file: '/abs/path.png', format: 'png' }} columns={40} rows={10} alt="diagram" />.
  2. 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):

  1. Send the graphics query and all kitty graphics APC sequences wrapped for passthrough (ESC P tmux; …with each ESC doubled… ESC \).
  2. Trust a positive answer to the graphics query rather than the XTVERSION name (see #99566).
  3. 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.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗