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. There is no token or password on top of that.

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.7.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 62 verbs. 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

Files and worktrees

Other machines

Five more verbs, open-pane, pane-agent, pane-cwd, resize-pane and read-dir, are what one daemon calls on another to run a window's process on a different machine. You do not normally call them yourself.

Events and waiting

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.

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.

There is no backfill: events start at the moment you subscribe. Call list-windows first to learn the current state, then follow the stream.

The event types are window-created, window-closed, window-exit, window-retitled, window-focused, window-moved, window-minimized, window-restored, workspace-switched, agent-state, agent-message, output, bell, mode-changed, session-created, session-closed and gap.

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