What
tmux is a terminal multiplexer, a program that splits one terminal window into panes. Some terminals, such as kitty and iTerm2, can show images inline. Claude Code's handling of these images inside tmux was reworked:
- At startup, Claude Code asks tmux itself for facts about the pane (whether passthrough is allowed, focus events, pane position) and answers the kitty and iTerm2 image questions from that, logged as
tmux images: passthrough .... It no longer runstmux display-message -p #{client_termtype}there. - Image detection now has a separate
tmuxinput, true when TMUX is set and STY is not, so tmux is no longer treated like screen. Inside tmux, image support defaults to off, with the reason "env: inside tmux, where the terminal cannot be asked whether it reads files".CLAUDE_CODE_FORCE_TERMINAL_IMAGESstill overrides this. Screen is now labelled "env: inside screen". - When TMUX is set, images are present, tmux passthrough is not 'off' and kitty or iTerm2 support is detected, Claude Code tracks where the pane sits and re-sends or redraws images when the pane moves, the terminal regains focus or the window is resized. Sync markers are skipped in that case.
- Image escape codes are wrapped for tmux passthrough, and large iTerm2 images are split into
MultipartFileandFilePartchunks. - New diagnostic code queries tmux for
client_termtype,allow-passthrough,focus-eventsand other pane fields and produces fix messages such as "images inside tmux need tmux 3.3 or later with allow-passthrough and focus-events on" and "tmux does not know which terminal is outside it, so Claude Code draws no images here". No caller for it was seen. - A denial for tmux passthrough now comes with a "tmux-passthrough" fix tag.
Why
Inline images inside tmux are decided differently, so they may now show where they did not before, or stop showing. Where they cannot show, there is now a specific explanation of what to change in tmux.