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"
elif [ -S "/run/user/$(id -u)/tuios/tuios.sock" ]; then
  SOCK="/run/user/$(id -u)/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.

Limits

The daemon limits the connections and the memory that clients can use.

A TUIOS client takes a few connections. A command takes one connection while it runs. A request of 64 KiB or less, such as a key press, never waits for the memory budget.

busy and too_many_connections are the only errors that can clear without a change to the request. When you get busy, the daemon did nothing. Wait a short time and send the request again. If the connection closed, open a new one first. When you get too_many_connections, close some clients or commands, then connect again.

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.

Calling a verb from a command Added in v0.9.3

A program that can start a process but cannot write to the socket uses tuios call. It sends one verb and prints the reply as JSON.

tuios call list-sessions
tuios call list-windows '{"session":"work"}'

The daemon checks the call as it checks any request on the socket. call refuses the verbs that hold the connection open. See call in the CLI reference.

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. From a pane, it then means that pane's own session. From outside every pane, it 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}}

Added in v0.10.0 A client may also send term and color_term, its TERM and COLORTERM. A session that the connection makes later, with new-session, the create of switch-session or start-agent, gives its panes that terminal. A caller with no terminal of its own, such as a script, sends none, and its sessions get xterm-256color and truecolor.

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

Search

Over a link, these verbs need list.

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, or the nonce of attach-presence. They 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

File transfers Added in v0.9.3

These verbs act on the files of the machine whose daemon answers them. To reach the files of another machine, send them on a connection from open-host-connection. That machine's files policy then decides. Every path is absolute or starts with ~. A pane needs the admin grant to use them.

A copy goes on after the client exits, after a dropped link and after a daemon restart. Each file is checked with sha256 before it is put in place, and keeps the permission bits and modification time of the original. A destination that exists answers file_exists unless the call passes conflict: replace, keep-both, merge (a folder into a folder) or fail. With move, the original is removed after every file is checked. Links, named pipes, sockets and devices in a folder are not copied. The row counts them in skipped. See Remote Hosts.

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

stream-pane Added in v0.9.3

stream-pane sends one pane to a client that cannot read tuios's own wire format, such as a phone app. The client reaches the daemon with tuios stdio-proxy over ssh.

{"id":1,"verb":"stream-pane","params":{"session":"work","window":"build"}}

The daemon answers with one JSON line. After that line, the connection carries binary frames in both directions: one type byte, a 4-byte big-endian length, and the payload.

• Skip a frame type that you do not know. Read its length, then read and drop the payload.
• Keep the seq of the last frame you applied. Send it back as from_seq with boot_id to resume after a dropped connection. The reply mode is resume or snapshot.
• At most 4 I frames wait for a pane that does not read its input. The next one gets an E frame with busy.
• A lease holds the pane at most at that size. It lasts 30 seconds, so send the same L frame again every 10 seconds. When it ends, the pane goes back to the size its clients asked for. A lease never changes the session size or another pane.
• list on a linked machine allows the stream. I frames need write.

tuios pane-view is a client of stream-pane. It shows one pane in a terminal, with no tuios around it. See pane-view in the CLI reference.

attach-presence Added in v0.9.3

{"id":1,"verb":"attach-presence","params":{"session":"work"}}

The reply carries a human_nonce. The verbs that act as the person accept it, such as respond, reply-approval, answer-ask, dismiss-attention and agent-transcript. The connection is not attached, so it does not size the session or count as a viewer.

• A presence made with session acts only in that session. A presence with no session acts in every session.
• The caller must be outside every pane of this daemon. A process in a pane gets forbidden, so an agent cannot act as the person.
• The presence ends when its connection closes, or when the connection calls restrict-connection.

queue-prompt

{"id":1,"verb":"queue-prompt","params":{"window":"build","parts":[{"kind":"text","text":"this fails: "},{"kind":"paste","text":"--- FAIL: TestJitter\n…","n":1}]}}
{"id":1,"result":{"type":"prompt_queued","id":"q4","position":1,"queued":1,"delivering":true,"parts":2}}

text holds at most 16 KiB. Added in v0.10.1 parts gives the message as ordered parts, as the reply editor sends it. With parts, the daemon ignores text, so a client can send both and an older daemon types the text.

A message takes at most 64 parts, 8 images of 8 MiB each, and 8 MiB in total. The text parts with the label of each block must fit in 16 KiB. The daemon on the machine of the pane chooses how each block travels when it types the message:

• A message of 12 KiB or less, for a pane that takes a bracketed paste, goes in one paste with each block in its place.
• In any other message, each block goes to a file in the paste folder, and the text names it: [Pasted text #1: PATH, 42 lines]. The file is mode 0600, and the daemon keeps it for 24 hours.
• Each image goes to a file there too. The [input] images value of the harness puts its path in a paste of its own, in the text as [Image #1] PATH, or refuses the message with invalid_params. See How a reply is typed.

A pane's queue holds at most 32 MiB, and all queues together 128 MiB. Past either, the call fails with queue_full.

Added in v0.10.1 host names a machine from [hosts]. The daemon sends the message, with its parts, to the daemon of that machine over the link. That daemon queues it as link:THIS-MACHINE. Its policy for this machine must allow write, and files for a block or an image. Only a caller outside every pane can send host.

send-agent-message takes parts too. A message that fits in 8 KiB and holds no image gets its blocks in place. In any other message, the daemon writes each paste and image to the paste folder. The message attaches each file, and the body names it. A daemon from v0.10.0 or earlier answers text is required for a message in parts only.

reply-history and add-reply-history keep what the person sent to each agent, in the daemon's memory only. Both take a live human_nonce that proves the person for every session. add-reply-history takes target, parts and human_nonce. A target keeps 100 messages, and the daemon keeps 64 targets. reply-history takes target and human_nonce, and answers entries, oldest first, each with parts, at and dropped.

agent-transcript Added in v0.9.3

{"id":1,"verb":"agent-transcript","params":{"session":"work","window":"api","human_nonce":"294e0a27..."}}

The reply holds the newest limit entries (default 200, 1 to 1000), oldest first. Each entry has a stable id, at, role (user, assistant or tool) and kind (text, thinking, tool_call, tool_result, plan or todos). A tool call that edits a file carries its diff, with colour spans for each line.

• Send the reply's cursor as after to read what comes next.
• Send the reply's older as before to read the page before. older is empty at the start of the file.
• reset is true when the cursor no longer fits the file, for example after the agent started a new file. Start the list again.
• more is true when a read stopped before the end of the file. Read again with the new cursor.

The pane must be joined to a Claude Code transcript under ~/.claude/projects. Otherwise the call fails with no_transcript or unsupported_harness. Over a link the call needs respond. Subscribe to the transcript event to hear when the conversation grows.

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, transcript, transfer, transfer-progress, layout-changed and gap. With hosts, the stream also carries the agent-state and session events of every linked host.

transcript, transfer-progress and layout-changed are opt-in: they arrive only when types names them. Added in v0.10.0 A layout-changed event names the session and the workspace whose panes opened, closed, moved, were minimized, zoomed or resized, or whose session changed size. It is not kept for replay. Call list-windows to read the new rectangles. Added in v0.9.3 A transcript event says the conversation of a pane grew, with the cursor of agent-transcript. A transfer event has action created, state or ended, and the copy's row. transfer-progress carries the row while bytes move, at most four times a second.

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