libghostty-vt is the terminal engine inside phux: the server owns one terminal per pane, and a rendering client runs its own. The phux README is the product overview. The engine's place on the wire is the phux-protocol README. The browser client, which isn't shipped yet, is described in the phux-vt-web README and the phux-web README.
What it does
The pane actor
owns a libghostty_vt::Terminal, the pane’s pseudo-terminal, and the
input encoders. Building the actor
creates that terminal at the pane’s size. Terminal is !Send, so the
actor runs on the server’s current-thread LocalSet.
That terminal is the canonical screen. It parses the PTY byte stream.
OSC 7501 arrives through libghostty’s on_program_status callback, and
phux stores the records
(program protocol,
effects).
A rendering client feeds those VT bytes to its own libghostty terminal. The phux-protocol README says a libghostty terminal on the client reproduces the server’s screen exactly, and that client-to-server input is key, mouse, focus, and paste events built from libghostty’s vocabulary. The server encodes those events for the PTY. Selection and text extraction belong to libghostty (decisions).
The browser client, which isn’t shipped yet, draws with libghostty-vt compiled to WebAssembly.
phux-vt-web loads ghostty-vt.wasm,
writes VT bytes, and reads the styled grid.
phux-web paints that grid on a canvas.
Embedding runs this replica in the app’s process
(embed phux).
Builds download a prebuilt libghostty-vt.a for a pinned Ghostty
commit, or compile it from source with Zig
(development).
What it does not do
libghostty is not the multiplexer. Sessions, tabs, and the process in the pane belong to the server. The library holds one pane’s terminal.
It does not speak the server protocol. The default phux-protocol
build is pure Rust, with no libghostty, and compiles to wasm. The
server feature adds libghostty conversions; decoding wire messages
does not need them
(phux-protocol README).
The WebAssembly driver does no networking, does not speak the phux protocol, and does not touch the DOM (phux-vt-web README).
A client replica does not answer terminal queries. The server’s canonical terminal is the only query answerer, and the replica drops the replies it would generate (engine adapter, terminal queries).
It does not paint chrome. Pane interiors are libghostty’s; the client’s chrome is separate (decisions).
A client that only wants text does not run a replica. It asks the
server for GET_SCREEN and gets the server’s view, which is what
phux snapshot does
(architecture). An attach can
instead use synthesized VT, which works with any emulator
(attach and output).
libghostty does not decide which coding agent occupies a pane. phux keeps that record itself (agent record).