A modern terminal multiplexer inspired by tmux, rewritten from scratch in Zig.
The name traces a fun lineage through multiplexer history:
GNU Screen → scn (shortened) → szn — where the c became z to
nod at Zig, just like tmux was born from C roots and szn is its Zig successor.
tmux is great — but open its source and you'll find it's also quietly keeping the lights on for terminals that haven't been relevant since the 1990s. It queries a terminfo database at startup (a compatibility layer invented when hundreds of incompatible terminal hardware models existed), falls back to VT100 ACS line-drawing for terminals that can't speak UTF-8, juggles four different mouse protocols on every launch, and ships dedicated shims for HP-UX, AIX, and Solaris going all the way back to version 2.0. There's even a workaround in there for a PuTTY 0.63 scroll-wheel bug.
None of that is a criticism — it's what made tmux run everywhere. But if you're only targeting modern terminals, you're carrying all that weight for nothing.
szn makes a different bet: your display terminal speaks xterm-256color or
newer, full stop. That lets us hardcode modern behaviour — UTF-8 box-drawing,
SGR mouse, kitty keys — and skip the entire compatibility layer. Inside panes,
programs see TERM=tmux-256color (just like tmux), with szn translating between
the two. Less code, fewer surprises, and nothing left over from 1978.
- Modern terminals only — xterm-256color as the display baseline. Inside
panes, programs run under
TERM=tmux-256color. SGR mouse (1006), true-colour RGB, kitty extended keys, UTF-8, OSC 8 hyperlinks, and sixel image support are available out of the box. - Pragmatic mouse forwarding — szn speaks SGR mouse (1006) natively, but
also forwards legacy
\x1b[M3-byte format when a program only enables basic mouse mode (1000/1002). This keeps SGR as the default while tolerating programs whose terminfo lacks theXMcapability. Legacy 3-byte mouse forwarding (ESC[M) is performed automatically when a program enables basic mouse mode (1000/1002); no configuration is required. - Clean architecture — Zig's comptime, error unions, tagged unions, arena
allocators, and slices replace C macros,
goto-based cleanup, and manual memory management. - Zero learning curve — tmux config files, keybindings, and the familiar session → window → pane model are all preserved. If you know tmux, you already know szn.
szn tracks the cursor model with a modern Unicode width table (Unicode 15/16 East-Asian-Width + emoji-presentation). Ambiguous-width symbols that modern terminals render as width 2 — emoji (✅ ★ ♥), Dingbats, Miscellaneous Symbols, and regional indicators — are reported as width 2 by default, so the model cursor stays in lockstep with the real terminal and text never drifts.
Terminals don't agree on ambiguous width and there is no capability to query
it — each emulator hardcodes its own choice. If your terminal renders some
symbols as width 1, override per-codepoint to match it (mirrors tmux's
codepoint-widths):
# Tell szn U+2705 (✅) renders as width 1 on this terminal
set -g codepoint-widths "U+2705=1"
# Override a whole block
set -g codepoint-widths "U+2600-U+26FF=1"
# Clear all overrides → back to szn's defaults
set -g codepoint-widths ""Some modern terminals (such as Kitty or customized Alacritty builds) promote
single-width base characters followed by Variation Selector-16 (U+FE0F, e.g. 🕶️,
⚡️, ❤️) into 2-cell wide emoji presentation sequences. Standard POSIX
terminals (xterm, stock Alacritty, GNOME Terminal) keep them as 1 cell wide.
If you see leftover or ghost characters on lines containing emojis, your host terminal is likely expanding VS16 sequences to 2 cells while szn is in standard 1-cell mode. Turn this option on to match your terminal (mirroring tmux):
# In ~/.szn.conf or ~/.tmux.conf
set -g variation-selector-always-wide onThai and Lao typography in terminal emulators presents unique challenges, particularly with the spacing vowels Thai SARA AM (U+0E33 ำ) and Lao SARA AM (U+0EB3 ຳ), whose upper circle (NIKKAHIT / NIKHAHIT ํ / ໍ) visually attaches backward over the preceding base consonant:
- Kitty 0.49.1+ with
Tlwg Typo: Using Kitty 0.49.1 (or newer) with theTlwg Typofont from fonts-tlwg combined withsznprovides proper Thai and Lao text shaping and eliminates font shaper cluster teardown:- When Sara-Am is deleted or modified,
sznautomatically re-emits and repaints the preceding base consonant cleanly (preventing invisible consonant remnants). - When the preceding base consonant is edited or replaced while Sara-Am remains,
sznre-emits Sara-Am so it re-projects its mark onto the updated consonant. - In either case,
szninvalidates the diff cache and re-emits both cells in ascending column order, ensuring clean HarfBuzz font reshaping.
- When Sara-Am is deleted or modified,
- Alacritty with
Tlwg Typist: If using Alacritty, theTlwg Typistfont from fonts-tlwg is recommended instead. Alacritty never had a problem with Sara-Am, but it cannot renderTlwg Typocorrectly.
szn reads configuration from ~/.config/szn/szn.conf, ~/.szn.conf, ~/.config/tmux/tmux.conf, or ~/.tmux.conf on startup.
szn manages scrollback history per pane using a fixed-capacity circular ring buffer with line recycling, ensuring zero heap/arena allocations during steady-state scrolling.
The history capacity is configurable via the history-limit option (default: 2000, min: 0, max: 1000000):
# In ~/.szn.conf or ~/.tmux.conf
set -g history-limit 10000You can also change the scrollback capacity dynamically at runtime:
# Global (applies to all panes across all sessions)
szn set-option -g history-limit 50000
# Session-scoped (applies to panes in the active session)
szn set-option history-limit 5000By default, single-width characters followed by Unicode Variation Selector 16 (U+FE0F) preserve POSIX 1-cell width. To promote them to 2 cells with padding cells (matching modern terminals like Kitty and Alacritty), enable variation-selector-always-wide:
# In ~/.szn.conf or ~/.tmux.conf
set -g variation-selector-always-wide onAll core development phases (Phases 0 to 11) are fully implemented and complete. We have a robust, functional Zig terminal multiplexer featuring:
- High-performance grid engine with arena-allocated session/pane lifecycles.
- Client-server IPC over Unix sockets.
- 49 commands matching standard tmux behavior (including pane resizing, layout splits, paste buffers, clock-mode, and command-prompt).
- Standard VT100 wrap-pending and Background Color Erase (BCE) support for accurate rendering.
- Full multi-pane layouts, interactive copy mode, status bars, and config parsing (
.szn.conf). -
Advanced Text Reflow — automatically rewraps text on pane resizing, respecting CJK characters, combining marks, and Thai & Lao cluster integrity (including an
$O(1)$ syllable backtracking algorithm). See docs/text_reflow.md for full design details. - 1,082 unit and integration tests, all passing on Zig 0.16.0 and 0.17.0.
Running the suite:
zig build test. ThedetectNestedtest skips itself when run inside an szn pane (SZNset), so expect one skip there. See docs/build-run.md.
szn is designed to be lean:
- Startup: ~7.5 ms from launch to prompt (tmux: ~7.8 ms).
- Memory: ~2.2 MB RSS idle — szn uses ~2200 kB vs tmux's ~4000 kB.
- Binary size: 1,053,312 bytes stripped (~1,029 KB, x86-64 Linux), 834,864 bytes on macOS aarch64 (~815 KB) with Zig 0.17.0.
A hyperfine-based benchmark suite is included at bench.sh for tracking these metrics.
Check out progress.md for the full migration and feature breakdown. Development docs live under docs/development/, and release notes under docs/releases/.
Binary RPM packages for Fedora are available through Fedora Copr:
sudo dnf copr enable cwt/szn
sudo dnf install sznNote: EPEL 9 and EPEL 10 packages do not currently build due to the
ExclusiveArch: %{zig_arches}macro constraint inszn.spec, and will be enabled in a future release.
szn builds with either Zig 0.16.0 or Zig 0.17.0 — the source is kept compatible with both toolchains. See Zig version compatibility.
To build and run tests:
zig build
zig build testTo install the output binary to a specific path (for example, ~/.local/bin):
zig build -Doptimize=ReleaseFast --prefix ~/.localszn compiles on Zig 0.16.0 and Zig 0.17.0 from the same source. Zig
0.17 renamed or removed a number of standard-library APIs, so the port sticks
to the subset that exists in both releases and confines the unavoidable
version branches to two places: comptime @hasField gates in build.zig, and
a small shim module at src/compat.zig.
| Removed / changed in 0.17 | Portable form used here |
|---|---|
Allocator.dupeZ |
compat.dupeZ (backed by allocSentinel) |
std.fmt.bufPrintZ |
std.fmt.bufPrintSentinel(..., 0) |
std.meta.fields(T)[i].name |
std.meta.fieldNames(T) |
std.ascii.indexOfIgnoreCase |
compat.indexOfIgnoreCase |
[_]T{v} ** N array repetition |
std.mem.zeroes / comptime @memset |
.Debug optimize tag |
compat.is_debug_build |
Build.build_root |
Build.root (selected via @hasField) |
Both toolchains are verified locally: zig build test -Doptimize=ReleaseFast
reports 1082/1082 passing on 0.16.0 and on 0.17.0 from a clean cache.
Testing note. Zig 0.17's
std.testing.allocatoris a non-reusingSafeAllocator, so a use-after-free in a test that passes silently on 0.16 segfaults on 0.17 (see bug #562). Always run the suite on both toolchains.
Maintenance note. Zig 0.17 marks the old
.Debug/OptimizeModespellings as deprecated ("to be removed after 0.18.0"), so a future 0.18 bump will need the two@hasFieldgates inbuild.zigrevisited.src/compat.zigis the single place to extend for the next toolchain.
To start a new session (this automatically spawns the background server daemon if not already running and attaches to it):
sznTo attach to an existing running session:
szn attachTo list all available subcommands and get help:
szn help
szn help <command>For example, to split the active window vertically or horizontally:
szn split-window -v
szn split-window -hDebug logging is disabled by default for user privacy. szn does not write any log output unless explicitly configured.
To enable it, add one of these lines to your ~/.szn.conf:
set -g server-log-file default
set -g server-log-file /path/to/custom/szn.log
set -g client-log-file default
set -g client-log-file /path/to/custom/szn-client.log
default for the server writes to $XDG_STATE_HOME/szn/szn.log (usually
~/.local/state/szn/szn.log); default for the client writes to
~/.szn/szn-client.log. (The old log-file name is still accepted as an
alias for server-log-file.) Both are independent and disabled unless set.
Once logging is enabled, the default level is info (warnings, errors, and
key lifecycle events only). To change it, set the SZN_LOG environment variable
before starting szn:
SZN_LOG=debug szn # verbose — all debug lines
SZN_LOG=info szn # default
SZN_LOG=warn szn # warnings and errors only
SZN_LOG=err szn # errors only