szn

Migration Plan: tmux (C) → szn (Zig)

Why Zig?

Problem in C Zig Solution
compat/ — 46 files, 7,108 lines of portability shims std.os, std.fs, std.net — standard library covers all targets
configure.ac + Makefile.am — 1,319 lines of autotools build.zig — 50 lines, built-in
queue.h / tree.h — 1,281 lines of macro-based data structures std.TailQueue, std.Treap, std.ArrayList — generic, type-safe
imsg — 1,530 lines of custom IPC framework Unix sockets + std.io.Writer / packed structs
osdep-*.c — 844 lines of platform probing Zig comptime + @import("builtin").os.tag
xmalloc.c / OOM-on-NULL pattern try allocator.alloc(u8, n) — alloc returns error, not null
TAILQ_FOREACH / RB_INSERT macros for (list.first) \|node\| { ... } — real iteration
if (x == NULL) return (-1) everywhere Error unions — try propagates automatically
goto cleanup defer — scoped, composable
Function pointer tables + void* casts Tagged unions — switch exhaustiveness checked
Integer state machines Zig unions with variants per state

What We’re Dropping

Dead Platforms

Dead Features

Dead Terminal Protocols

Dead Build System

Compat Layer

Every file in compat/ goes away. Zig’s stdlib provides all of it.


Testing-First Phases

Every phase has one deliverable: zig build test passes. Phases are ordered so each can be implemented and tested in isolation without needing later phases.

Phase 0:  Scaffolding + test harness      (zig build test: compiles, 0 tests)
Phase 1:  Grid + Colour + Screen          (zig build test: 40+ tests, no I/O)
Phase 2:  Key + Session + Window + Layout (zig build test: 60+ tests, no I/O)
Phase 3:  Options + Config                (zig build test: 80+ tests, no I/O)
Phase 4:  TTY output engine               (zig build test: 100+ tests, strings only)
Phase 5:  TTY input parsing               (zig build test: 120+ tests, strings only)
Phase 6:  Input escape parser             (zig build test: 240+ tests, strings only)
Phase 7:  Format + Status                 (zig build test: 270+ tests, strings only)
Phase 8:  Mode + Key bindings             (zig build test: 300+ tests, strings only)
Phase 9:  Client-server IPC               (zig build test: 330+ tests, integration)
Phase 10: Commands                        (zig build test: 450+ tests, integration)
Phase 11: Full integration                (zig build test: 490+ tests, full stack)

Phase 0: Scaffolding + Test Harness

Goal: zig build produces a binary, zig build test compiles and passes.

Files

build.zig              — build target + test target
build.zig.zon          — package manifest
src/main.zig           — stub entry point
src/test.zig           — test runner (imports all module tests)
src/err.zig            — shared error sets (later removed; see bug #36)
src/log.zig            — logging wrapper

Historical note: this is the plan as written, not the current tree. src/err.zig no longer exists — its SznError set turned out to be dead code and was deleted (bug #36). Per-subsystem error sets are now declared locally in each module instead.

Test structure

// src/test.zig
comptime {
    // Phase 1 modules imported as they're created
    // _ = @import("grid.zig");
    // _ = @import("colour.zig");
}

Acceptance

$ zig build test
All 0 tests passed.

Phase 1: Grid + Colour + Screen

Goal: Grid data structure, colour types, and screen wrapper — all pure data, fully unit-testable without I/O.

grid.zig (~800 lines)

Replaces grid.c, grid-view.c, grid-reader.c (~2,300 lines of C).

pub const Cell = packed struct(u64) {
    char: u24,          // Unicode code point
    attr: Attr,         // bold, dim, italic, underline, blink, reverse, etc.
    fg: Colour,         // foreground colour
    bg: Colour,         // background colour
    _padding: u6,
};

pub const Attr = packed struct(u16) {
    bold: bool = false,
    dim: bool = false,
    italic: bool = false,
    underline: bool = false,
    blink: bool = false,
    reverse: bool = false,
    concealed: bool = false,
    strikethrough: bool = false,
    overline: bool = false,
    double_underline: bool = false,
    curly_underline: bool = false,
    _padding: u5,
};

pub const Colour = packed struct(u32) {
    tag: ColourTag,     // indexed, rgb, default, terminal
    value: u24,         // palette index or RGB value
};

pub const Grid = struct {
    lines: std.ArrayListUnmanaged(GridLine),
    width: u32,
    height: u32,
    // ...
};

Tests (20+):

colour.zig (~300 lines)

Replaces colour.c (~1,179 lines of C).

pub const ColourTag = enum(u8) {
    indexed,   // colour0-colour255
    rgb,       // #RRGGBB
    default_,  // default colour
    terminal,  // terminal colour
};

pub fn parse(hex: []const u8) !Colour { ... }
pub fn paletteIndex(n: u8) Colour { ... }
pub fn toRgb(c: Colour) ?[3]u8 { ... }

Tests (15+):

screen.zig (~200 lines)

Replaces screen.c (~900 lines of C).

pub const Mode = packed struct(u32) {
    insert: bool = false,
    keypad: bool = false,     // MODE_KKEYPAD — kept for compat, not emitted
    line_wrap: bool = true,
    mouse_standard: bool = false,
    mouse_button: bool = false,
    mouse_utf8: bool = false,  // DECSET 1005 — not emitted, kept for input compat
    mouse_sgr: bool = false,
    focus: bool = false,
    paste: bool = false,
    alt_screen: bool = false,
    cursor: bool = true,
    origin: bool = false,
    _padding: u20,
};

pub const Screen = struct {
    grid: Grid,
    cursor: Cursor,
    mode: Mode,
    // ...
};

Tests (10+):

Phase 1 Acceptance

$ zig build test
All 45 tests passed.

Phase 2: Key + Session + Window + Layout

Goal: Core data types for session management — pure data, no I/O.

key.zig (~300 lines)

Replaces parts of key-string.c, tmux.h key enum, input-keys.c.

pub const Key = union(enum) {
    char: u21,              // Unicode character
    function: Function,     // F1-F12
    arrow: Arrow,           // up/down/left/right
    modifier: ModifierSet,  // ctrl, alt, shift, meta combinations
    // ...
};

pub const Modifier = packed struct(u8) {
    ctrl: bool = false,
    alt: bool = false,
    shift: bool = false,
    meta: bool = false,
    _padding: u4,
};

// Parse a CSI sequence like \e[1;5A → Ctrl+Up
pub fn parseCsi(seq: []const u8) !Key { ... }

// Format a key to its canonical string representation
pub fn format(key: Key) []const u8 { ... }

Tests (15+):

session.zig (~200 lines)

pub const Session = struct {
    id: u32,
    name: []const u8,
    windows: std.ArrayListUnmanaged(*Window),
    active_window: ?*Window,
    options: Options,
    // ...
};

Tests (5+): create, rename, attach/detach windows.

window.zig (~300 lines)

pub const Window = struct {
    id: u32,
    name: []const u8,
    layout: Layout,
    panes: std.ArrayListUnmanaged(*Pane),
    active_pane: ?*Pane,
    // ...
};

pub const Pane = struct {
    id: u32,
    screen: Screen,
    // ...
};

Tests (10+): create, rename, add/remove panes.

layout.zig (~400 lines)

Replaces layout.c, layout-custom.c, layout-set.c.

Binary tree of splits (same algorithm as tmux):

pub const Layout = struct {
    root: *Node,
};

pub const Node = union(enum) {
    leaf: *Pane,
    split: struct {
        direction: SplitDir,  // horizontal, vertical
        proportion: f64,
        a: *Node,
        b: *Node,
    },
};

Tests (15+):

Phase 2 Acceptance

$ zig build test
All 90 tests passed.

Phase 3: Options + Config

Goal: Options storage and config file parser — pure data, no I/O.

options.zig (~400 lines)

Replaces options.c, options-table.c (~1,900 lines of C).

Comptime-generated option definitions:

pub const OptionType = enum {
    number,
    string,
    colour,
    key,
    flag,
    choice,
};

pub const Option = struct {
    name: []const u8,
    type: OptionType,
    default: union {
        number: i64,
        string: []const u8,
        // ...
    },
};

pub const Options = struct {
    map: std.StringHashMap(OptionValue),
    // ...
};

Tests (15+): set, get, unset, default values, type validation.

cfg.zig (~500 lines)

Replaces cfg.c (~600 lines of C).

Parse tmux-compatible config syntax:

Tests (15+):

Phase 3 Acceptance

$ zig build test
All 120 tests passed.

Phase 4: TTY Output Engine

Goal: Write escape sequences to a real terminal. Testable by capturing output to a buffer instead of a real FD.

tty.zig (~600 lines)

Replaces tty.c, tty-draw.c (~3,500 lines of C).

pub const Term = struct {
    // Hardcoded escape sequences — no terminfo
    const caps = comptime blk: {
        // Validate all sequences at compile time
        break :blk std.ComptimeStringMap([]const u8, .{
            .{ "cuu1", "\x1b[A" },
            .{ "cud1", "\x1b[B" },
            .{ "cuf1", "\x1b[C" },
            .{ "cub1", "\x1b[D" },
            .{ "el",   "\x1b[K" },
            .{ "ed",   "\x1b[J" },
            .{ "smcup", "\x1b[?1049h" },
            .{ "rmcup", "\x1b[?1049l" },
            // ~40 entries total
        });
    };

    writer: std.io.AnyWriter,
    // ...
    
    pub fn writeEscape(self: *Term, name: []const u8) !void { ... }
    pub fn setCursor(self: *Term, x: u32, y: u32) !void { ... }
    pub fn setColour(self: *Term, fg: ?Colour, bg: ?Colour) !void { ... }
    pub fn clearScreen(self: *Term) !void { ... }
    pub fn writeCell(self: *Term, cell: Cell) !void { ... }
};

Tests (20+):

Phase 4 Acceptance

$ zig build test
All 140 tests passed.

Phase 5: TTY Input Parsing

Goal: Parse terminal input (key presses, mouse events) into Key events.

tty_key.zig (~400 lines)

Replaces tty-keys.c, input-keys.c (~2,600 lines of C).

Only modern key sequences:

pub const Event = union(enum) {
    key: Key,
    mouse: MouseEvent,
    resize: struct { cols: u32, rows: u32 },
    focus_in: void,
    focus_out: void,
    paste: []const u8,
};

pub const MouseEvent = struct {
    button: MouseButton,
    action: MouseAction,  // press, release, drag
    col: u32,
    row: u32,
};

pub fn parse(bytes: []const u8) !?Event { ... }

Tests (20+):

Phase 5 Acceptance

$ zig build test
All 160 tests passed.

Phase 6: Input Escape Sequence Parser

Goal: Parse escape sequences from child process output and update the grid. This is the heart of terminal emulation.

input.zig (~1,500 lines)

Replaces input.c (~3,600 lines of C).

Tagged union state machine:

const Parser = struct {
    state: State = .ground,
    
    const State = union(enum) {
        ground: void,
        esc: struct { intermediate: u8 = 0 },
        csi: struct {
            params: std.ArrayList(u8),
            intermediate: u8 = 0,
            final: u8 = 0,
        },
        osc: struct {
            cmd: u8 = 0,
            data: std.ArrayList(u8),
        },
        dcs: struct { ... },
        sos_pm_apc: void,
    };
    
    pub fn feed(self: *Parser, bytes: []const u8) !void { ... }
};

What’s dropped from C input.c:

Tests (80+):

Phase 6 Acceptance

$ zig build test
All 240 tests passed.

Phase 7: Format + Status

Goal: Template expansion and status bar rendering.

format.zig (~500 lines)

Replaces format.c, format-draw.c (~7,500 lines of C).

pub fn expand(template: []const u8, ctx: *Context, allocator: Allocator) ![]const u8 {
    // Support tmux-compatible #{} syntax
    // #{session_name}, #{window_index}, #{pane_title}, etc.
    // #{?condition,true,false} ternary
}

Comptime parsing of format strings — validate at compile time where possible.

Tests (20+):

status.zig (~300 lines)

Replaces status.c (~1,800 lines of C).

pub const StatusBar = struct {
    left: []const u8,
    centre: []const u8,
    right: []const u8,
    bg: Colour,
    fg: Colour,
};

Tests (10+): rendering with sample configs.

Phase 7 Acceptance

$ zig build test
All 270 tests passed.

Phase 8: Mode + Key Bindings

Goal: Copy mode, tree mode, and key binding dispatch.

mode_copy.zig (~1,000 lines)

Replaces window-copy.c (~6,000 lines of C).

Copy mode with vim and emacs keybindings:

Tests (30+):

key_binding.zig (~300 lines)

Replaces key-bindings.c (~500 lines of C).

Comptime-generated default key tables.

Phase 8 Acceptance

$ zig build test
All 300 tests passed.

Phase 9: Client-Server IPC

Goal: Multi-process architecture with socket communication.

proc.zig (~400 lines)

Replaces proc.c (~700 lines of C).

pub const Message = packed struct {
    magic: u32 = 0x5A4D5558,  // "SZN"
    length: u32,
    type: MessageType,
    data: [4096]u8,
};

pub const MessageType = enum(u32) {
    identify,
    command,
    command_result,
    notify,
    // ...
};

server.zig (~1,000 lines)

Replaces server.c, server-fn.c, server-client.c (~4,000 lines of C).

client.zig (~500 lines)

Replaces client.c (~1,500 lines of C).

Tests (15+):

Phase 9 Acceptance

$ zig build test
All 330 tests passed.

Phase 10: Commands

Goal: Command implementations with comptime dispatch.

File layout

src/
  cmd/
    new_session.zig
    split_window.zig
    kill_pane.zig
    ...
  command.zig   — comptime dispatch table

MVP commands (25 total)

Session:      new-session, kill-session, attach-session, detach-client,
              switch-client, rename-session
Window:       new-window, kill-window, rename-window, move-window,
              select-window, swap-window, rotate-window
Pane:         split-window, kill-pane, select-pane, resize-pane,
              swap-pane, join-pane, break-pane
Input:        send-keys, capture-pane, paste-buffer
Config:       bind-key, unbind-key, set-option, show-options, source-file
Navigation:   copy-mode, find-window
Misc:         show-messages, list-keys, list-commands

Tests (50+):

Phase 10 Acceptance

$ zig build test
All 450 tests passed.

Phase 11: Full Integration

Goal: End-to-end tests against a real pseudo-terminal.

test "full session lifecycle" {
    const szn = try sznProcess.start(test_allocator, .{});
    defer szn.kill();

    _ = try szn.sendCommand("new-session -d -s test");
    _ = try szn.sendCommand("split-window -h");
    _ = try szn.sendCommand("select-pane -t 1");
    
    const output = try szn.sendCommand("list-panes -a -F '#{pane_id}'");
    try testing.expectEqualStrings("%0\n%1\n", output);
}

Phase 11 Acceptance

$ zig build test
All 490 tests passed.

Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│                      main.zig                           │
│   parse args → fork → server or client                  │
└───────────────────────┬─────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│                   proc.zig (process)                     │
│              event loop (epoll/kqueue)                   │
└──┬────────┬──────────┬──────────┬──────────┬───────────┘
   │        │          │          │          │
   ▼        ▼          ▼          ▼          ▼
┌──────┐ ┌──────┐ ┌────────┐ ┌────────┐ ┌────────┐
│server│ │client│ │input.zig│ │tty.zig │ │grid.zig│
│ .zig │ │ .zig │ │escape  │ │output  │ │screen  │
│sess'n│ │conn  │ │parser  │ │+ term  │ │buffer  │
│ mgmt │ │ to   │ │for     │ │I/O     │ │+scroll │
│      │ │server│ │child   │ │        │ │back    │
└──────┘ └──────┘ └────────┘ └────────┘ └────────┘
                              │
                              ▼
                         ┌────────┐
                         │format  │
                         │ .zig   │
                         │strings │
                         └────────┘

Reference Implementation Strategy

The tmux/ directory tracks the upstream C source. Use it as follows:

Never copy C patterns. When looking at tmux C code:

  1. Understand what the code does (not how)
  2. Design a Zig-native equivalent
  3. Test against the same input/output as tmux

Key Architectural Decisions

No imsg

Simple packet protocol over Unix sockets:

const Packet = packed struct {
    magic: u32 = 0x5A4D5558,  // "SZN"
    length: u32,
    type: MessageType,
    data: [4096]u8,
};

Arena allocators

Single poll loop

Use std.os.poll or epoll/kqueue wrapper. No libevent dependency.

Comptime key bindings

Default key bindings generated and validated at compile time.

How to Contribute

  1. Read the tmux C source for the subsystem you want to port
  2. Understand the behaviour (test with tmux -L test ...)
  3. Design the Zig interface
  4. Write the Zig implementation + tests
  5. Run zig build test — all tests must pass
  6. Open a PR

See AGENTS.md for coding conventions.