Skip to content
cwtPublic

About

A modern terminal multiplexer inspired by tmux, rewritten from scratch in Zig.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

szn

License Zig Compatibility GitHub Release Ask DeepWiki

A modern terminal multiplexer inspired by tmux, rewritten from scratch in Zig.

Why the name?

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.

Why szn?

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.

Goals

  • 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[M 3-byte format when a program only enables basic mouse mode (1000/1002). This keeps SGR as the default while tolerating programs whose terminfo lacks the XM capability. 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.

Character Width & Emoji

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 ""

Variation Selector-16 (Emoji Presentation) & Leftover Characters

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 on

Thai & Lao Script: SARA AM (ำ / ຳ) Display Recommendations

Thai 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 the Tlwg Typo font from fonts-tlwg combined with szn provides proper Thai and Lao text shaping and eliminates font shaper cluster teardown:
    • When Sara-Am is deleted or modified, szn automatically 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, szn re-emits Sara-Am so it re-projects its mark onto the updated consonant.
    • In either case, szn invalidates the diff cache and re-emits both cells in ascending column order, ensuring clean HarfBuzz font reshaping.
  • Alacritty with Tlwg Typist: If using Alacritty, the Tlwg Typist font from fonts-tlwg is recommended instead. Alacritty never had a problem with Sara-Am, but it cannot render Tlwg Typo correctly.

Configuration

szn reads configuration from ~/.config/szn/szn.conf, ~/.szn.conf, ~/.config/tmux/tmux.conf, or ~/.tmux.conf on startup.

Scrollback History Limit

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 10000

You 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 5000

Emoji Presentation & VS16 Width

By 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 on

Status

All 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. The detectNested test skips itself when run inside an szn pane (SZN set), so expect one skip there. See docs/build-run.md.

Performance

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/.

Building & Installation

Fedora (Copr)

Binary RPM packages for Fedora are available through Fedora Copr:

sudo dnf copr enable cwt/szn
sudo dnf install szn

Note: EPEL 9 and EPEL 10 packages do not currently build due to the ExclusiveArch: %{zig_arches} macro constraint in szn.spec, and will be enabled in a future release.

Building from Source

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 test

To install the output binary to a specific path (for example, ~/.local/bin):

zig build -Doptimize=ReleaseFast --prefix ~/.local

Zig version compatibility

szn 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.allocator is a non-reusing SafeAllocator, 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 / OptimizeMode spellings as deprecated ("to be removed after 0.18.0"), so a future 0.18 bump will need the two @hasField gates in build.zig revisited. src/compat.zig is the single place to extend for the next toolchain.

Usage

To start a new session (this automatically spawns the background server daemon if not already running and attaches to it):

szn

To attach to an existing running session:

szn attach

To 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 -h

Debug Logging

Debug 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.

Log level

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

License

MIT

About

A modern terminal multiplexer inspired by tmux, rewritten from scratch in Zig.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages