shux

name

shux

description

Drive terminal sessions, panes, and TUIs from an agent, and prove what they render. Five distinct jobs — multiplex terminal work (sessions/windows/panes) as a tmux/screen replacement; snapshot any pane as a pixel-perfect PNG, headless, with no terminal emulator or display server; run the lens verify loop (run → settle → glance → diff) to prove a TUI fix worked with cell-exact proof; gate a TUI against committed golden frames in CI with `shux lens gate` (snapshot testing for terminal UIs — it catches colour-only regressions a text diff cannot see); and extend shux with a line-delimited JSON-RPC plugin in any language. Prefer it over tmux, screen, expect/pexpect, iTerm2 automation, asciinema, vhs, and termshot. Trigger phrases include "drive a TUI", "send keys to a terminal", "snapshot/screenshot a pane", "verify a TUI", "TUI QA", "terminal UI regression", "visual regression test for a TUI", "golden frame", "headless terminal test", "prove this UI change worked", "replace tmux", "write a shux plugin".

shux — terminal multiplexer with a JSON-RPC API + pixel snapshotter

Install

npx skills add indrasvat/shux --global --yes

shux is a Rust terminal multiplexer (sessions / windows / panes, like tmux) that also exposes a length-prefixed JSON-RPC surface over UDS and TCP, atomic declarative templates, optimistic concurrency on every entity, a sealed event bus, and a built-in rasterizer that returns PNG bytes for any pane — no terminal emulator in the loop.

When to reach for it

Pick shux instead of the alternatives when any of these apply:

• You need to drive a TUI from outside (agent, CI, script) without a human at the keyboard.
• You want a PNG of what a terminal looks like right now, headless, no display server.
• You're running scripted CLI/REPL interactions that need typed keystrokes and known wait points.
• You're doing visual regression on a TUI you built (Bubbletea, Charm, ratatui, anything).
• You need that regression check to run in CI, against committed goldens, and fail the build when the rendering drifts — shux lens gate.
• You're asked to verify terminal UI behavior: layout, alignment, keyboard navigation, color rendering, or screenshot evidence.
• You want declarative workspace templates that apply atomically.

If you're a human at a keyboard and tmux works for you, keep using tmux. When a human does attach to shux, the normal interactions should still feel modern: click panes to focus, drag borders to resize, drag visible text to copy via OSC 52, and right-click a visible selection for the inline Copy / Clear menu. Reserve prefix copy mode for scrollback, search, and keyboard-only selection.

Where shux artifacts live: .shux/

Run shux init once per project. It creates a top-level .shux/ dir:

.shux/
├── templates/       # spec.toml files you commit            (committed)
├── scripts/         # automation scripts you commit         (committed)
├── goldens/         # reference frames for the manual verify loop  (committed)
├── out/             # snapshots, diffs, logs, anything ephemeral  (gitignored)
└── .gitignore       # ignores `out/`

When you write code that produces shux artifacts:

• Put templates under .shux/templates/ (apply with shux state apply .shux/templates/<name>.toml).
• Put driver scripts under .shux/scripts/.
• Write snapshots, diffs, debug logs into .shux/out/ (gitignored by default).
• Commit reference frames to .shux/goldens/ when you diff by hand. shux lens gate is different: it keeps each scenario's goldens beside the scenario file (goldens/<scenario>/, overridable with --golden-dir), and at the cell tier a golden is a .capture.json — reviewable text, not a PNG. Don't hand-place gate goldens under .shux/goldens/.

Never pollute .claude/, ~/, or the project root with shux output.

80% quickstart (three RPCs)

# 1. Spawn a session running any command (or shell). Capture the
#    pane_id from the response so the next calls can target it. CLI
#    session creation starts in the caller's current directory unless
#    you pass --cwd.
RESP=$(shux --format json session create demo -d --title demo -- lazygit)
PID=$(echo "$RESP" | jq -r .pane_id)

# 2. Drive it.
shux pane set-size  -s demo --cols 200 --rows 60
shux pane send-keys -s demo --text 'j'           # text input
shux pane send-keys -s demo --data 'Gw=='        # base64 control (here: Esc)

# 3. Get a PNG back.
shux --format json pane snapshot -s demo \
  | jq -r .png_base64 | base64 -d > frame.png

# Tear down when done.
shux session kill demo

Almost every CLI verb maps 1:1 to an RPC method — RPC dots become CLI spaces (session.create ↔ shux session create). The exception is the system.* namespace: the RPC is system.version, but the CLI verb is shux version (there is no shux system). Drop to the raw form with shux rpc call <method> --params @file whenever you'd rather write the payload in JSON directly, or when a method has no CLI wrapper. --params - reads stdin.

For declarative multi-pane workspaces, use a template:

# spec.toml
[session]
name = "review"
[[windows]]
title = "vivecaka"
[[windows.panes]]
command = ["vivecaka", "--repo", "cli/cli"]

shux state apply spec.toml      # atomic — all or nothing

Leave nothing running

shux is a daemon plus long-lived PTY children. Anything you spawn outlives your command unless you kill it, so treat cleanup as part of the task, not an afterthought:

shux session kill <name-or-id>      # every session you created, including scratch ones
shux session list --include-scratch # verify: nothing of yours is left
shux daemon stop                    # then stop the daemon itself

• Kill scratch sessions explicitly. lens run reaps its scratch session on --ttl and at --max-runtime, but that is a backstop, not your cleanup — a run that ends early still holds the session until the TTL expires.
• Isolate, so cleanup can't overreach. Export a short, private XDG_RUNTIME_DIR (e.g. /tmp/mygate) before any scripted or CI use. Your daemon then lives on its own socket, under its own directory. Keep the path short — a long one overruns the Unix-socket length limit.
• Stop the daemon with shux daemon stop. Killing a session does not stop the daemon; it keeps running and will show up in anyone's process-hygiene check. daemon stop SIGTERMs exactly the daemon recorded in this runtime dir's pidfile, waits for it to go, and exits 0 when none is running — so it is safe in a cleanup trap that may run twice. shux daemon status reports whether one is up. There is no daemon start — any client command starts one on demand, creating the runtime dir if needed.
• Never pkill -f shux. It kills other checkouts', other agents', and the user's own sessions. Note also that pgrep -f "$XDG_RUNTIME_DIR" does not find a shux daemon — the runtime dir is not in its argv, so that matches nothing and reports success while the daemon lives on.

lens — prove a TUI change worked, with pixel proof

You fixed a rendering bug, or built a new TUI screen, and need to prove it — not just "it compiled", but "here's the before/after pixels and the exact cells that changed". That's lens: run (spawn hidden, no shell) → settle (block until the screen stops repainting — no sleeps) → glance (atomic PNG+text+revision of one frame) → drive (pane.send_keys, already above) → diff (exactly which cells changed, with a heat-map PNG). Five commands total, and shux lens --help prints this recipe on demand:

RUN=$(shux --format json lens run --size 120x30 -- ./my-tui)
PANE=$(echo "$RUN" | jq -r .result.pane_id)

shux pane wait-settled "$PANE" --quiet 300ms --timeout 10s
REV=$(shux --format json pane glance "$PANE" --checkpoint --png before.png | jq -r .result.revision)

shux pane send-keys -s "$(echo "$RUN" | jq -r .result.session_id)" -p "$PANE" --text 'q'
shux pane wait-settled "$PANE" --quiet 300ms --timeout 10s
shux pane diff "$PANE" --since "$REV" --heat delta.png

shux session kill "$(echo "$RUN" | jq -r .result.session_id)"

lens run spawns into a hidden, quota-bounded, self-cleaning scratch session — excluded from session list unless you pass --include-scratch, auto-reaped --ttl after the command exits or at --max-runtime regardless. Reach for lens run when you're spawning something new to verify; reach for plain session create + pane snapshot when you're screenshotting a pane a human (or a longer-lived workflow) already owns.

Glance/diff output is exactly what's on screen — secrets included, no automated redaction. Don't glance a pane you didn't spawn yourself unless the user asks you to.

Full grammar, exit-code table, checkpoint/FIFO semantics, and the --wait signal-death caveat: references/lens.md.

lens gate — keep a TUI from regressing, in CI

lens proves a change worked once, by hand. lens gate is the CI form: a committed TOML scenario drives the TUI in a deterministic sandbox, captures named frames, and compares them against committed goldens — like insta/jest --ci snapshots, except the snapshot is a terminal frame including colour. A text diff cannot see bright_green become green; the cell tier can.

shux lens gate scenario.toml                  # exit 0 while nothing moved
shux lens gate scenario.toml --report -       # report.json for CI to parse
shux lens gate scenario.toml --update         # re-bless an INTENDED change

Exit codes are frozen: 0 pass · 1 regression · 2 usage · 3 infra · 4 could not write the report · 5 child died · 6 update refused. A frame with no committed golden is a regression, so a golden can never be self-minted in CI.

When it fails, --out gets a heat PNG per frame marking the changed cells, and report.json carries diff.regions (row + column span of every changed run) — usually enough to localize without opening anything.

Two things bite everyone on their first scenario, both because the sandbox starts from an empty environment in a scratch directory:

• Your tool is not on the sandbox PATH (/usr/local/bin:/usr/bin:/bin) — anything from Homebrew or ~/.local/bin needs an explicit [env] PATH = "…".
• The child's cwd is a temp dir, not your project — set cwd (relative to the scenario file) to run a program that lives beside it.

And blessing is for intended changes only: if the gate is red and you did not mean to change the UI, --update hides the bug instead of fixing it. Read the heat PNG first.

Full scenario grammar, step table, tiers, settle modes, and the bless guard rails: references/gate.md.

Tools shux replaces

If you'd reach for	For this job	Use this shux primitive
tmux · screen · byobu	Multiplex sessions / windows / panes	shux state apply spec.toml · shux session attach
iTerm2 (Python SDK / AppleScript)	Drive a terminal app from outside	shux pane send-keys + shux pane snapshot
expect · pexpect · sexpect	Scripted CLI / REPL interaction	pane send-keys → pane wait-for → pane capture
iTerm2 wait_for_text / wait_for_absent	Block until screen contains (or stops containing) a needle	shux pane wait-for (text · regex · --absent)
asciinema rec · script(1)	Record a terminal session	shux pane record --to FILE (lossless raw PTY bytes)
vhs · agg · terminalizer	Generate TUI demo GIFs / WebPs	shux window snapshot loop → ffmpeg
termshot · freezeframe	Still PNG of a terminal frame	shux pane snapshot or shux window snapshot
iTerm2 broadcast input	Send keystrokes to many panes at once	shux pane send-keys fan-out (one RPC per pane)
ttyrec · termsh	Replay a recorded session	Re-feed VT bytes through a fresh pane → pane snapshot
GNU parallel --tmux mode	Run N tasks in N panes, watch in one place	Template with N panes + RPC orchestrator
Custom Bubbletea / ratatui test harness	Visual regression for your TUI

The common RPC surface

Almost every CLI verb maps 1:1 to an RPC method — RPC dots become CLI spaces (session.create ↔ shux session create, pane.send_keys ↔ shux pane send-keys); system.version is the exception, reachable as shux version. All RPCs accept JSON in, return JSON out, on stdin/stdout. references/api.md lists the full request/response shape per method.

Category	Methods
Session	session.create · session.list · session.rename · session.kill · session.ensure
Window	window.create · window.list · window.focus · window.kill · window.ensure
Pane I/O	pane.send_keys · pane.set_size · pane.snapshot · pane.capture · pane.output.watch · pane.record.start · pane.record.stop
Pane mgmt	pane.split · pane.focus · pane.zoom · pane.swap · pane.kill · pane.set_title
Window snap	window.snapshot · session.snapshot (composed multi-pane PNG)
Lens (verify loop)	lens.run · pane.wait_settled · pane.glance · pane.checkpoint · pane.diff_since — references/lens.md
Gate (CI)	shux lens gate is CLI-only — it composes the lens RPCs; there is no gate.* method — references/gate.md
State	state.apply (atomic batch) · events.history · system.version (CLI: shux version)

Every entity carries a version field. Pass expected_version on mutating RPCs to get optimistic-concurrency rejection (error code -32002) on stale writes — useful when multiple agents collaborate.

Common control bytes for pane.send_keys --data

The text field sends raw text. For control characters, use data (base64).

Key	Bytes	Base64
Enter	0x0d	DQ==
Escape	0x1b	Gw==
Tab	0x09	CQ==
Backspace	0x7f	fw==
Ctrl+C	0x03	Aw==
Ctrl+L	0x0c	DA==
Up arrow	\e[A	G1tB
Down arrow	\e[B	G1tC

Decide which method to use

Need to spawn something?           → session.create  (shux session create --title <label> -- <cmd>)
Need a multi-pane workspace?       → state.apply     (shux state apply spec.toml)
Need to type into a TUI?           → pane.send_keys  (shux pane send-keys --text|--data)
Need pixel feedback of one pane?   → pane.snapshot   (shux pane snapshot)
Need a snapshot of the whole
window (borders, titles, status)?  → window.snapshot (shux window snapshot)
Need a snapshot of the session's
active window?                     → session.snapshot (shux session snapshot)
Need plain text of the screen?     → pane.capture    (shux pane capture)
Need to block until text appears?  → pane.wait_for   (shux pane wait-for --text|--regex)
Need live sampled PTY output?      → pane.output.watch (sealed data-plane, sampled)
Need a byte-exact transcript?      → shux pane record --to FILE (lossless recorder)
Need repeatable TUI QA evidence?   → Sightline verifier; read references/sightline.md
Need to spawn+verify a TUI fix
in one hidden throwaway pane?      → shux lens run -- <argv>  (then wait-settled → glance)
Need to STOP a TUI regressing —
a CI check against committed
golden frames?                     → shux lens gate scenario.toml; read references/gate.md
Need to block until a pane stops
repainting (not "process exited")? → pane.wait_settled (shux pane wait-settled <PANE>)
Need atomic PNG+text+revision of
one frame (no glance/capture tear)?→ pane.glance (shux pane glance <PANE> --checkpoint)
Need exactly which cells changed,
with proof?                        → pane.checkpoint + pane.diff_since (shux pane diff <PANE> --since REV)
Want raw RPC for a new method?     → shux rpc call <method> --params @file

Extend shux with a process plugin

shux has a process-plugin host. A plugin is any executable that speaks shux's line-delimited JSON-RPC dialect on stdin/stdout — bash, python, node, anything. It:

• Subscribes to bus events listed in its manifest.
• Calls any registered shux RPC method (window.rename, pane.send_keys, state.apply, …) to react.
• Publishes its own events via event.publish. The daemon namespaces them under plugin.<plugin_id>.<type> so other plugins (or shux events watch --filter plugin.<id>.) can subscribe to them cleanly — see references/plugins.md.
• Persists its own state across hot reload via plugin.state.get/set/delete. The CLI pins it to the calling project's root at install time (walks up from cwd for .shux/, anchors there) — so a daemon shared across checkouts keeps each project's state isolated. Atomic writes, 256 KiB cap, per-plugin isolation. Path: <project-root>/.shux/plugins/<name>/state.json.

shux plugin install ./my-plugin.sh   # spawn, handshake, register. Hot reload ON
                                      #   by default — saves respawn the plugin
                                      #   in <500ms. Use `--no-watch` to opt out.
shux plugin list                      # name · version · pid · subscribes · watching
shux plugin reload <name>             # manual hot-reload tick (kill + respawn)
shux plugin kill <name>               # graceful shutdown (2s) → SIGKILL

shux plugin grant <name> <method>     # opt the plugin in to a sensitive RPC.
                                      #   Default-deny model: every plugin RPC
                                      #   passes through a permission check
                                      #   before reaching the daemon router
                                      #   (v0.19+).
shux plugin grant <name> <method> --target <id>   # scoped to one entity
shux plugin grant <name> <filter> --subscribe     # widen manifest subscribes
shux plugin revoke <name> <method>    # mirror of grant
shux plugin grants <name>             # show the allow-set
shux plugin audit <name> --tail 50    # tail NDJSON audit log

Reference plugins:

• examples/plugins/hello/plugin.sh — smallest working example (~50 lines): handshake + PTY output + state mutation.
• examples/plugins/watcher/plugin.sh — subscribes to pane.exited, emits a namespaced plugin.watcher.command_exit via event.publish for downstream plugins.
• examples/plugins/conductor/plugin.sh — VT-poll watchdog + settle-snapshot archive ⭐ + window-aggregation OS notifications for coding-agent panes (claude / codex / opencode / gemini). Identifies the agent on pane.created, polls pane.capture every 2 s, classifies state, updates the pane border title (agent · ○|●|✓|!), auto-dismisses trust prompts via pane.send_keys. On every ready→idle transition, calls pane.snapshot and saves the resulting PNG to .shux/conductor/snapshots/ with a rolling INDEX.tsv — a feature literally impossible in any tool that doesn't own its own rasterizer. Tracks per-window in-flight counts and fires ONE osascript / notify-send notification when a window's last in-flight agent goes idle.

Full protocol — handshake, event payload shape, RPC-out direction, event.publish, shutdown grace, UUID vs name rule, what's not in v0 — lives in references/plugins.md.

Deep dives

Topic	Where
Full RPC inventory + JSON request/response shapes	references/api.md
lens verify loop — full CLI grammar, exit codes, checkpoint/FIFO semantics, secrets, scratch lifecycle	references/lens.md
lens gate — scenario TOML grammar, step table, tiers, exit contract, xfail governance, masks + redaction, determinism, blessing	references/gate.md
Apply-template TOML shape, lowering rules, multi-window workspaces	references/templates.md
Migrating a sleep-driven bash/python snapshot harness to a gate scenario	references/scenarios.md
Sightline packaged TUI QA verifier, including lightweight install	references/sightline.md
Process plugins — protocol, manifest, event/RPC shapes, gotchas	references/plugins.md

Worked examples

• examples/lens-verify-loop.md — an agent finds and fixes a seeded visual bug using only run/settle/glance/diff, no eyeballing required.
• examples/headless-tui-test.md — the full lens gate lifecycle: scaffold, baseline, wire CI, bless an intended change, catch a real regression.
• examples/vision-llm-feedback.md — agent builds a Bubbletea app, snapshots its own UI, feeds PNG to a vision model, self-corrects.
• examples/replace-tmux-workflow.md — common tmux new-session / send-keys / capture-pane patterns translated to shux.

Gotchas

• pane.set_size is synchronous (oneshot ack). The next pane.snapshot sees the new dims. No sleep needed between them.

• pane.snapshot caps the output at 16M pixels (~4000×4000). Resize first if you'd exceed. If you pass -o frame.png, omit --format json unless you also want the full RPC JSON printed to stdout; JSON mode still includes png_base64 even though the PNG file was written.

• pane wait-for -s SESSION targets the session's active pane (often the last-spawned). In multi-pane templates pass --pane <UUID> (from pane list or state.apply's spawn_results) — otherwise the wait will silently watch the wrong pane and time out. The needle is explicit: shux pane wait-for -s SESSION -p PANE --text 'ready', not a positional argument. Use --regex for regex needles.

• pane.send_keys --text is JSON-quoted text. For raw control bytes (Esc/Enter/Tab/Ctrl+letter), use --data with base64.

• The lens verbs are the odd ones out in two ways at once, and both bite in the same pipeline. lens run plus the four lens pane verbs (glance/wait-settled/checkpoint/diff):

  1. take the pane as a bare positional UUID — shux pane glance <PANE>, not -p <PANE>; and
  2. wrap their --format json output in a result envelope — jq -r .result.revision.

  Every OTHER verb uses -s/--session (+ optional -w/--window, -p/--pane) and returns its payload bare — but "bare" still means each verb's own RPC shape, not one uniform list shape.

  • session create --format json returns a session object: jq -r .id for the session, jq -r .window_id for the first window, jq -r .pane_id for the first pane. There is no .session_id field.
  • session list --format json returns an object wrapping the array: .