Control Protocol

Verbs: Windows

Verbs: Windows: part of the Control Protocol of TUIOS.

This page is one part of docs/protocol.md of the tuios repository. The Control Protocol page lists every part.

list-windows

List the windows in a session.

Params: session (optional).

Request:

{"verb": "list-windows", "params": {"session": "work"}}

Response:

{"result": {
  "type": "window_list",
  "total": 2,
  "focused_index": 0,
  "focused_window_id": "7e02...",
  "current_workspace": 1,
  "workspace_windows": [2, 0, 0, 0, 0, 0, 0, 0, 0],
  "windows": [
    {"window_id": "7e02...", "index": 0, "title": "zsh", "display_name": "editor",
     "workspace": 1, "focused": true, "minimized": false, "x": 0, "y": 0,
     "width": 80, "height": 24, "pty_id": "4bff..."}
  ]
}}

A window that runs a program other than its shell has foreground_cmd, the program's name. It is omitted at a shell prompt.

A window whose process runs on another machine also has host. While the link to it is lost and the pane is being reattached, it has host_link: "reconnecting" and host_link_until, the unix time the far machine stops keeping the process (see A pane that outlives its link).

A window with a pane on this daemon also has history_rows and revision, the numbers capture-pane reports. A reader can compare revision with the one it last captured and skip the panes that did not change.

A window whose process runs on this machine also has pid, the process the pane started, and tty, the path of its terminal device. A zoomed window has zoomed: true. A floating window has floating: true. It sits over the tiled windows at its own rectangle.

A window that a process in another pane opened has started_by, that pane as {"session", "window"}. See Which pane started a pane.

get-window

Describe one window, as the client protocol's GetWindow command does. With a client attached the client answers, with its cursor and process fields; with none, the daemon answers with the window's list-windows entry. The window is resolved by the daemon either way, so a target that matches nothing is window_not_found. A client that does not answer in time is not waited on twice: the daemon's entry follows.

Params: session and window (both optional; window omitted means the focused window).

It is a read, like list-windows: a pane holding read may call it on its own session and its fan group, and a restricted connection on a session in reach. tuios get-window uses it.

Request:

{"verb": "get-window", "params": {"session": "work", "window": "build"}}

Response:

{"result": {"type": "window", "window_id": "7e02...", "index": 1, "title": "zsh",
 "display_name": "build", "workspace": 1, "focused": false, "minimized": false,
 "agent_state": "idle", "width": 80, "height": 24, "pty_id": "4bff..."}}

new-window

Create a new window in a session.

Params, all optional: session, name (window name; omit to use the shell's title), workspace (workspace number; omit for the calling pane's workspace, else the one the session shows), cwd (directory to start in; omit for the caller's directory when the caller runs in a pane, else the focused pane's), focus (default true; pass false to leave the focus where it is), command (argv to exec instead of a shell, not parsed by any shell; with a client attached, the window closes when it exits), host (run the window's process on a machine from the [hosts] table; omit or pass local for this machine), and close_on_exit (default false; close the window when its process exits, also with no client attached. Without it, a detached session keeps the window until something closes it), keep_open (default false; keep the window after its process exits, with a line that shows the exit status under the last output; not with close_on_exit), wait (default false; answer when the process exits, with exit_code and, when a signal stopped it, signal; not for a window on another machine), timeout (with wait, milliseconds before the timeout error; 0 waits with no limit), and env (an object of variables to set in the process; checked as start-agent checks its env; not for a window on another machine, and refused from another machine), and shell_integration (auto or off: whether the pane's bash or zsh starts with OSC 133 prompt marks on; omit it for [shell] integration; no effect on a window that runs a command). new-session takes the same env for its first window, and refuses it with window false.

A daemon that does not know keep_open and wait refuses them with invalid_params, as it refuses any parameter it does not know. A daemon from before that refusal ignores them: the result has no keep_open and no exit_code. A caller checks for those fields.

Request:

{"verb": "new-window", "params": {"session": "work", "name": "build"}}

Response:

{"result": {"type": "window_created", "window_id": "9a3c...", "name": "build"}}

split-window, zoom-window, swap-window, resize-window

The layout verbs. Each one names a pane with window. Without window, a caller in a pane of the session acts on its own pane, and any other caller on the focused pane. The daemon changes the layout itself, so these work with no client attached. An attached client lays its panes out again from the result, and a client that attaches later shows it.

split-window cuts a pane in two and opens a new window in the new half. Params: side (left, right, up or down: the side of the pane the new pane takes) or direction (vertical for right, horizontal for below), ratio (the new pane's share in percent, 1 to 99; omit for half), and name, command, cwd, focus, keep_open, close_on_exit, env, host, shell_integration and grants as for new-window. Without cwd, the pane starts in the caller's directory when the caller runs in a pane. The new pane is on the workspace of the pane it cuts. A floating, minimized or popup pane cannot be split (invalid_params). The verb turns tiling on when it is off. The result is new-window's, with type window_split, side and direction.

zoom-window zooms a pane to fill its workspace. Params: zoom (true or false; omit to toggle). Zooming a pane on the workspace the session shows focuses it. The result has window_id, zoomed and changed.

swap-window swaps two tiled panes. Params: with (required, the other pane). The panes must be on one workspace. The focus does not move.

resize-window moves one border of a tiled pane. Params: direction (required: right and down move a border right or down, left and up move it left or up) and amount (percent of the layout's width or height, 1 to 50; default 5). The border is the one on that side of the pane, or the one on the other side when the pane is at the edge there. The result has changed, false when no border could move.

move-window takes beside (a pane), side (default right) and ratio: the window leaves its place and splits that pane, on that pane's workspace.

In the master-stack and scrolling layouts, which place panes by order, an attached client does the swap and the resize.

{"verb": "split-window", "params": {"session": "work", "window": "build", "side": "down", "ratio": 30, "focus": false, "command": ["tail", "-f", "app.log"]}}
{"verb": "swap-window", "params": {"session": "work", "window": "build", "with": "logs"}}
{"verb": "resize-window", "params": {"session": "work", "window": "logs", "direction": "up", "amount": 10}}
{"verb": "zoom-window", "params": {"session": "work", "window": "build", "zoom": true}}

Open a popup: a floating pane that runs one command and closes when the command exits. Needs an attached client, and fails with needs_client when there is none.

Params: command (required argv), session (optional), width and height (optional, cells such as "60" or a share of the pane region such as "60%", default "80%" and "60%"), name, cwd, workspace and dim (all optional), wait, capture_stdout and timeout (optional, below), and scratch and scratch_name (optional). scratch starts a scratch group, the layout a key shows and hides, with its first pane. The pane is not a popup: it is a tiled window on the group's own workspace, numbered from 1000 up, which is never the session's current workspace. scratch_name names the group: empty is the built-in scratch terminal of toggle_scratch, and a [[keybindings.command]] entry of type scratch uses its own name. With scratch, command is optional and defaults to the shell. A session has one group per name, so a second call with the same name fails with invalid_params. A new-window with the group's workspace adds a pane to the group, and one with a scratch workspace no group is on fails. list-windows marks each pane of a group with "scratch": true and its "scratch_name". Every group survives a daemon restart, hidden, each pane with a new shell and its saved history.

dim is 0 to 90. Omitted, it inherits appearance.popup_dim (appearance.modal_dim for a TML popup); explicit 0 turns it off. Dimming applies only while the popup has focus.

The popup's command starts at the size the popup has on the screen: the size the caller asked for, in the session's pane region.

With wait the call stays open until the command exits, and answers with {"type": "popup_result", "window_id", "name", "exit_code"}. exit_code is -1 when a signal ended the command, which is how closing the popup by hand ends it. capture_stdout (which needs wait) gives the command a pipe the daemon owns as its standard output instead of the popup, and adds stdout (at most 1 MiB) and stdout_truncated to the answer. A picker such as fzf draws on the terminal and prints only the choice, so the choice is what comes back. It is refused on Windows. timeout bounds the wait in milliseconds; 0, the default, waits as long as the popup is open, and a wait that runs out fails with timeout and leaves the popup open. None of this grants anything: the caller picked the command, and what comes back is what it printed.

The size the caller asks for is session state and the rectangle it resolves to is not. Each attached client centres the popup in its own pane region, the way each client computes its own zoom box.

Request:

{"verb": "popup", "params": {"session": "work", "command": ["fzf"], "width": "60%"}}

Response:

{"result": {"type": "popup_opened", "window_id": "9a3c...", "name": "fzf",
            "workspace": 1, "pty_id": "4bff...", "width": "60%", "height": "60%"}}

close-window

Close a window.

Params: session (optional), window (optional target; defaults to the focused window). A window target matches, in order, an exact window ID, a unique ID prefix, an exact custom name, then an exact title.

Request:

{"verb": "close-window", "params": {"session": "work", "window": "build"}}

Response:

{"result": {"type": "ok"}}

close-workspace

Close every pane on a workspace, like tmux kill-window. A scratch pane stays unless the workspace named is its scratch workspace. A pane that calls it needs the admin grant.

Params: session (optional), workspace (optional; defaults to the current workspace).

Request:

{"verb": "close-workspace", "params": {"session": "work", "workspace": 2}}

Response:

{"result": {"type": "workspace_closed", "workspace": 2, "closed": ["a6e55709-...", "75684348-..."]}}

pip

Pin a pane as the attached client's picture-in-picture view, or unpin it. The view is a small live copy of the pane in a corner of the client's screen. It shows while another pane has the focus.

Params: session (optional), window (optional; a window ID or name), off (optional bool). Omit window to pin the client's focused pane. Naming the pinned pane again unpins it. off unpins whatever is pinned and takes no window.

The view belongs to the client, not to the session. It is not in session state, so the verb needs an attached client and fails with needs_client without one. The verb reaches one client: with more than one attached, the client that run-command reaches. A client attached to a session on another machine refuses the command from that machine's daemon, because the view is part of the person's own screen.

Request:

{"verb": "pip", "params": {"session": "work", "window": "agent"}}

Response:

{"result": {"type": "pip", "pinned": true, "window_id": "6a7ad980-..."}}

screenshot

Render a window to a styled image file. The picture is drawn from the pane's own cells, so colors, styles and OSC 8 links are exact, and the window chrome in it is drawn by the renderer rather than scraped off a client's border. It runs daemon side for the reason capture-pane does, so it answers on a detached session with nobody attached.

Params:

  • session (optional), window (optional).
  • format (optional): png (the default), svg, ansi, html or txt. Any other value is rejected with invalid_params.
  • frame (optional): window (the default), plain or none. ansi and txt are frameless whatever this says.
  • theme (optional): render in this theme instead of the session's. Indexed and basic cells re map cleanly; truecolor cells, which is most modern TUI output, are unchanged by it.
  • scrollback (optional bool): put the pane's history above the screen.
  • lines (optional int): bound the history to the last N rows. Needs scrollback.
  • cursor (optional bool): draw the cursor cell.
  • out (optional): write here instead of generating a name under screenshot.directory.

Everything else about the picture comes from the screenshot.* options.

Request:

{"verb": "screenshot", "params": {"session": "work", "window": "build", "format": "svg"}}

Response:

{"result": {"type": "screenshot", "path": "/home/u/Pictures/tuios/tuios-build-2026-08-25-204003.svg",
            "host": "daemon", "format": "svg", "cols": 78, "rows": 22, "bytes": 2407, "warnings": []}}

The verb always writes a file and returns its path. There is no bytes in the envelope route: the protocol is line delimited JSON, a scrollback PNG is megabytes, and a second delivery path is a second set of bugs. host names the machine the path is on, so a script never has to assume; a CLI reaching the daemon over its unix socket is on that machine by construction.

warnings is always present and empty when there is nothing to say. The one that matters is the no theme case: tuios can never read the host terminal's palette, so a session with no theme set renders basic and indexed colors in the xterm reference defaults and says so. Truecolor cells are exact regardless, and theme re renders in any installed palette.

A screenshot cannot contain kitty images a pane is displaying. Those are host side placements, not cells; the capture shows whatever cells sit under them.

Region and full screen captures are not verbs. They need a viewport, a layout and composed chrome, which only an attached client has, and they are reached from capture mode in the TUI.

resize

Resize a window's PTY.

Params: session (optional), window (optional), width (required, positive), height (required, positive).

Request:

{"verb": "resize", "params": {"session": "work", "width": 100, "height": 40}}

Response:

{"result": {"type": "resized", "width": 100, "height": 40}}

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page