Skip to content

Add tmux support for kitty graphics protocol#135

Open
ibehnam wants to merge 6 commits intolusingander:masterfrom
ibehnam:tmux_support
Open

Add tmux support for kitty graphics protocol#135
ibehnam wants to merge 6 commits intolusingander:masterfrom
ibehnam:tmux_support

Conversation

@ibehnam
Copy link
Copy Markdown

@ibehnam ibehnam commented Feb 26, 2026

Summary

  • Adds tmux support for terminals using the kitty graphics protocol (Kitty, Ghostty) via Unicode placeholders (U+10EEEE with diacritics) and DCS passthrough
  • Adds runtime kitty protocol detection by querying the terminal directly, removing reliance on env vars alone
  • Adds GHOSTTY_RESOURCES_DIR env var fallback so Ghostty is correctly detected inside tmux (where $TERM becomes tmux-256color)
  • Uses actual pixel cell sizes for graph image generation instead of hardcoded values
  • Adds libc dependency for non-blocking stdin reads during terminal capability detection

Based on the work from #99 (by @meck) and #101 (by @ky-shinsoft), rebased onto current master with conflict resolution and the Ghostty-in-tmux detection fix.

Terminal support matrix

Terminal Direct In tmux
Kitty Kitty protocol Kitty + DCS passthrough + Unicode placeholders
Ghostty Kitty protocol (query) Kitty protocol (GHOSTTY_RESOURCES_DIR fallback)
iTerm2 iTerm2 protocol Not supported
WezTerm iTerm2 protocol Not supported

Test plan

  • Tested serie in Ghostty + tmux — graph renders correctly
  • Test in Kitty + tmux
  • Test in Kitty directly
  • Test in iTerm2 directly (should still work via iTerm2 protocol)
  • Verify no regression in non-tmux terminals

meck added 5 commits February 25, 2026 22:51
The kitty unicode placeholder protocol does not change
the aspect ratio when presenting images, this can
lead to gaps between images
Autodetection does not match pregenerated images
This is much more reliable then checking for envars,
especially if connected via SSH or tmux as the envars
might be missing, and should work automatically with
new terminals supporting the kitty protocol
@ibehnam
Copy link
Copy Markdown
Author

ibehnam commented Feb 26, 2026

In ghostty:

image

Added entries for:
- macOS system files (.DS_Store, .Trashes, etc.)
- IDE config directories (.claude, .codex, .opencode)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
@Mo0rBy
Copy link
Copy Markdown

Mo0rBy commented Mar 17, 2026

Is there anyway I can help test this?
I use Wezterm + tmux as mentioned in the Issue link above ^^

@gogongxt
Copy link
Copy Markdown

LGTM

@yaslama
Copy link
Copy Markdown

yaslama commented Mar 18, 2026

Is this PR still needed? See tmux/tmux#4902 and https://github.com/tmux/tmux/tree/ta/kitty-img

@Mo0rBy
Copy link
Copy Markdown

Mo0rBy commented Mar 23, 2026

Is this PR still needed? See tmux/tmux#4902 and https://github.com/tmux/tmux/tree/ta/kitty-img

I think it potentially could be.
I highlight on the issue linked above that image rendering with tmux works fine with Yazi (terminal file manager tool).

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.

5 participants