// ZTERMINAL — GPU-ACCELERATED TERMINAL EMULATOR

Quickstart

Build from source, then run the binary:

# debug build
cargo build
# → target/debug/zterminal

# release build
cargo build --release

macOS installer (.pkg)

make pkg builds a single installer that drops Zterminal.app into /Applications and the zterminal-icat helper into /usr/local/bin:

make pkg          # → target/release/osx/Zterminal-<version>.pkg

# install
sudo installer -pkg target/release/osx/Zterminal-<version>.pkg -target /

It builds a release binary, assembles + ad-hoc-signs the app bundle (stamping the version from zterminal/Cargo.toml), and packages both targets. The package is unsigned (no Developer ID), so first launch needs a right-click → Open. make app / make dmg build just the app bundle / disk image.

Full install + usage live in the README and man 5 zterminal.

Features

Inventions

Firsts that zterminal introduces to the terminal-emulator space. Each is, to our knowledge, novel — no shipping terminal emulator did it before.

Control panel & shortcuts

zterminal hosts an in-process GUI suite (rendered in an embedded WebView) for configuration and inspection. All of its state and logs live under ~/.zterminal. The control panel has Settings, Dashboard, tmux, Keybindings, Logs, and About tabs.

The command palette reaches every panel tab plus the terminal actions, and is searchable, so the action list stays out of the way. Every action is also a rebindable keyboard shortcut (see the Keybindings tab).

Splits (native tiling)

zterminal tiles natively — its own i3-style binary split tree, one independent shell + PTY per pane, GL-scissored into the window (no tmux required). Any pane splits in either direction, nests arbitrarily, and each pane renders in its own sub-viewport.

Layouts (⌘⇧L) save and restore a window's native split tree. Save captures the split geometry plus each pane's working directory and foreground command to ~/.zterminal/layouts/<name>.json; restore rebuilds the splits, respawns every pane in its directory and replants the saved command at the prompt (it is not run — you review and press Enter). Live process state isn't restored — panes return in the right layout/cwd as fresh shells. This is the native counterpart to the tmux Sessions save/restore.

All split, history, MRU, and layout actions are in the command palette too, so a key binding is never required — by design, no zterminal binding masks a shell or tmux key on any OS (macOS uses ⌘; Linux/Windows use ⌃⇧ or palette-only).

Inline graphics

zterminal renders images inline in the grid via the GPU, supporting all three common terminal image protocols:

• Kitty graphics protocol — transmit (a=t), transmit-and-display (a=T), put-by-id (a=p), support query (a=q, so capable tools auto-detect zterminal), and delete (a=d); RGB / RGBA / PNG (f=24/32/100); direct and file (t=f) transmission; zlib compression (o=z); chunked payloads; stacking order (z=); Unicode placeholders (U=1) for grid-anchored placement; and animation (a=f frames + a=a play/stop/loop control), played back on a timer.
• Sixel — ESC P … q … ST, with RGB and HLS color registers, run-length, and raster attributes.
• iTerm2 inline images — OSC 1337;File=… (imgcat), any format the decoder handles (PNG / JPEG / GIF).

Images are uploaded as GPU textures and blitted over the cells they occupy; they scroll with the buffer, clip at pane edges, draw behind (z < 0) or over the text, and are freed when they scroll out of the scrollback. A scanner sits ahead of the escape-sequence parser to extract image sequences (Kitty APC, Sixel DCS, iTerm2 OSC) — ordinary text and control sequences are untouched. Sequences wrapped by tmux (ESC Ptmux;…, with set -g allow-passthrough on) are unwrapped and decoded, and Kitty's Unicode-placeholder placement also works through tmux.

Background image

zterminal can draw an image behind the cells (a terminal / desktop background), set in config rather than via an escape sequence — so it works everywhere, including inside tmux:

[window]
opacity = 0.85                            # < 1 so the image shows through cells
background_image = "~/Pictures/wall.png"
background_image_opacity = 1.0            # 0.0–1.0

The image is uploaded once as a GPU texture and drawn each frame (cover: fills the window preserving aspect, cropping overflow), behind any cell whose background is the default color — lower opacity to reveal more of it. Reloads live when the path changes; PNG / JPEG / GIF.

Displaying an image

extra/zterminal-icat picture.png  # bundled, zero deps (base64 + sips on macOS)
kitten icat picture.png           # kitty
timg picture.png                  # brew install timg
chafa picture.png                 # brew install chafa  (kitty/sixel/iterm2)
img2sixel picture.png             # libsixel
imgcat picture.png                # iTerm2's imgcat

The bundled extra/zterminal-icat needs no extra tools — it emits the Kitty protocol from any image with just base64 (and sips, on macOS, to convert non-PNG input). It works inside tmux with no setup: it enables allow-passthrough itself and places the image via Kitty Unicode placeholders, so the picture survives tmux redraws.

tmux integration

zterminal speaks tmux's client/server wire protocol directly to the server's Unix socket (imsg framing, protocol version 8) — no tmux subprocess. The target server is resolved from $TMUX or the default socket.

The tmux tab is a live manager: the full session → window → pane tree, each pane with a capture-pane text preview. Click a pane to switch the attached client to it; toolbar and per-session buttons create/split/zoom/rotate/kill windows, panes, and sessions. It refreshes while the tab is open.

• Sessions (⌃⌘S) — save and restore the full tmux layout, a native replacement for tmux-resurrect/continuum. Save snapshots every session → window → pane (with exact window_layout, cwd, command) to ~/.zterminal/snapshots/; restore rebuilds it over the wire protocol, including the exact split geometry and active window/pane, and can start a server if none is running. Opt-in relaunch re-runs each pane's full command line with arguments; Save pane contents replays each pane's scrollback. A tmux_restore_processes pref gives the resurrect-style whitelist. Mark a snapshot Set startup to auto-restore on launch.
• Broadcast (⌃⌘B) — sends keystrokes to a chosen set of panes at once, across any windows/sessions, which native tmux can't do (synchronize-panes is whole-window). Per-window synchronize-panes can also be toggled from the same overlay.
• Cross-pane search (⌃⌘P) — fuzzy-matches (shared ZGui.fzf) the recent scrollback of every tmux pane at once: type a query, see panes ranked by fzf score with matched characters highlighted, and press Enter (or click) to jump to that pane.

The command palette includes tmux: actions — new window, split horizontal/vertical, next/previous window/session, zoom/rotate/break pane, next layout, choose-tree switcher, new/kill session, detach. The Dashboard shows the server's sessions (name, window count, attached state).

Configuration

zterminal does not create a config file for you. It looks for one in the following locations (first match wins):

1. $XDG_CONFIG_HOME/MenkeTechnologies/zterminal.toml
2. $XDG_CONFIG_HOME/zterminal.toml
3. $HOME/.config/MenkeTechnologies/zterminal.toml
4. $HOME/.zterminal.toml
5. /etc/MenkeTechnologies/zterminal.toml

On Windows: %APPDATA%\zterminal\zterminal.toml. Configuration is documented in man 5 zterminal.

terminfo

zterminal sets TERM to zterminal when that terminfo entry is installed, otherwise it falls back to xterm-256color. The terminfo source ships in extra/zterminal.info.

Repository & links

• Source — GitHub repo
• Issues — issue tracker
• README — README on GitHub (features, control panel, splits, inline graphics, tmux, build, configuration).
• Inventions — docs/INVENTIONS.md
• Manual — man 1 zterminal and man 5 zterminal (configuration).