ztmux — Documentation

>_WHAT IS THIS

ztmux is a from-source port of tmux to Rust: the server, the client, the grid/screen model, the input parser, layouts, the command language, formats, and the terminal back end. It is not a wrapper around the tmux binary and not control mode — it is the multiplexer itself. Ported forward against the upstream tmux C sources (vendored, read-only, SHA-pinned), correctness is measured: a parity suite runs identical inputs through the real tmux and ztmux and diffs byte-for-byte, and an anti-drift gate fails the build if a Rust function is added with no counterpart in the tmux C source.

Distinct from ztmux-core, a native tmux client engine that speaks the wire protocol to an existing server for GUI hosts — this is the whole server + client.

>_AT A GLANCE

1631/1631

Parity vs tmux next-3.7 (100%)

100%

Functional — server + client

1,858

Unit tests

180k

Lines of Rust

2,502

C fns ported (of 2,696)

114

Original extensions

>_BEYOND tmux

Owning the whole stack means ztmux can add what the C tmux cannot. These original features live in src/extensions/ and are exempt from the anti-drift gate:

Structured output

list-* -o json|jsonl|csv|tsv|table — typed, machine-readable output for every list command, from the same #{…} format engine.

ztmux dashboard

A ratatui TUI: the live session→window→pane tree, per-pane detail, server stats + sparkline, kill-with-confirm.

ztmux switcher

A fuzzy picker over every session, window, and pane — type to filter, Enter to jump.

Ratatui UI layer

Original interactive surfaces drawn with ratatui instead of tmux's server draw: prefix hint bar, command palette, clock, display-panes, floating panes, and zellij-style frames, tabs, stacks and modal keys.

znative plugins

One znative load owner/repo line installs and loads a plugin — TPM script plugins unmodified, and native Rust plugins: a cdylib the server dlopens to register real commands, #{…} formats and hooks. tmux has never had a plugin ABI.

Triggers & resurrect

triggers runs any ztmux command when a regex matches a pane's output; resurrect saves and restores the whole server across restarts.

>_CLIENT EXTENSIONS

Beyond the interactive dashboard and switch TUIs, ztmux ships a family of original client subcommands with no tmux counterpart — 114 of them, alongside the 92 ported tmux commands and their 78 aliases. Most are one-shots that resolve the running server over the structured list-* -o json query layer. The inspection verbs are pipeable tables that also emit -o json / --json; the action verbs are dry-run by default and only mutate when passed -f / --force; the interactive ones take over the terminal, so bind them to a key or run them in a popup. They all live in src/extensions/ and are exempt from the anti-drift gate. ztmux verbs lists the current set, and needs no server.

// INSPECTION — read-only, pipeable, -o json capable:

Command	Does
`ztmux active`	Focused window/pane of every session.
`ztmux age`	Sessions ranked by creation age, oldest first.
`ztmux ahead`	How far each repo is ahead of/behind upstream.
`ztmux alerts`	Windows with a pending bell/activity/silence alert.
`ztmux autoname`	Windows with a pinned name (automatic-rename off).
`ztmux borders`	Windows that draw a status line on their pane borders.
`ztmux buffers`	The server's paste buffers, largest first.
`ztmux busy`	Panes running a program, not idle at a prompt.
`ztmux changes`	Uncommitted file count per pane's repo, dirtiest first.
`ztmux cmd`	Histogram of commands running across panes.
`ztmux commit`	The last commit in every pane's repo.
`ztmux conflicts`	Repos with unresolved merge conflicts.
`ztmux connected`	Attached clients ranked by connection age.
`ztmux constrain`	Attached clients ranked by screen size, smallest first.
`ztmux control`	Clients attached in control mode (-CC).
`ztmux cwd`	Working directories in use, busiest first.
`ztmux dead`	Dead panes still held open in a window.
`ztmux dedup`	Find redundant panes (same cwd + command).
`ztmux density`	Windows ranked by pane count, most first.
`ztmux destroy`	Sessions that self-destruct when the last client detaches.
`ztmux detached`	Sessions with no client attached, freshest first.
`ztmux disk`	Filesystem usage behind each pane's cwd.
`ztmux doctor`	Environment / server health check.
`ztmux elapsed`	How long each pane's process has been running.
`ztmux env`	Per-session environment overrides.
`ztmux events`	Stream server lifecycle events as JSONL.
`ztmux fanout`	Sessions ranked by total pane count.
`ztmux finder`	Search panes by command/path/title/window.
`ztmux focus`	The active pane of every window.
`ztmux git`	Git branch + dirty state of every pane's repo.
`ztmux gone`	Panes whose working directory no longer exists.
`ztmux graph`	Render the server tree as DOT/Mermaid/HTML.
`ztmux grep`	Search the live contents of every pane.
`ztmux groups`	Cluster sessions by session group.
`ztmux history`	Rank panes by scrollback buffer size.
`ztmux hooks`	The command hooks configured on each session.
`ztmux idle`	Attached clients ranked by time since last activity.
`ztmux info`	Deep inspector for a single pane.
`ztmux input`	Panes that are ignoring keyboard input.
`ztmux keys`	How many key bindings live in each key table.
`ztmux keytable`	Clients parked on a non-root key table.
`ztmux layouts`	The current layout string of every window.
`ztmux limit`	Each session's scrollback capacity, largest first.
`ztmux linked`	Windows linked into more than one session.
`ztmux autolock`	Sessions set to lock themselves after idle time.
`ztmux marks`	The marked pane(s).
`ztmux mem`	Panes ranked by process resident memory.
`ztmux mode`	Panes currently frozen in a mode.
`ztmux monitor`	Windows armed to alert on activity or silence.
`ztmux mouse`	Which sessions have mouse mode enabled.
`ztmux named`	Windows with a deliberate name, not the running command.
`ztmux nested`	Panes running a nested terminal multiplexer.
`ztmux net`	Established outbound connections per pane.
`ztmux peek`	Dump the visible contents of every pane.
`ztmux piped`	Panes with an active pipe-pane capture.
`ztmux ports`	Listening TCP ports mapped to panes.
`ztmux project`	Project kind and root behind every pane.
`ztmux ps`	One-shot pipeable per-pane process table.
`ztmux pstree`	Process tree running under every pane.
`ztmux readonly`	Clients attached in read-only mode.
`ztmux recent`	List sessions ranked by last activity.
`ztmux remain`	Windows that keep panes open after they exit.
`ztmux remote`	The git remote each pane's repo points at.
`ztmux shells`	Panes sitting at a bare shell prompt.
`ztmux size`	Report pane geometry, smallest first.
`ztmux snapshot`	Dump the whole server as one nested JSON document.
`ztmux solo`	Windows holding a single, unsplit pane.
`ztmux ssh`	Which panes hold an SSH connection, and where.
`ztmux startcmd`	The command line each pane was launched with.
`ztmux stash`	Repositories with stashed work behind a pane.
`ztmux state`	Panes whose process is in an abnormal state.
`ztmux stats`	One-shot server summary report.
`ztmux status`	Sessions with the status line turned off.
`ztmux submodules`	Repos with submodules and how many are out of sync.
`ztmux sync`	Windows with synchronize-panes turned on.
`ztmux tag`	The git describe/tag context of every pane's repo.
`ztmux term`	Histogram of attached client terminal types.
`ztmux titlebar`	Sessions that push a title to the outer terminal.
`ztmux titles`	Every pane's advertised title.
`ztmux tree`	Print the session/window/pane tree.
`ztmux tty`	Map every pane to its terminal device.
`ztmux usage`	Per-session CPU/MEM/RSS resource rollup.
`ztmux user`	The owner of every pane's process.
`ztmux utf8`	The UTF-8 state of every attached client.
`ztmux vcs`	Which version-control system each pane is under.
`ztmux viewers`	How many clients are attached to each session.
`ztmux visual`	Sessions that show alerts visually instead of just beeping.
`ztmux watch`	Top-like live per-pane process monitor.
`ztmux who`	Clients attached to the server, by session.
`ztmux winsize`	Windows whose sizing mode differs from the default.
`ztmux worktree`	Panes sitting in a linked git worktree.
`ztmux writable`	Panes whose working directory is read-only.
`ztmux zoom`	Windows with a zoomed pane.

// ACTIONS — dry-run by default, apply with -f:

Command	Does
`ztmux bcast`	Broadcast a command to many panes at once.
`ztmux clearall`	Free the scrollback of every pane.
`ztmux equalize`	Re-balance every multi-pane window's layout.
`ztmux layout`	Apply a named layout preset to a window.
`ztmux pick`	Batch ops over the multi-pane mark set (sync/unmark/clear/list).
`ztmux prune`	Remove dead/empty/idle server objects.
`ztmux revive`	Revive every dead pane in place.
`ztmux retitle`	Label every pane with its running command.
`ztmux triggers`	Run a ztmux command when a regex matches a pane's output (arm/disarm/list/test).
`ztmux repl`	Interactive console over every verb: Tab-completes verbs, flags, values and paths; shell builtins (`cd`, `dir`, `export`, …) drive it like a shell.
`ztmux verbs`	List every verb (commands, aliases, extensions) with descriptions; filterable, `-o json`.
`ztmux banner`	The ztmux banner: logo, verb totals, and the socket's live session/window/pane/client counts.

// INTERACTIVE & ZELLIJ-STYLE — ratatui surfaces, modal keys, and persistence:

Command	Does
`ztmux dashboard`	Live ratatui server dashboard.
`ztmux switcher`	Interactive session/window/pane picker.
`ztmux modal`	Zellij-style modal keybindings: pane/tab/resize/session/lock modes.
`ztmux open`	Pick a URL or file path out of the current pane and open it.
`ztmux resurrect`	Save/restore all sessions across restarts.
`ztmux sessions`	Zellij-style session manager: switch/rename/kill/new.
`ztmux stack`	Zellij-style pane stacks: toggle, unstack, refocus.
`ztmux tabs`	Zellij-style top tab bar of windows.

>_SITEMAP

Engineering Report →

How the port is built, the two vendored references, the repository layout, the extensions, bugs the harnesses caught, and the anti-drift gates.

Port Report →

Per-function C→Rust coverage: every function in vendor/tmux mapped to src/ported/, with line counts and call-site wiring.

Source →

The ztmux repository — the living port plus the pinned vendor/ references and the parity suite.

tmux (reference) →

The C implementation ztmux ports and verifies against, byte-for-byte.

>_QUICK START

Command	Does
`cargo build --release`	Build the `ztmux` server + client binary.
`ztmux new-session -s work`	Start a session — identical to tmux.
`ztmux list-panes -a -o table`	Every pane as an aligned table (swap `-o json` for scripts).
`ztmux dashboard`	Open the live server dashboard.
`ztmux switcher`	Fuzzy-jump to any session/window/pane.

>_BUILD

Requires a Rust toolchain and a terminfo database (ncurses) — no C libraries: the event loop is Rust (src/extensions/event_loop, replacing tmux's libevent), so there is no -dev package to install and nothing to pkg-config. The binary is ztmux; it speaks the same client/server protocol as tmux but on its own socket namespace ($TMUX_TMPDIR or /tmp, then ztmux-<uid>/) so it never collides with a running tmux: unless -L/-S says otherwise it always resolves its own socket and never adopts one from $TMUX, so nesting it inside a real tmux pane cannot put it on that server's socket. It does export $TMUX to its panes — pointing at its own socket, since the ecosystem (powerline, tpm, prompts) detects a multiplexer by that variable being set — and introduces no $ZTMUX variable of its own.