Control Protocol

The TUIOS daemon accepts JSON requests on its Unix socket. Send one JSON object per line and read one JSON object back per line. No client library is needed: a shell, nc and jq are enough.

Use it when a script or program needs structured errors, blocking waits, or a live stream of events. For quick one-liners, the CLI commands such as tuios send-text and tuios wait-for do the same things and are built on this protocol.

Connecting

The protocol shares the socket the TUIOS client uses. There is no separate port and no handshake to negotiate: connect and write JSON. The daemon tells the two apart by the first byte, since a JSON request starts with { and a binary client frame never does.

if [ -n "$XDG_RUNTIME_DIR" ]; then
  SOCK="$XDG_RUNTIME_DIR/tuios/tuios.sock"
else
  SOCK="/tmp/tuios-$(id -u)/tuios.sock"
fi

printf '{"id":1,"verb":"list-sessions"}\n' | nc -U "$SOCK" | jq .

socat - UNIX-CONNECT:"$SOCK" works in place of nc -U "$SOCK". The socket path for Windows is in Sessions.

You can send several requests on one connection. They are answered in order, one response line per request line. To run requests in parallel, open more connections.

The socket is only accessible to your user: its directory is created with mode 0700, and TUIOS refuses a directory that another user owns or that is a symlink. There is no token or password on top of that. What a program inside a pane may do over the socket is limited by the pane's grants.

Discovering the protocol

The daemon describes itself, so you do not need this page to use it:

tuios list-verbs                # every verb, its parameters and example requests
tuios list-verbs capture-pane   # one verb
tuios list-verbs --json         # the same, as JSON

The output includes the protocol version, every parameter with its type, default and accepted values, the error codes, and the request and response shapes. The same catalogue is available over the socket as the list-verbs verb.

The accepted values come from the same lists the daemon checks requests against, so they cannot disagree with what it will actually take.

Requests and responses

A request has an optional id, a verb, and params when the verb takes any:

{"id":1,"verb":"send-text","params":{"session":"work","window":"build","text":"make\n"}}

The id can be a number or a string. It is echoed back on the response, and left out if you left it out.

A successful response carries a result. Every result has a type field naming its shape:

{"id":1,"result":{"type":"hello","protocol":1,"min_protocol":1,"daemon_version":"0.8.0","pid":4242,"sessions":2}}

A failure carries an error with a stable code, a readable message, and usually a hint:

{"id":2,"error":{"code":"invalid_params","message":"verb capture-pane has no parameter foo","hint":{"verb":"list-verbs","command":"tuios list-verbs capture-pane","param":"foo","accepted":["session","window","source","styled","scrollback","ansi","resolved","palette","lines","start","end"],"detail":"An unknown parameter is refused rather than silently ignored. Fix the name and retry."}}}

The hint says what to do next: the parameter that was wrong, the values it accepts, the closest match to what you typed (did_you_mean), the names that do exist (available), or a command to run. Every hint field is optional.

A few rules hold for every verb:

• Unknown parameters are refused, not ignored. A misspelt parameter fails with invalid_params instead of doing something you did not ask for.
• session can usually be left out. It then means the most recently active session.
• window takes a window ID or name. Left out, it means the focused window.
• A request that cannot do what it asked never reports success.

Versioning

hello reports the protocol version the daemon speaks and the oldest one it accepts. The current version is 1. Calling it first is optional: every other verb works without it.

{"id":1,"verb":"hello","params":{"client":"my-script","version":"1.0.0","protocol":1}}

A caller whose version is outside the accepted range gets protocol_mismatch. New verbs are added without changing the version; it changes only when an existing verb or the envelope changes incompatibly.

Verbs

The daemon currently implements 115 verbs, some of them only for one daemon to call on another. tuios list-verbs always reflects the binary you are talking to.

Discovery

Sessions

Windows

Workspaces and layout

Input and output

Options, themes and the dock

Agents and messages

The Inbox, the queue and review

The verbs that act as the person need the nonce a client receives when it attaches, and refuse a caller inside a pane even when it has a copy.

Files and worktrees

ship-push and ship-pr send nothing on the first call. They answer confirm_required: the hint's available lists what would be sent, and confirm carries a token. Call again with that token. A caller inside a pane or on a restricted connection also needs the person's allow in the Inbox, and the call waits for it (wait, default 120000 ms). See Ship and Checkpoints.

Other machines

More verbs, open-pane, pane-agent, pane-cwd, resize-pane, read-dir, wait-dir, close-pane, pane-calls, paste-pane-image and link-peer, are what one daemon calls on another to run a window's process on a different machine. You do not normally call them yourself.

With [agents] enabled = false, every agent verb fails with agents_disabled, and so do the agent conditions of wait-for. See Turn off agent features.

Events and waiting

Clients

list-clients takes no params:

{"verb": "list-clients"}

{"result": {"type": "client_list", "clients": [
  {"client_id": "client-1790941960197517900", "pid": 4242, "session": "work"}
]}}

• session is empty while the connection is not attached.
• pid is 0 on Windows and the BSDs.
• For an SSH or web client, pid is the local server process, not the remote SSH process or the browser.

The client-session-changed event follows the same connections. It carries client_id, pid, session and attached. attached is true when a client enters a session and false when it leaves, a disconnect while attached included. A session rename sends one event with the new name and attached: true for each client in the session.

Detaching clients

detach-client detaches clients, as tmux detach-client does. The sessions continue to run.

• client names one client from list-clients.
• session names a session. Every client of it detaches.
• Give one of the two, or neither. With neither, the verb acts on the client used last in the session of the caller's pane, else in the only session with a client.
• all_other keeps the named client, or the client used last, and detaches every other client of its session.

{"verb": "detach-client", "params": {"session": "work", "all_other": true}}

{"result": {"type": "clients_detached", "detached": ["client-1790941960197517900"]}}

Each detached client exits with status 0. An attach with detach_others set (tuios attach -d), or any attach while [daemon] single_client is on, detaches the other clients of the session in the same way. An unknown client fails with invalid_params. A pane needs the admin grant. Over a link the verb needs write.

Capturing windows

capture-pane reads one of two buffers, chosen by source:

• visible (default): the screen as it is now.
• recent: the screen plus the scrollback above it.

Set styled to keep ANSI colours and attributes, and resolved to turn the 16 theme colours into 24-bit RGB. Limit the output with lines (the last N lines) or with start and end (a 1-based inclusive range, which overrides lines).

{"id":1,"verb":"capture-pane","params":{"session":"work","window":"build","source":"recent","lines":50}}

Long lines come back split at the window's width. The emulator does not record which rows were soft-wrapped, so there is no unwrapped capture.

Waiting for conditions

wait-for replaces poll loops. It blocks until the condition matches, then returns a wait_result. If the timeout passes first, it fails with the timeout error code.

agent-state also takes any_session, or a select selector with every to wait for all the panes it matches.

timeout defaults to 30000 milliseconds. For window-output, source defaults to recent, so output that has already scrolled off the screen still matches.

{"id":1,"verb":"wait-for","params":{"condition":"window-output","session":"work","window":"build","pattern":"build (ok|failed)","timeout":120000}}

Event stream

subscribe turns the connection into a stream. The first line back is an acknowledgement carrying the current sequence number, and every line after it is an event:

{"id":1,"verb":"subscribe","params":{"session":"work","types":["window-created","window-closed","bell"]}}

{"id":1,"result":{"type":"subscribed","seq":42}}
{"seq":43,"type":"window-created","session":"work","window":"1f3c...","pty_id":"9ab2...","title":"build","time":1790102604545781000}

Filter with session, window and types. Leave types out to receive everything.

The acknowledgement carries seq, the last event number when the stream went live, and boot_id, a random id for this daemon start. Every event carries both. To resume after a disconnect, subscribe with after_seq and the boot_id it came with: the daemon replays the events it still holds after that seq, then carries on live. When it cannot replay everything you missed, a gap event comes first and names the reason (evicted, boot_changed, not_retained or overflow). Output events are never replayed. After a gap, read the current state again with list-windows or list-agents.

The event types are window-created, window-closed, window-exit, window-retitled, window-focused, window-moved, window-minimized, window-restored, workspace-switched, workspace-renamed, agent-state, agent-message, agent-activity, attention, output, bell, notification, mode-changed, prompt, command-started, command-finished, session-created, session-closed, client-session-changed, host-changed and gap. With hosts, the stream also carries the agent-state and session events of every linked host.

A workspace-renamed event fires when a workspace's name is set, changed or cleared. It carries session, workspace and title, the new name. title is absent when the name was cleared.

Events fire the same way whether a change came from a verb or from a person using the TUI. Window geometry changes do not produce events.

If you read too slowly, the daemon drops events rather than wait for you, and sends a gap event with the number dropped before the next one it delivers. queue sets how many events buffer before that happens (default 256).

Verbs that need an attached client

Some verbs change what is drawn, which needs a client to draw it: split-window, set-layout, popup, and focus-window with a direction. On a headless session, such as one made with tuios new --detach, they fail with needs_client instead of pretending to succeed. Attach a client first if you need them.

Error codes

Codes are stable, so it is safe to branch on them.

Examples

# Create a headless session and run a build in it
printf '{"verb":"new-session","params":{"name":"ci"}}\n' | nc -U "$SOCK"
printf '{"verb":"send-text","params":{"session":"ci","text":"make test\\n"}}\n' | nc -U "$SOCK"

# Block until it finishes, then read the last 20 lines
printf '{"verb":"wait-for","params":{"condition":"window-output","session":"ci","pattern":"(PASS|FAIL)","timeout":600000}}\n' | nc -U "$SOCK"
printf '{"verb":"capture-pane","params":{"session":"ci","source":"recent","lines":20}}\n' \
  | nc -U "$SOCK" | jq -r .result.content

# Watch for bells and exits in every session
printf '{"verb":"subscribe","params":{"types":["bell","window-exit"]}}\n' | nc -U "$SOCK" | jq -c .

Related