Architecture
ztmux-core implements the client side of tmux's client/server protocol directly: it frames OpenBSD imsg messages (protocol version 8) over the tmux server's Unix socket, the same protocol the tmux binary speaks. There is no tmux subprocess and no control-mode (-CC) text parsing. Pane process inspection reads the running command line via libproc / /proc rather than spawning anything. Every high-level operation returns a serde_json::Value, so a GUI host (zterminal, and other apps) renders the session tree in its own frontend.
Module map
The engine's source modules (src/*.rs). All are real, implemented modules.
| module | responsibility | status |
|---|---|---|
| transport | the wire client — command(socket, argv) -> TmuxOutput, socket_path() (connect-validated) | implemented |
| proc | the full command line running in a pane, via libproc / /proc — no subprocess | implemented |
| ops | session tree (with pane previews), capture, search corpus, broadcast list + send_keys, synchronize-panes, focus, dashboard summary — all returning serde_json::Value | implemented |
| snapshot | native session save / restore (a tmux-resurrect replacement): layout, cwd, full command line, active state, pane contents, process whitelist; parameterized by storage dir | implemented |
| lib | crate root tying the layers together for host consumption | implemented |
Design notes
- Why the wire protocol — talking imsg directly to the server is faster and more robust than spawning
tmuxper query and scraping its output, and it avoids control-mode's text-stream parsing. - JSON boundary — ops return
serde_json::Valueso the engine stays UI-agnostic; each host renders the tree, previews, and dashboards itself. - No subprocess anywhere — both the protocol client (
transport) and pane process inspection (proc) avoid spawning children. - Snapshot — save/restore is native rather than a shell plugin, capturing layout, cwd, command lines, and pane contents under a configurable storage directory.
Verification policy
The crate ships 16 #[test] functions covering the transport framing, ops JSON shapes, and snapshot round-trips. Builds and tests run on headless Linux CI; behavior degrades gracefully (typed empty/false results) when no tmux server is reachable rather than panicking.