MuxDisplay

Overview

MuxDisplay is a Julia package that enables display of graphics from Julia REPLs running inside terminal multiplexers (tmux, WezTerm) by redirecting image output to dedicated panes, exploiting modern terminals' ability for displaying images. The package hooks into Julia's multimedia display system to intercept objects with an image representation, writes them to temporary files, and uses external imgcat programs to display them in specified multiplexer panes.

The package currently supports both tmux and WezTerm multiplexers with different display strategies. For tmux, it leverages OSC passthrough sequences (tmux ≥3.3) to communicate with the underlying terminal emulator. For WezTerm, it uses the native multiplexing capabilities and pane targeting. Key features include configurable target panes, image sizing control, automatic terminal protocol detection, and support for multiple image display programs including wezterm imgcat, iTerm's imgcat, and Kitty's icat.

Installation and Usage

MuxDisplay is registered in the Julia General registry and thus can be installed by running

] add MuxDisplay

in the Julia REPL.

It is recommended to install MuxDisplay into your main Julia environment. To use, run

using MuxDisplay

in the REPL. Assuming local usage, with tmux for output:

Determine the target pane: Press Ctrl+b q (or your tmux prefix + q) to show pane numbers, or run tmux display -p '#{pane_index}' in the target pane
Run e.g. MuxDisplay.enable(target_pane="1") to use the target pane 1

Or, for WezTerm:

Open a WezTerm window, run echo $WEZTERM_PANE to get the WezTerm pane number
Run, e.g., MuxDisplay.enable(multiplexer=:wezterm, target_pane=1) to use the target pane 1

See MuxDisplay.enable and the remainder of the documentation for details.

Alternatives

ITerm2Images – Display inline images using the iTerm2 protocol
KittyTerminalImages – Display inline images using the Kitty terminal graphics protocol
SixelTerm – Displaying inline images using the Sixel protocol

While these alternatives work well in direct terminal sessions, they face significant limitations inside multiplexers:

tmux compatibility issues: KittyTerminalImages does not support tmux passthrough; ITerm2Images displays at cursor location
Image persistence problems: Images disappear when scrolling or switching tmux windows/tabs
Placement issues: Inline images often appear in wrong locations within split panes
Sizing limitations: Images frequently appear too small or with poor aspect ratios

MuxDisplay addresses these shortcomings by using dedicated multiplexer panes instead of inline display, providing persistent images with configurable sizing and intelligent pane targeting.

Terminals and Multiplexers

WezTerm – Primary supported terminal emulator with built-in multiplexing and comprehensive image protocol support
tmux – Primary supported terminal multiplexer with OSC passthrough capabilities for image display
iTerm2 – macOS terminal emulator with native image protocol support
Kitty – Cross-platform terminal emulator with its own graphics protocol
Blink Shell iOS app – iOS SSH client with iTerm2 protocol support for mobile development workflows

Workflow Software

The following software is used in the Overview video, as part of a terminal-based workflow: