flmux
A terminal multiplexer / window manager built in Flutter, hosting the
Ghostty VT engine (libghostty-vt via the flterm widget). Splittable,
resizable, focus-tracked panes — each a live terminal — with a control plane
so agents can spawn, drive, observe, and label panes programmatically.
Runs on macOS desktop (FFI, real local shells) and web/WASM
(libghostty-vt compiled to WebAssembly, rendered in the browser).
flmux — pronounced "flummox" (Flutter + mux) — is the control-plane CLI.
Prior art: flmux unabashedly steals its control-plane model from
cmux — the pane tree, stable surface ids, and the JSON-RPC-over-Unix-
socket verbs are cmux's ideas. flmux is the Flutter/Ghostty reimagining, with
a workspace UI, live pane status, full-duplex notifications, and a Monty
orchestration layer on top.
Quick start
flutter run -d macos # desktop: real shells via PTY (flutter_pty)
flutter build web --release # web: libghostty-vt as WASM
python3 -m http.server 8080 --directory build/web
Keyboard (desktop): ⌘D split right, ⌘⇧D split down, ⌘W close. On web
those collide with the browser — use the toolbar buttons.
The control plane
flmux speaks JSON-RPC 2.0, one object per line, over a Unix socket
(FLMUX_SOCKET_PATH, default /tmp/flmux.sock). Two interchangeable clients:
flmux — compiled Dart binary (bin/flmux.dart).scripts/flmux.sh — dependency-free POSIX sh + python3, same interface,
no Dart needed.
flmux tree # pane tree: surface ids, focus, titles
flmux status # table: activity / command / cpu / last
flmux new-split direction=row # split → returns the new surface_id
flmux send surface_id=2 'text=ls -la\r' # type a command into pane 2 (\r submits)
flmux read-screen surface_id=2 # read pane 2's rendered screen
flmux focus surface_id=1
Verbs
| Verb | Params | Result |
|---|
api | — | machine-readable schema of all verbs + notifications |
tree | — | nested pane tree (ids, focus, title, label, status, activity, command, cpu, memory_mb, last_activity) |
status | — | flat list, one row per pane (for flmux status's table) |
new-split | [direction=row|column] [surface_id=N] [kind=shell|monty] | {surface_id} of the new pane |
send | surface_id=N text=STR | type STR into the pane (see escapes) |
read-screen | [surface_id=N] | {text} — the rendered screen as plain text |
focus | surface_id=N | make that pane active |
set-status | [surface_id] [status] [progress] [label] | set a pane's cooperative agent status (badge/progress/label) |
set-title | [surface_id] title=STR | sticky display label (empty clears → auto title) |
maximize | [surface_id] | surface a pane |
close | [surface_id] | kill + remove a pane (e.g. an exited one) |
play | file=PATH [surface_id] | play an image/GIF as cell-art (needs chafa) |
subscribe / unsubscribe | — | opt in/out of push notifications (see below) |
text= escapes & submitting
\n \r \t, \e (ESC, for CSI like arrow keys), \xHH (raw byte; \x03=Ctrl-C,
\x15=Ctrl-U). To submit (press Enter), end with \r — that's what the
Return key sends. A shell accepts \n too, but a TUI (e.g. pi) treats \n
as a literal newline in its editor and only submits on \r.
Full-duplex notifications
The socket is persistent. A client that sends subscribe then also receives
server-initiated notifications (no id) on the same connection:
{"method":"state","params":{"tree":{…}}} — on split / close / focus / maximize.{"method":"event","params":{"type":"status","surface_id":N,…}} — on a status change.
This is how an agent reacts to the UI (and to its sibling agents) live.
Workspace, status & labels
The default view is a master–detail workspace: a left rail listing every
pane, and a detail area you can split (right/down) to watch several at once.
