Skip to content

feat: support Kitty graphics in tmux - #39

Open
kndrio wants to merge 1 commit into
codr1:mainfrom
kndrio:feat/tmux-kitty-graphics
Open

kndrio wants to merge 1 commit into
codr1:mainfrom
kndrio:feat/tmux-kitty-graphics

Conversation

@kndrio

@kndrio kndrio commented Oct 5, 2026

Copy link
Copy Markdown

Summary

  • support Kitty graphics through tmux passthrough and Unicode placeholders
  • enable allow-passthrough for the current pane and use tmux cell dimensions
  • preserve direct-terminal Kitty behavior and document the explicit renderer requirement

Validation

  • go test -race -count=1 -shuffle=on -timeout=2m ./client/...
  • go vet ./client/...
  • client build and help smoke test
  • website suite (the graphics behavior was also verified manually in Kitty through tmux)

@kitofr

kitofr commented Oct 20, 2026

Copy link
Copy Markdown

Tested this branch in Ghostty inside tmux, which the PR description says hasn't been validated yet. It works.

Environment

  • Ghostty 1.3.1, macOS 27.0.1 (arm64)
  • tmux 3.8, allow-passthrough on set globally in .tmux.conf
  • Termium built from f28e99d (dev-f28e99d6fccd), installed with npm run install:local, run as termium --renderer kitty

What worked

  • Pages render as real Kitty graphics inside a tmux pane, with no escape characters leaking into the pane.
  • Termium read the global allow-passthrough on through show -Ap and left it alone.
  • The placeholder grid is laid out as expected: one U+10EEEE row per terminal row, each with the correct row diacritic (checked with tmux capture-pane).
  • The cell size was right (8×17, which is what tmux reports as window_cell_width/height), and the Chromium viewport matched the pane exactly (3416×1275 for 427×75 cells). It came from TIOCGWINSZ or calibrateXterm(), so the new tmuxCellSize() fallback wasn't exercised in this setup.
  • Daily use: Neovim's markdown-preview.nvim opens Termium in a tmux split-window -d pane next to the editor. Re-opening replaces that pane, and the previews render fine.

Observations

  • Browsing has noticeable lag in tmux. I haven't measured it or compared it with running Termium outside tmux, so this is only an impression. The pane was large (≈427×75 cells), which may matter.
  • With --debug, the log shows Using default character size: 8x16 pixels even though the size actually used comes from tmux. setDefaultCharSize() logs first, and the TIOCGWINSZ/calibrateXterm() paths that then set the real size don't log anything. Logging the size that is finally used, and where it came from, would make this clearer.
  • kittyRowDiacritics has 297 entries, so a pane taller than 297 rows errors out instead of falling back to another renderer. That's unlikely in practice, but a fallback might be friendlier than an error.

Thanks for this! It's the piece that makes Termium usable for me day to day, since I live in tmux.

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.

2 participants