szn

Architecture Overview

szn is a from-scratch rewrite of tmux in Zig, targeting Zig 0.16.0 and 0.17.0. It keeps tmux’s client/server shape but replaces imsg with a tiny length-prefixed packet protocol and uses arena allocation per session/pane instead of reference counting.

Referencing convention: this document names symbols and files, not line numbers. Line citations drift every time a file is edited — an earlier revision of this page carried ~25 of them and nearly all had rotted. To find a symbol, grep for its name.

Process model

Entry point is src/main.zig. A single szn binary is both client and server; it decides which role to take at startup.

Key distinction from classic tmux: the original process is the client and the server is the forked child. The server does not spawn the client’s attaching process.

Server event loop

src/server/loop.zig is a poll()-based loop. Loop owns an fds: ArrayList(FdEntry) plus reusable pollfds/event_buf. pollOnce rebuilds the pollfd[] and calls std.posix.poll. FdEntry.udata (*anyopaque) tags which pane a PTY fd belongs to.

Server.run() per iteration:

Watched fds: listener socket, each client fd, and each pane PTY master fd (registered via watchPanePty). When the last session is gone the loop stops (loop.running = false).

Data model

Type File Notes
Session session.zig Arena allocator, windows: ArrayList(*Window), active_window, per-session Options.
Window window.zig panes: ArrayList(*Pane), a binary-split Layout tree, options.
Pane window.zig screen: Screen, optional pty, optional parser, dirty, back-pointer to window.

A pane’s PTY is created in Pane.spawn() via Pty.open() + Pty.spawn(...), which fork()s the shell child — not the client. The pane id is passed to the child via the SZN/SZN_PANE env vars. The PTY master fd is registered with the loop.

Rendering

src/server/render.zig holds Display, the server-side renderer that emits escape sequences to a client fd (or captures into a buffer for one .output packet).

src/tty/tty.zig provides Term, a lower-level emitter with cached cx/cy/fg/bg/attrs to minimize redundant escapes; used in tests and as the conceptual building block.

Input parsing

InputParser in src/input.zig is a byte-at-a-time state machine (see its State enum: ground, ESC, CSI, OSC, and a rich DCS set including sixel). Attached per pane and fed by Pane.feedPty.

It handles cursor moves, erase, insert/delete line/char, scroll, DECSET/DECRST, SGR, terminal queries (DA1/DA2, DSR, DECRQM, XTSMGRAPHICS sixel negotiation), sixel DCS (accumulated then Screen.addSixelImage, which buffers the image in pending_sixel until a measured cell size is known — see cell_size_needs_refresh), OSC title/clipboard, and kitty keyboard (CSI u).

Screen & grid

Command subsystem

Commands are described by CmdEntry (src/cmd/cmd.zig) and assembled into a comptime table (CMD_TABLE, exposed through cmdTable()) from the commands.* instances — 48 entries as of 2026-08-30. parse/lookup tokenize and validate args; dispatchCommand (src/server/dispatch.zig) calls exec(server) and returns a DispatchResult (.ready/.err/.exit/.wait). Handlers operate directly on *Server.

Directory layout

Design principles (from AGENTS.md)