Platform Compatibility

Platform, Emulator, Multiplexer, and Remote Compatibility

Use this skill when a TUI must behave across operating systems, terminal emulators, multiplexers, SSH sessions, containers, CI, or embedded pseudo-terminal hosts.

Compatibility mindset

Terminal capability is a chain: application library, OS console or PTY, shell, multiplexer, SSH transport, terminal emulator, font, theme, and user settings. A feature is reliable only if each link preserves it. Treat every advanced protocol as optional unless the app owns the whole environment.

Support matrix to define

For production TUIs, document and test:

• OS: Linux, macOS, Windows Terminal, classic conhost if supported, WSL, containers.
• Terminal emulators: Terminal.app, iTerm2, Kitty, Alacritty, WezTerm, foot, GNOME Terminal/VTE, Konsole, Windows Terminal.
• Multiplexers: tmux, GNU screen, Zellij.
• Remote: SSH, mosh-like links, serial/slow links, jump hosts, agent forwarding policy.
• Shell and locale: UTF-8 locale, code page on Windows, TERM and terminfo availability.
• Constraints: minimum size, color level, Unicode/ASCII mode, mouse/paste support.

Platform rules

• On Windows, distinguish Windows Terminal/ConPTY from legacy console hosts. Enable virtual terminal processing when using low-level console APIs, prefer UTF-8, and test child-process hosting through ConPTY when relevant.
• On Unix-like systems, handle PTY semantics, SIGWINCH, termios raw/cbreak restoration, process signals, and locale-dependent encoding.
• On macOS, Terminal.app and iTerm2 differ in proprietary protocols, option-key behavior, clipboard/image features, and default color/theme settings.

Multiplexer rules

• tmux/screen/Zellij can rewrite TERM, filter OSC/DCS, transform mouse events, mediate alternate screen, and require passthrough wrappers for clipboard, images, truecolor, or keyboard protocols.
• Always test inside and outside the multiplexer versions you claim.
• Prefer text fallbacks over hard dependencies on OSC 52, OSC 8, Kitty graphics, iTerm2 images, focus events, or extended keyboard protocols.

Remote rules

• Minimize write volume and cursor churn over SSH.
• Coalesce resize storms and high-frequency metrics.
• Do not assume clipboard, local file paths, image protocols, or agent forwarding are present or allowed.
• Provide low-bandwidth, no-mouse, no-animation, plain, and batch modes.

Reference files

• references/emulator-platform-matrix.md - OS, emulator, PTY, and feature compatibility guidance.
• references/multiplexer-remote.md - tmux/screen/Zellij, SSH, latency, passthrough, and resize practices.

Emulator and Platform Compatibility Matrix

Feature classes

Per-environment quirks

Windows

• Windows Terminal plus ConPTY is the primary modern target: broad VT support, Unicode rendering, tabs/panes, GPU text rendering, themes, and copy/paste integration.
• Classic console hosts can require ENABLE_VIRTUAL_TERMINAL_PROCESSING for output and appropriate input modes for VT input. Older hosts may not behave like Unix PTYs.
• ConPTY is a pseudo-console API, not a byte-for-byte Unix PTY clone. It can affect buffering, dimensions, process lifetime, signal behavior, and test harness design.
• Prefer framework support such as Crossterm, tcell, Terminal.Gui, or Spectre.Console rather than hand-rolled Win32 console mode code unless necessary.

Unix-like PTYs

• PTYs preserve the historical terminal model: termios modes, process groups, signals, SIGWINCH, and byte streams.
• Raw mode disables canonical line editing and may suppress signal generation depending on flags; restore termios on every exit path.
• Locale matters. A non-UTF-8 locale can break Unicode rendering even if the emulator can display it.

macOS Terminal.app and iTerm2

• Terminal.app is conservative and integrates with macOS defaults. Test Option/Alt behavior, theme contrast, and clipboard expectations.
• iTerm2 offers proprietary image, inline file, notification, and escape-code extensions. Use them only as enhancements with clear fallback.
• Both can run remote shells or multiplexers; do not infer local capabilities from remote environment variables alone.

Linux desktop emulators

• GNOME Terminal and many others use VTE; expect solid CSI/SGR support and common xterm extensions.
• Konsole, foot, Kitty, Alacritty, and WezTerm have different priorities: performance, protocol extensions, GPU rendering, Wayland/X11 integration, keyboard handling, and configuration depth.
• GPU-accelerated terminals can render quickly, but the application still pays for bytes sent, parser work, and SSH latency. Diff and batch writes remain important.

Multiplexer and remote rules

• Inside tmux/screen/Zellij, the inner TERM often hides outer-terminal capability. Prefer conservative behavior plus explicit user overrides.
• OSC 52, OSC 8, truecolor, focus events, and image protocols may be blocked or require passthrough settings.
• SSH adds latency and can strip environment variables. Do not assume TERM_PROGRAM reflects the local emulator on a remote host.
• Container shells often lack locale, terminfo, and real TTY allocation unless launched with -it.

Capability strategy

1. Ask for user intent through flags first: --plain, --ascii, --no-mouse, --color, --no-tui. 2. Use libraries and terminfo where available. 3. Treat environment variables as hints, not proof. 4. Bound terminal queries with timeouts and handle absent or malformed replies. 5. Keep a conservative path that requires only text, newline, and ordinary input.

Multiplexer and Remote Terminal Reference

tmux

• tmux often advertises a tmux-specific TERM, so outer terminal features may need tmux configuration to pass through.
• Truecolor support can require appropriate terminal-overrides or feature flags depending on tmux version and site config.
• OSC 52 clipboard access is configurable and often intentionally restricted.
• DCS passthrough can carry some sequences to the outer terminal, but relying on it makes behavior version- and configuration-dependent.
• Mouse events are mediated by tmux; test panes, copy mode, alternate screen, wheel scrolling, and drag behavior.

GNU screen

• screen is more conservative and may filter or transform modern sequences.
• Expect weaker support for OSC/DCS extensions, focus events, truecolor configuration, and advanced keyboard protocols.
• Provide 16/256-color and no-clipboard fallbacks.

Zellij

• Zellij has its own pane, keybinding, and mode model. It may intercept shortcuts and mediate copy, mouse, and layout behavior.
• Test app shortcuts against Zellij defaults. Avoid assuming Ctrl/Alt chords are available.

Passthrough policy

Use passthrough only for optional enhancement. Core workflows should not depend on terminal images, clipboard writes, focus notifications, or private keyboard protocols surviving a multiplexer chain. If a feature is attempted, detect failure or timeout and continue visibly.

SSH and remote sessions

• Remote TERM describes what the remote side believes the terminal is; it may not reflect the local emulator accurately, especially through jump hosts or multiplexers.
• Resize propagation can be delayed or lost; treat SIGWINCH/resize events as hints and periodically tolerate stale dimensions.
• Clipboard and image protocols cross a trust boundary. Many environments block them for good reason.
• Agent forwarding is unrelated to terminal rendering but is a security-sensitive remote feature. Do not require it for UI behavior; clearly separate authentication failures from terminal capability failures.

Latency and bandwidth tactics

• Render on state change, not busy loops.
• Batch writes and flush once per frame.
• Prefer dirty-region/cell-diff updates over full clears.
• Avoid high-frequency mouse hover effects over SSH unless throttled.
• Cap dashboard updates to the rate users can read.
• Offer --no-animation, --low-bandwidth, or reduced refresh options.

Remote-safe UX

• Keep keyboard navigation complete; mouse may be disabled by SSH clients, multiplexers, or user preference.
• Avoid local-only assumptions such as opening local files, using local clipboard, or rendering local images from remote paths.
• Preserve useful scrollback in non-full-screen mode for logs and long-running commands.
• Provide recovery instructions that work remotely: quit keys, reset, stty sane, and --no-tui.