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

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.

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).

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

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: jq -r '.sessions[].id'.
  • pane list --format json and window list --format json return a bare JSON array: jq -r '.[].id'.

  Reaching for .result.pane_id or .session_id on session create yields null, not an error, so the mistake surfaces later as an empty variable rather than a failed command.

• session kill and the -s/--session flag on every pane/window subcommand (incl. snapshots) accept a session NAME or a UUID — including the session_id a lens run response hands you for its scratch session. UUID-shaped input (hyphenated or 32-hex) resolves as an ID first, falling back to a session NAMED that string; the ID wins when both match (warning printed). Exceptions: session rename, session save, and session attach are NAME-only.

• lens run --wait on a signal-killed child (e.g. reaped by --max-runtime) reports RPC exit_code: -1, which the shell sees as $? == 255 (Unix truncates negative process exits to 8 bits) — 255 there means "never exited on its own", not a literal child exit code.

• lens run, pane glance, and pane diff --heat output can contain whatever the pane displays, including secrets. No automated redaction — don't glance/diff a pane you didn't spawn yourself unless asked to.

• shux state apply foo.toml atomically commits the graph but PTY spawn outcomes are reported per-pane in spawn_results. A spawn failure does not roll back the graph.

• The first pane of the first template window is folded into the session's auto-created initial window — there is no phantom default-shell pane.

• PNG snapshots use a bundled font chain by default: JetBrains Mono Nerd Font for primary monospace metrics and Nerd Font icons, Noto Sans Math for arrows such as ↻, Noto Sans Symbols 2 for braille spinners/status glyphs such as ⠹, Noto Sans Symbols for older technical symbols such as ⎇, and monochrome Noto Emoji for standalone emoji. You normally do not need local font config for common TUI glyphs.

• appearance.font is the only config knob that changes PNG snapshot cell metrics. appearance.font_fallbacks is snapshot-only fallback coverage; omit it for the default chain. If set, it must be a non-empty ordered list of builtin tokens (builtin:nerd-font, builtin:math, builtin:symbols, builtin:symbols-legacy, builtin:emoji) or font paths. If font is unset, bundled JetBrains Mono still anchors metrics.

• Still not full terminal font parity: color emoji, composed emoji/ZWJ sequences, ligatures, RTL shaping, CJK/system-font discovery, and platform font fallback are renderer-v2 work. For those, trust live attach or keep visual tests scoped to currently supported scalar glyphs.