Panels

A panel is a terminal that sirioctl starts and owns, in the worktree you name with --worktree or in the selected one. It never appears in the window: you write to it, read it and close it through sirioctl alone. To split a terminal you can see, use sirioctl pane split.

panel create and panel split print the new panel’s id, such as pane-81234-1. Keep it.

WORKER=$(sirioctl panel create --cmd 'codex')
PEER=$(sirioctl panel split right --from "$WORKER" --cmd 'pi')

--cmd runs through your shell, and the panel’s process exits when the command does. The panel keeps its output and exit code for read, state and wait until you close it. Without --cmd, a panel holds an interactive shell. panel split --from takes only an id that panel create or panel split printed, and starts the new panel in the same directory. In a pane of the window, $SIRIO_PANE_ID names that pane, so --from answers it with unknown pane.

Drive it

sirioctl panel write --id "$WORKER" --input 'Implement the parser change' --enter
sirioctl panel key   --id "$WORKER" --key enter
sirioctl panel read  --id "$WORKER" | base64 -d
sirioctl panel state --id "$WORKER"
sirioctl panel list
sirioctl panel close --id "$WORKER"

write, key, read, scrollback, state, wait, focus and close take the panel’s id as --id or right after the verb, and split takes it as --from.

• write sends the text of --input, and --enter adds a carriage return after it.
• key sends the one key that --key names: enter (or return), tab, escape, backspace, delete, up, down, left or right.
• read returns the newest 256 KiB the panel has printed, in base64. Decode it before you treat it as text. scrollback --max-bytes 4096 prints the newest 4096 bytes in base64, then a tab and how many bytes it returned. Keep only the first field before you decode it.
• state prints the working directory, the exit status (running, success or code:N), the exit code once there is one, and how many bytes of output the panel holds. On macOS and Linux, a command that a signal kills reports 128 plus the signal’s number, as a shell does. A pane of the window can also report signal:N or unknown.
• list shows the panels of the selected worktree, or of --worktree, beside the panes of its tabs in the window, with each one’s id, tab, title, agent and whether it is the active one. focus makes a panel the active one in that list.

Wait for the result

panel wait blocks until the panel’s command exits, for up to an hour, and prints its exit code. It then exits 0 itself, whatever the code, so read the code from its output. It fails only when it cannot wait: an unknown or closed id, a socket it cannot reach, a --timeout-ms that runs out, or an hour of waiting, after which sirioctl stops listening on the socket whatever --timeout-ms says.

status=$(sirioctl panel wait --id "$WORKER") || status=1
sirioctl panel read --id "$WORKER" | base64 -d
sirioctl panel close --id "$WORKER"
exit "$status"

Always clean up

A shell trap closes the worker on success, failure and interruption alike:

WORKER=$(sirioctl panel create --cmd 'codex')
trap 'sirioctl panel close --id "$WORKER"' EXIT

panel close stops the panel’s process, and close-workspace stops every panel of that worktree. A panel is a terminal like any other, so it runs in the host and quitting Sirio leaves it running; see Terminals that outlive the app.