Skip to content

Terminal Compatibility

mdink edited this page Feb 28, 2026 · 1 revision

Terminal Compatibility

Image protocol support matrix

Terminal Protocol Images Notes
Kitty Kitty graphics ✅ Native support
WezTerm Kitty graphics ✅ Native support
iTerm2 iTerm2 inline images ✅ macOS only
Alacritty ≥ 0.13 Sixel ✅ Requires Sixel build flag
foot Sixel ✅ Wayland; excellent Sixel support
xterm Sixel ✅ Enable with -ti 340 or XTerm*decTerminalID: vt340
mlterm Sixel ✅
Windows Terminal — ⚠️ Half-block art fallback; no Sixel/Kitty support yet
tmux — ⚠️ Degrades to half-blocks; passthrough possible but unreliable
GNU Screen — ⚠️ No graphics protocol support
All others — alt text Falls back to image alt text; use --no-images

Legend:

  • ✅ Full image rendering
  • ⚠️ Degraded (half-block art or passthrough issues)
  • alt text = the ![alt text](url) description is shown as styled text

Protocol detection

On startup (before entering the TUI), mdink briefly enables raw mode and sends a terminal inquiry sequence to auto-detect the best supported protocol. Detection happens in this order:

  1. Kitty graphics protocol — query via \x1b_Ga=q\x1b\\
  2. iTerm2 inline protocol — checks $TERM_PROGRAM for iTerm.app
  3. Sixel — query via \x1b[c (primary DA); look for 4 in the response
  4. Half-block art — fallback when nothing else is detected

The detection is non-fatal: if the query times out or the terminal does not respond, mdink falls back to half-block art (or plain alt text if --no-images is set). You can always force no images with --no-images.


Disabling image rendering

# For a single session
mdink --no-images README.md

# Via environment variable
export MDINK_STYLE=dark

# Permanently via config file
echo '{"no_images": true}' > ~/.config/mdink/config.json

When images are disabled, ![alt text](url) renders as [🖼 alt text] with dim styling.


Multiplexer notes

tmux

tmux intercepts terminal escape sequences, which can degrade or break Sixel and Kitty graphics passthrough. Results vary by tmux version and the outer terminal:

  • tmux ≥ 3.3 has experimental Sixel support (enable with allow-passthrough on).
  • Kitty graphics passthrough is unreliable; use --no-images for consistent output in tmux.

GNU Screen

Screen does not support any graphics protocol. Use --no-images.

SSH sessions

Image rendering over SSH depends on the local terminal emulator's support. The detection query is sent to the local terminal (via the PTY), so if your local terminal supports Sixel or Kitty, images should work over SSH without any extra configuration.

Clone this wiki locally