Protocol Verbs

Other verbs

Other verbs: part of the Protocol Verbs of TUIOS.

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

agent-message-receipts Added in v0.13.1

The mail one window sent and its state, newest last: delivered, seen (the recipient looked at its inbox without reading) or read, with the times, and undeliverable when the recipient window is gone. Marks nothing. On this machine it reads every session's ring and asks each linked machine for the mail this window sent there; over a link it answers only for mail that arrived on that link from that window, with ids, recipients and times. A message a ring no longer holds is not listed.

ParamTypeRequiredDefaultDescription
windowstringyesThe sending window's id, normally $TUIOS_PANE_ID. A restricted connection may name only its own window.
limitint20At most this many rows, newest last, at most 200.
Result fieldTypeDescription
receipts[]objectOne per message: id, host (empty for this machine), session, to, to_label, thread_id, sent_at, seen_at, read_at (Unix nanoseconds, 0 when not yet), undeliverable, and on this machine preview, the first line of the text.
waiting[]objectMail this window sent to a machine whose link is down, kept here until it is back: queue_id, host, session, to, queued_at.
unreachable[]objectLinked machines that could not be asked now: host and reason. Mail sent there is not listed.
{"id":1,"verb":"agent-message-receipts","params":{"window":"3f2a91c0-5b1e-4d7a-9c2f-0e8b6a4d1c3e"}}

agent-preset Added in v0.13.1

Merge an [agents.presets] entry of this daemon's config into start-agent params, as start-agent merges it, for a start-agent call on this machine or another one, so a preset of this machine works on every host. An unknown name is refused with the names there are.

ParamTypeRequiredDefaultDescription
presetstringThe preset to merge.
paramsobjectThe start-agent params to merge it into.
Result fieldTypeDescription
paramsobjectThe merged start-agent params, without preset.
{"id":1,"verb":"agent-preset","params":{"preset":"worker","params":{"name":"w3","session":"crew"}}}

agent-readiness Added in v0.13.1

Say for each harness whether it can start an agent on this machine: its program on the PATH, and for a harness whose manifest names a check ([launch] signed_in_args), whether it says it is signed in. The check runs the harness's own program, is bounded to 2 seconds, and its answer is kept for a minute; its output is matched and dropped.

ParamTypeRequiredDefaultDescription
harnesses[]stringHarness ids to answer for. Omit for every harness the registry knows.
envobjectPATH in it is where the programs are looked up, as for start-agent. Refused from another machine.
repo_urlstringAlso say if this machine has a checkout of it.
repos_rootstringWhere to look, as for start-agent.
peer_instancestringThe caller's daemon instance, for back.
Result fieldTypeDescription
agents[]objectOne per harness, by id: harness, name, command, installed, signed_in (yes, no or unknown; absent for a harness with no check), usage_limit.
repostringfound, none or many.
loadobjectcores, load1, load_ok, mem_pct, working, starting, started, instance.
capint[tasks] machine_cap, 0 for none.
backstringThis machine's name for the caller, when that link is up.
{"id":1,"verb":"agent-readiness","params":{}}
{"id":1,"verb":"agent-readiness","params":{"harnesses":["claude-code","codex"]}}

clear-history Added in v0.11.0

Clear a pane's scrollback for every client of the session.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
screenboolfalseAlso remove the rows above the prompt, as cmd+k does in Ghostty and iTerm2. The prompt row moves to the top of the pane. Without it, the screen stays, as with tmux clear-history.
Result fieldTypeDescription
windowstringThe id of the pane that was cleared.
screenboolWhether the rows above the prompt were removed too.
{"id":1,"verb":"clear-history","params":{"session":"work","window":"build"}}
{"id":1,"verb":"clear-history","params":{"session":"work","screen":true}}

close-pane Added in v0.8.0

End a pane this machine runs for another machine at once: its process is killed and its connection closed. The owning daemon sends it when the window is closed on purpose, so a resumable pane does not wait out its grace.

ParamTypeRequiredDefaultDescription
panestringThe pane id open-pane returned.
Result fieldTypeDescription
panestringThe pane that was ended.
closedboolAlways true.
{"id":1,"verb":"close-pane","params":{"pane":"f2c1"}}

daemon-upgrade Added in v0.13.1

Upgrade the daemon live to another tuios binary. Every pane's process keeps running, with the same pid, terminal and screen, and the daemon keeps its pid. The binary is run once first and must say it reads this daemon's state; a refusal changes nothing. The call answers once every pane is stopped and written down. Then every client is told and dropped, and the daemon execs the binary in place. Call hello until instance changes: its upgrade field says what the handoff measured, and has fallback set when the new binary could not take the panes and the binary that was running took them back, and recovered too when the new image died first and the handoff's keeper started that binary under a new pid. Refused on Windows, while a pane runs on another machine or here for another machine, while a fan check, a capturing popup, a hook or a plugin command runs, and to a plugin or over a link, whatever its grants. From a caller inside a pane it first asks the person in a dialog on every attached client, naming the binary's full path, its version and the pane, and blocks for up to 60 s: only Yes, pressed at a client, lets it go on, and anything else is forbidden.

ParamTypeRequiredDefaultDescription
binarystringAbsolute path of the tuios binary to run the daemon as.
Result fieldTypeDescription
pidintThe daemon's pid, which the upgrade keeps.
instancestringThe running image's id. hello reports another one once the new image runs.
fromstringThe version running now.
tostringThe version the binary reports.
binarystringThe binary, as an absolute path.
handoffintThe version of the state handed over.
panesintHow many panes are handed over.
manifest_bytesintThe size of the state handed over.
clientsintThe attached TUI clients the upgrade dropped. A tuios client on this machine attaches again by itself.
preflight_msintHow long the binary took to answer the preflight.
{"id":1,"verb":"daemon-upgrade","params":{"binary":"/usr/local/bin/tuios"}}

delegate Added in v0.13.1

Hand a task to a child agent: start it with start-agent, linked to its parent and never wider than it, and type the task as its first prompt. Without wait the call returns at once, and the child's answer comes to the parent as mail from the child once it finishes, which wakes the parent at rest. A question the child stops on comes as mail too, and an approval stays in the Inbox. With wait the call returns the outcome itself: done, a question or an approval, or the timeout, which does not stop the child. A call from outside every pane names the parent or waits.

ParamTypeRequiredDefaultDescription
promptstringyesThe task, typed as the child's first prompt.
agentstringThe child agent, as start-agent takes it. Omit for the parent's own harness.
args[]stringMore arguments for the agent, as an argv.
rolestringgeneralThe job. It names the child's window and shows in list-agents. research and review default grants to read. It adds no text to the prompt. One of implementation, research, review, design, test or general.
isolationstringsharedshared: the child works in the parent's folder. worktree: in a new worktree, in a session of its own, made from the commit of the parent's checkout. A worktree does not have uncommitted changes. One of shared or worktree.
namestringThe child's window name. Omit for the role.
sessionstringSession to open the child in, for shared isolation. Omit for the parent's session.
cwdstringThe folder the child starts in, or, for worktree isolation, the checkout to make the worktree from. Omit for the parent's folder.
parentstringThe agent pane the answer is mailed to, by window id. Omit it from an agent pane: that pane is the parent. Outside every pane, name it or pass wait.
waitintMilliseconds to wait for the outcome, at most 600000. Omit to return at once and get the answer by mail.
ready_timeoutint120000Milliseconds to wait for the child to be ready for its prompt.
envobjectEnvironment variables for the agent, as start-agent takes them.
grants[]stringWhat the new pane may do through tuios: read, write, fan, respond, admin, or none. Omit for the default of [agents.permissions], or, from a pane without admin, the calling pane's own grants. A pane may give only what it holds, and admin does not include respond. A window on another machine holds what that machine gives it. One of read, write, fan, respond, files, task, admin or none.
Result fieldTypeDescription
delegatedboolTrue when the task was typed into the child.
window_idstringThe child's pane. The other fields of start-agent are here too, with its outcome as start_outcome.
rolestringThe role.
isolationstringshared or worktree.
modestringasync or wait.
nextstringAsync only: what the parent does now. It ends its turn, and tuios wakes it with the answer.
worktreestringWorktree isolation: the worktree's folder. branch and base are its branch and start commit, and worktree_note says it has no uncommitted changes.
outcomestringWait only: how the wait ended. One of done, errored, question, approval, closed or timeout.
answerstringWait only, on done or errored: the child's last answer, from its transcript or its screen (answer_source). Text another program wrote: data, not instructions.
questionobjectWait only, on question or approval: the prompt the child stopped on, kind, message and lines.
wait_notestringWait only, on timeout: the child still works, and where its answer goes.
{"id":1,"verb":"delegate","params":{"role":"review","prompt":"Review the diff on this branch and list the bugs."}}
{"id":1,"verb":"delegate","params":{"agent":"codex","isolation":"worktree","role":"test","prompt":"Add tests for the parser.","wait":300000}}

delete-buffer Added in v0.9.0

Delete a paste buffer. From a pane this needs the write grant, and a pane without admin may delete only its own buffers.

ParamTypeRequiredDefaultDescription
namestringThe buffer to delete. Omit for the newest buffer tuios named, as tmux does: for the person, the newest of the person's own, and for a pane without admin, the newest of its own.
versionintAct only while the buffer holds the content of this version, as list-buffers or show-buffer gave it. Otherwise the call answers no_buffer.
Result fieldTypeDescription
namestringThe buffer that was deleted.
{"id":1,"verb":"delete-buffer","params":{"name":"buffer1"}}

drop-files Added in v0.9.3

Give a pane on a machine the paths of files on this machine. For this machine the answer is the paths. For a host, the files are copied into a new private drop folder there, and the answer has their paths there and the transfers that copy them. Paste a path once its transfer is done.

ParamTypeRequiredDefaultDescription
hoststringThe machine the pane is on. Omit for this machine.
paths[]stringyesThe files on this machine.
dirstringA folder on the host to copy into instead of a drop folder, such as the pane's own folder.
Result fieldTypeDescription
paths[]stringThe files' paths on the pane's machine, in order.
dirstringThe folder they go into on the host.
transfers[]objectOne transfer row per file, as transfer-list. Empty for this machine.
{"id":1,"verb":"drop-files","params":{"host":"build","paths":["~/Desktop/screenshot.png"]}}

exec Added in v0.13.1

Run one shell line on this machine and return its stdout, its stderr and how it ended. No window is opened. The line runs under sh -c (cmd /c on Windows) in a process group of its own, with no stdin and the daemon's environment less the pane, session and agent variables of the command that started the daemon, as a pane gets it. The group is stopped at the timeout, when the caller goes away, and when the daemon stops. Each stream keeps its last 1 MiB. At most 8 run at once. Over a link it needs open, as new-window does.

ParamTypeRequiredDefaultDescription
linestringyesThe command line, parsed by the shell, at most 16384 bytes.
cwdstringDirectory to run in. It must exist. Omit for the daemon's home directory.
timeout_msintHow long the line may run, in milliseconds, at most one hour. Omit for 30000.
Result fieldTypeDescription
stdoutbytesWhat the line wrote to stdout, base64 in JSON.
stderrbytesWhat the line wrote to stderr, base64 in JSON.
stdout_droppedintBytes cut from the start of stdout to keep the last 1 MiB.
stderr_droppedintBytes cut from the start of stderr to keep the last 1 MiB.
exitintThe exit status. Absent when the line was stopped by a signal, the timeout or the caller leaving.
signalstringThe signal that stopped the line, such as killed. Absent when it exited.
signal_numberintThe number of that signal, such as 9.
timed_outboolThe timeout stopped the line.
duration_msintHow long the line ran.
{"id":1,"verb":"exec","params":{"line":"uname -a"}}
{"id":1,"verb":"exec","params":{"line":"ls -la","cwd":"/tmp","timeout_ms":60000}}

file-abort Added in v0.9.3

Remove the part a copy to a path left on this machine.

ParamTypeRequiredDefaultDescription
pathstringyesThe file the copy was for. An absolute path, or one that starts with ~.
part_idstringThe copy's part id, up to 32 hex digits: the part is .NAME.tuios-part-ID, so two copies to one path write two parts. Omit for .NAME.tuios-part.
Result fieldTypeDescription
pathstringThe path.
{"id":1,"verb":"file-abort","params":{"path":"~/big.iso"}}

file-check Added in v0.9.3

Describe many files under a folder on this machine at once, for a copy that leaves out what is there already: whether each is there, its kind, size and time, and with hash its sha256. At most 2000 files, and 512 MiB hashed, in one call.

ParamTypeRequiredDefaultDescription
rootstringyesThe folder. An absolute path, or one that starts with ~.
rels[]stringyesThe files, as paths under the folder, slash separated.
hashboolHash each regular file.
Result fieldTypeDescription
entries[]objectOne per file, in order: rel, exists, kind (file, dir, symlink, other), size, mtime (Unix ms), sha256 when hashed.
{"id":1,"verb":"file-check","params":{"root":"~/src","rels":["a.go","b/c.go"],"hash":true}}

get-keep-awake Added in v0.13.1

Report whether the daemon holds the machine awake: [daemon] keep_awake, the hold, the working agent panes on this machine, and the method the system uses.

No params.

Result fieldTypeDescription
modestring[daemon] keep_awake in force. One of off, agents or on.
heldboolTrue while the daemon holds the machine awake.
workingintAgent panes that work now on this machine.
methodstringHow the hold is made: systemd-inhibit, caffeinate, SetThreadExecutionState, or none.
errorstringWhy the machine could not be held awake. Absent when nothing failed.
{"id":1,"verb":"get-keep-awake"}

get-note Added in v0.12.0

Read the return note of a session, or of one pane with window. See set-note.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name for a pane's note. Omit for the session's note.
Result fieldTypeDescription
typestringAlways note.
sessionstringThe session's name.
windowstringThe id of the pane, empty for the session's note.
notestringThe note, empty when there is none.
{"id":1,"verb":"get-note","params":{"session":"work"}}

host-speed-test Added in v0.9.3

Measure the link to a host the way a copy uses it: the round trip of a small call, then bytes up and down on bulk streams. The bytes are random, so compression does not help them.

ParamTypeRequiredDefaultDescription
hoststringyesA name from [hosts].
bytesint67108864How many bytes each way.
Result fieldTypeDescription
rtt_msfloatThe middle of five round trips, ms.
upfloatBytes a second from this machine to the host.
downfloatBytes a second from the host to this machine.
up_msintHow long the bytes up took.
down_msintHow long the bytes down took.
{"id":1,"verb":"host-speed-test","params":{"host":"build","bytes":16777216}}

judge-fan Added in v0.11.0

Start an agent that judges the attempts of a fan. It runs in a new session of its own, named after the fan with -judge, in the repository's main checkout, with the read grant alone. Once its pane exists, the attempts name that pane, and that pane alone reads them: it cannot type into them, run commands in their sessions or start agents there. Its first prompt, typed then, asks it to read the attempts and report its pick with set-fan-verdict. Only the person or a pane with admin starts a judge. The record is cleared when the judge's session ends. It answers once the agent is ready, as start-agent does.

ParamTypeRequiredDefaultDescription
sessionstringyesAny session of the fan.
agentstringThe judge's agent, as start-agent takes it. Omit for the agent the first attempt ran.
envobjectEnvironment variables for the judge, as start-agent takes them.
ready_timeoutint120000Milliseconds to wait for the judge to be ready.
Result fieldTypeDescription
judge_sessionstringThe judge's session.
groupstringThe fan's group.
window_idstringThe judge's pane, with the rest of what start-agent returns.
{"id":1,"verb":"judge-fan","params":{"session":"api-fan-retry"}}

Name the machine a link connection came from. tuios stdio-proxy sends it as the first line of every connection it opens for a link, and the daemon resolves that machine's link policy from the name. Accepted once per connection, before anything else, and only on a link socket. After the reply the connection is read from scratch, JSON or binary.

The connection stays open after the reply.

ParamTypeRequiredDefaultDescription
peerstringThe machine's name: the one the hub gave for itself, or the one the proxy was pinned to with --as. Empty for none.
pinnedboolThe name came from stdio-proxy --as on this machine, not from the hub.
ssh_auth_sockstringThe SSH_AUTH_SOCK stdio-proxy runs with: the agent the link's ssh forwards. A client attached through the link uses it for ssh_agent = "follow".
closesstringThe close_token of another link connection. The far side closed that connection's stream on purpose, so a size lease it holds ends at once and does not wait for a viewer to come back.
Result fieldTypeDescription
peerstringThe name the connection is held to.
close_tokenstringThe token stdio-proxy sends back as closes when the far side closes this connection's stream on purpose.
{"id":1,"verb":"link-peer","params":{"peer":"laptop"}}

list-buffers Added in v0.9.0

List the paste buffers, newest first. A yank in copy mode adds one, and so does set-buffer. From a pane this needs the read grant, and a pane without admin sees only the buffers it set. Every total counts only the buffers listed.

ParamTypeRequiredDefaultDescription
sample_widthint60How many characters each sample shows, at most 200.
Result fieldTypeDescription
buffers[]objectOne entry per buffer, newest first: name, bytes, created, automatic, sample, session, pane.
totalintHow many buffers there are.
bytesintHow many bytes they hold together.
limitintHow many buffers the daemon keeps, from [paste_buffers] limit.
max_bytesintHow many bytes the buffers may hold together, from [paste_buffers] max_kb.
{"id":1,"verb":"list-buffers"}

list-push Added in v0.9.3

List the phones registered with register-push, and the daemon's VAPID public key. A phone's endpoint is shown only as its origin. Only the person, by the rules of register-push.

ParamTypeRequiredDefaultDescription
human_noncestringThe nonce of an attach, or of an attach-presence made with no session, from the same process.
Result fieldTypeDescription
devicesobject[]Each phone: device, kinds, service (the endpoint's origin), created, and last_ok or last_error when a push was tried.
vapid_public_keystringThe daemon's VAPID public key, base64url. A phone needs it before it subscribes.
machinestringThis machine's name.
{"id":1,"verb":"list-push","params":{"human_nonce":"<from attach-presence>"}}

list-recordings Added in v0.13.1

List the recordings that run now, across every session.

No params.

Result fieldTypeDescription
recordings[]objectOne entry per recording: path, window, started_at.
{"id":1,"verb":"list-recordings","params":{}}

list-routes Added in v0.12.1

List the addresses this machine has now, so a phone paired on one network can reach it from another.

No params.

Result fieldTypeDescription
routes[]objecthost (a name or an IP, without a port) and kind (tailnet, lan or public), the tailnet name first.
{"id":1,"verb":"list-routes"}

mark-recording Added in v0.13.1

Write a marker (an m event) into a pane's recording at the current time, so a player can jump to the moment.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
labelstringThe marker's label, one line of at most 200 bytes.
Result fieldTypeDescription
pathstringThe file being written.
windowstringThe id of the pane recorded.
labelstringThe label written.
{"id":1,"verb":"mark-recording","params":{"session":"work","window":"build","label":"tests start"}}

open-pane Added in v0.8.0

Spawn a process on this machine and turn this connection into its pty. After the reply, every byte written here reaches the process and every byte it writes comes back. Send nothing until the reply has arrived. This is the far half of a global session: the pane belongs to the session on the daemon that asked, which draws it and sizes it; this machine supplies the process and nothing else.

The connection stays open after the reply.

ParamTypeRequiredDefaultDescription
widthintThe pane's width in cells, decided by the layout that owns the window. Out of range falls back to 80.
heightintThe pane's height in cells. Out of range falls back to 80.
cwdstringA directory on this machine to start in. Ignored when it does not exist here, since the asking machine's path need not mean anything on this one.
command[]stringAn argv to run in place of the shell. Omit for a login shell.
termstringTERM for the process. It comes from the asking session because that session's emulator is what the process is talking to.
color_termstringCOLORTERM for the process, for the same reason.
shellstringThe shell to run. Omit to use this machine's.
sessionstringThe asking session's name, exported as TUIOS_SESSION_REMOTE.
windowstringThe asking daemon's id for the window the pane is drawn in. Exported as TUIOS_PANE_ID, and a promise to open the pane's report channel with pane-calls: a report the process sends naming it is forwarded there.
resumableboolAsk for the pane to outlive a dropped connection for the grace this machine's link policy gives the asking machine (hosted_grace), so it can be reattached with resume. The reply carries resume_token and grace when one was given.
resumeobjectReattach a pane instead of starting one: {"pane": id, "token": resume_token, "offset": bytes of output already received}. What was missed is written after the reply, from the pane's 64 KB ring, and the pane is live again from there.
kitty_mediaboolRead the files that kitty graphics commands in the pane name (t=f, t=t, t=s) on this machine. Each command is answered here when the file may not be read, and replaced by a marker for pane-kitty-medium when it may. The reply carries kitty_media_token when the asking machine may read files here.
Result fieldTypeDescription
panestringThe id that addresses this pane in resize-pane. It lives as long as the connection does, or with resumable until its grace runs out.
calls_tokenstringThe secret pane-calls takes. Present only when window was sent.
resume_tokenstringThe secret a reattach takes. Present only when resumable was asked and a grace was given.
graceintHow many seconds the pane waits to be reattached after its connection drops.
resumedboolTrue on a reattach.
pixelsboolresize-pane takes xpixel and ypixel.
kitty_media_tokenstringThe secret pane-kitty-medium takes. Present only when kitty_media was asked and the asking machine may read files here.
gapboolOn a reattach, true when more output was missed than the ring holds: the whole ring is written, and the screen may need a redraw.
{"id":1,"verb":"open-pane","params":{"width":120,"height":40}}

open-tree-stream Added in v0.9.3

Turn this connection into a tree stream: many files of a folder in one stream. mode read: the caller writes one line {rel, size, mtime} per file and {end}, and gets one record per file and {end}. mode write: the caller writes records, and gets one ack {rel, path, sha256, skipped} or {rel, code, error} per file and {end}. A record is a header line {rel, kind, size, perm, mtime, z, conflict, label}, the bytes (one flate stream when z), and a trailer line {sha256}. docs/protocol.md has the whole format.

The connection stays open after the reply.

ParamTypeRequiredDefaultDescription
rootstringyesThe folder the paths are under. An absolute path, or one that starts with ~.
modestringyesread or write. One of read or write.
part_idstringwrite: the copy's part id, which names the parts.
compressboolread: send a file as flate when a sample of it compresses well.
Result fieldTypeDescription
rootstringThe folder, made absolute.
{"id":1,"verb":"open-tree-stream","params":{"root":"~/src","mode":"read","compress":true}}

pane-agent Added in v0.8.0

What a pane this machine runs for another machine has running in it. The machine with the process is the only one that can look: the daemon that owns the window reads a pid that means nothing there, so without this a pane on another machine is invisible to agent detection. This side reads the process; the side that owns the window decides what it means.

ParamTypeRequiredDefaultDescription
panestringThe pane id open-pane returned.
Result fieldTypeDescription
panestringThe pane asked about.
runningboolWhether a foreground process could be read at all.
commstringThe process name, as the kernel reports it.
argvarrayThe full command line.
exestringThe resolved binary, empty when it cannot be read.
pidintThe foreground process, zero when none was resolved.
shell_pidintThe pane's own shell, which is a fact about the pane rather than about what it runs.
{"id":1,"verb":"pane-agent","params":{"pane":"f2c1"}}

pane-calls Added in v0.8.0

Open the report channel of a pane this machine runs for another machine. Only the daemon that owns the window holds the token. After the reply this machine writes one request line per report the pane's process sends naming its pane ({"id","verb","params"}: set-agent-state, set-agent-meta, set-agent-session, read-agent-messages, send-agent-message, or wait-for agent-message), and the owner answers each with {"id","result"} or {"id","error"}. The owner runs every request as its own window, whatever it says.

The connection stays open after the reply.

ParamTypeRequiredDefaultDescription
panestringThe pane id open-pane returned.
tokenstringThe calls_token open-pane returned.
Result fieldTypeDescription
panestringThe pane whose channel this connection now is.
{"id":1,"verb":"pane-calls","params":{"pane":"f2c1","token":"<from the open-pane reply>"}}

pane-cwd Added in v0.8.0

Where a pane this machine runs for another machine has its process. The machine with the process is the only one that can say: the daemon that owns the window reads a pid that means nothing there, and a shell may never announce its directory.

ParamTypeRequiredDefaultDescription
panestringThe pane id open-pane returned.
Result fieldTypeDescription
panestringThe pane asked about.
cwdstringThe directory the process is in, empty when it cannot be read.
{"id":1,"verb":"pane-cwd","params":{"pane":"f2c1"}}

pane-kitty-medium Added in v0.11.0

Turn this connection into the bytes of an image that a pane this machine runs for another machine named by path in a kitty graphics command (t=f, t=t or t=s). The pane's output holds a marker with the id in the command's place. Only the daemon that owns the window holds the token. After the reply the connection carries size bytes, as one flate stream when compressed is set, then closes. A temporary file or a shared memory object is deleted after it is read.

The connection stays open after the reply.

ParamTypeRequiredDefaultDescription
panestringThe pane id open-pane returned.
tokenstringThe kitty_media_token open-pane returned.
idstringThe id in the marker.
Result fieldTypeDescription
panestringThe pane the image is from.
sizeintThe image's bytes, before compression.
compressedboolThe bytes come as one flate stream.
{"id":1,"verb":"pane-kitty-medium","params":{"pane":"f2c1","token":"<from the open-pane reply>","id":"<from the marker>"}}

paste-buffer Added in v0.9.0

Type a paste buffer into a window's PTY as a paste. Each line feed becomes a carriage return unless raw, as in tmux. Control characters other than tab, line feed and carriage return are removed, and the text is wrapped in the bracketed paste delimiters when the program in the pane turned bracketed paste on. From a pane this needs the read and write grants.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
namestringThe buffer to paste. Omit for the newest buffer tuios named, as tmux does: for the person, the newest of the person's own, and for a pane without admin, the newest of its own.
deleteboolfalseDelete the buffer after the paste, unless its content was set again meanwhile.
rawboolfalseKeep each line feed instead of turning it into a carriage return.
versionintAct only while the buffer holds the content of this version, as list-buffers or show-buffer gave it. Otherwise the call answers no_buffer.
allow_blockedboolfalseFrom a pane, type into a pane on needs_input instead of refusing with agent_blocked. What is typed then answers its prompt, which also needs the respond grant. The person, outside every pane, is not held.
Result fieldTypeDescription
namestringThe buffer that was pasted.
bytesintHow many bytes the buffer holds.
bracketedboolTrue when the paste went in the bracketed paste delimiters.
deletedboolTrue when the buffer was deleted after the paste.
{"id":1,"verb":"paste-buffer","params":{"session":"work","window":"build"}}
{"id":1,"verb":"paste-buffer","params":{"session":"work","name":"deploy","delete":true}}

paste-pane-image Added in v0.8.3

Write an image for a pane this machine runs for another machine, and answer with the path here. Only the daemon that owns the window holds the token it needs. That daemon sends it for a paste-image the person made.

ParamTypeRequiredDefaultDescription
panestringThe pane id open-pane returned.
tokenstringThe calls_token open-pane returned.
contentstringThe image, base64, at most 8 MB decoded.
Result fieldTypeDescription
panestringThe pane the image is for.
pathstringThe image's path on this machine.
bytesintHow many bytes were written.
{"id":1,"verb":"paste-pane-image","params":{"pane":"f2c1","token":"<from the open-pane reply>","content":"iVBORw0KGgo="}}

place-agent Added in v0.13.1

Pick the machine for a new agent, this one or a linked one, and say why. A machine is left out when the agent is not installed, signed in or free of a usage limit there, it has no checkout of the repository, its memory is full, it is at its cap, or for a card it has no link back. Of the rest the most spare cores wins; a tie goes to the checkout, then this machine. Starts nothing. Refused over a link.

ParamTypeRequiredDefaultDescription
agentstringThe harness, such as claude. Default: the card's.
repo_urlstringThe repository by origin URL. Default: the card's project.
repos_rootstringWhere this machine looks for it.
cloneboolfalseA machine with no checkout may clone one.
local_originstringThe origin of the caller's folder here: this machine has that checkout.
taskstringA card of this daemon the agent takes.
task_sessionstringThe card's session.
reservebooltrueCount the pick as busy there for 90 seconds.
exclude[]stringMachines to leave out; local is this one.
envobjectPATH for this machine, as for start-agent.
Result fieldTypeDescription
hoststringThe pick, empty for this machine.
namestringThe pick as a person reads it.
whystringOne line on why.
task_hoststringWith task: the pick's name for this machine, for start-agent.
cloneboolThe pick clones the repository.
machines[]objectEvery machine, the pick first: host, name, ok, why, repo.
{"id":1,"verb":"place-agent","params":{"agent":"claude"}}
{"id":1,"verb":"place-agent","params":{"agent":"codex","repo_url":"git@github.com:acme/api.git"}}
{"id":1,"verb":"place-agent","params":{"task":"t4","task_session":"api"}}

plugin-cell Added in v0.13.1

Set or clear one dock cell of the calling plugin. Only a process of a native plugin that holds the ui grant may call it, and the manifest must name the cell in [[cell]]. The daemon keeps the text until the plugin changes it or stops. At most 8 changes a second for one plugin.

ParamTypeRequiredDefaultDescription
idstringyesThe id of the [[cell]] in the manifest.
textstringOne line of at most 512 bytes. SGR colour stays. Other control sequences are dropped.
actionstringThe id of an action of the plugin that a click runs.
clearboolRemove the cell.
Result fieldTypeDescription
idstringThe cell.
{"id":1,"verb":"plugin-cell","params":{"id":"status","text":"CI ok","action":"open"}}

plugin-notify Added in v0.13.1

Show the person a notification under the calling plugin's name. Only a process of a native plugin that holds the ui grant may call it. At most 8 changes a second for one plugin, shared with plugin-cell.

ParamTypeRequiredDefaultDescription
textstringyesThe message. tuios keeps the first 200 characters on one line.
levelstringinfo, warning or error. The default is info. One of info, warning or error.
Result fieldTypeDescription
typestringplugin_notified.
{"id":1,"verb":"plugin-notify","params":{"text":"The build failed","level":"error"}}

rail-pane Added in v0.12.0

Start, keep or close the session's rail pane: the pane an attached client draws in its rail's pane section. A session has at most one. It sits on a workspace no client shows, so it is in no layout and in no list a user reads. The daemon owns its process, so it survives a detach, and closes it when the process exits. The attached client calls this from its [appearance.sidebar.pane] table.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
keystringThe command line the pane runs, as configured. A pane with the same key is kept, and a pane with another key is closed and replaced.
commandstring[]The argv the pane runs. Required unless off is set.
cwdstringDirectory the program starts in. Omit to inherit the focused pane's.
widthintColumns the program starts at.
heightintRows the program starts at.
offboolfalseClose the rail pane, if there is one. Takes no command.
Result fieldTypeDescription
window_idstringId of the rail pane, empty after off.
createdboolWhether this call started it.
{"id":1,"verb":"rail-pane","params":{"session":"work","key":"htop","command":["sh","-c","htop"],"width":27,"height":12}}
{"id":1,"verb":"rail-pane","params":{"session":"work","off":true}}

read-dir Added in v0.8.0

List a directory on this machine, as the rail's file section reads it. The machine with the process is the machine with the files, so a pane running here is listed here.

ParamTypeRequiredDefaultDescription
dirstringThe directory to list.
maxintAt most this many names. Omit for the built-in cap.
Result fieldTypeDescription
dirstringThe directory listed.
entries[]stringOne entry per name, carrying the name and whether it is a directory. Directories first, then names, case insensitively.
cappedboolThe directory holds more names than were sent.
errstringWhy there is no listing, in words a person can act on.
{"id":1,"verb":"read-dir","params":{"dir":"/home/ubuntu"}}

record-pane Added in v0.13.1

Record a pane to an asciicast v2 file (.cast) that asciinema, agg and reel play. The first event paints the screen the pane shows now, its history included; then every output chunk and resize is an event at its real time. Input is not recorded. The recording runs until stop-recording, duration_ms, max_bytes or the pane's end. The file holds everything the pane prints while it runs.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
outstringyesThe path of the file to write, absolute or starting with ~, made with mode 0600. Over a link, held to the file verbs' write rules.
overwriteboolfalseReplace out when it exists. Without it, an existing file is refused with file_exists.
duration_msint0Stop after this long. 0 records until stopped.
max_bytesint67108864Stop when the file reaches this size, with a size limit marker. Between 4096 and 1073741824.
titlestringThe title the header carries, which players show.
Result fieldTypeDescription
pathstringThe file being written.
windowstringThe id of the pane recorded.
widthintThe pane's width when the recording started, the header's width.
heightintThe pane's height when the recording started, the header's height.
started_atstringWhen the recording started, RFC 3339 in UTC.
{"id":1,"verb":"record-pane","params":{"session":"work","window":"build","out":"~/build.cast"}}

remove-push Added in v0.9.3

Remove a phone registered with register-push. Only the person, by the rules of register-push.

ParamTypeRequiredDefaultDescription
devicestringThe phone's name.
human_noncestringThe nonce of an attach, or of an attach-presence made with no session, from the same process.
Result fieldTypeDescription
devicestringThe phone removed.
removedboolAlways true. An unknown name is refused with invalid_params.
{"id":1,"verb":"remove-push","params":{"device":"pixel","human_nonce":"<from attach-presence>"}}

report-program-status Added in v0.13.1

Apply one OSC 7501 report (the Program Status Protocol) to a pane, as if the pane's emulator read it from the pane's output. tuios status sends it when the process has no terminal, such as an agent's shell tool. The report gets the same checks, records and lifetime as one the pane writes. A pane may report only for itself, as with set-agent-state.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit from a pane for the pane itself, and from outside every pane for the focused window.
reportstringyesThe body of the report: the text between ESC ] 7501; and the string terminator, such as state=working:app=build. A report a terminal would discard is refused, and nothing is recorded.
Result fieldTypeDescription
window_idstringThe window the report was applied to.
program_status[]objectThe pane's records after the report, as get-agent-state reports them.
{"id":1,"verb":"report-program-status","params":{"session":"work","report":"state=done:app=build:msg=QnVpbHQ="}}

resize-pane Added in v0.8.0

Resize a pane this machine is running for another machine. It arrives on its own connection because the pane's connection carries raw bytes and has no room to say anything out of band.

ParamTypeRequiredDefaultDescription
panestringThe pane id open-pane returned.
widthintThe new width in cells.
heightintThe new height in cells.
xpixelintThe new width in pixels, for programs that scale images to it. Omit to use the fallback cell size.
ypixelintThe new height in pixels.
Result fieldTypeDescription
panestringThe pane that was resized.
widthintThe width it was set to.
heightintThe height it was set to.
{"id":1,"verb":"resize-pane","params":{"pane":"f2c1","width":120,"height":40}}

resize-window Added in v0.13.1

Move one border of a tiled pane. right and down move a border right or down, left and up move it left or up. The border is the one on that side of the pane, or the other one when the pane is at the edge there. Works with no client attached.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringPane to resize. Omit for the caller's own pane, or outside a pane the focused one.
directionstringyesThe way the border moves. One of left, right, up or down.
amountint5How far the border moves, in percent of the layout's width or height, from 1 to 50.
Result fieldTypeDescription
window_idstringId of the pane.
changedboolFalse when no border could move: the pane is alone, floating, or at the smallest or largest share.
{"id":1,"verb":"resize-window","params":{"session":"work","window":"build","direction":"right","amount":10}}

retry-host Added in v0.9.0

Dial the link to one host again now. The backoff starts again from one second. If the link is up, the link pings the host instead. If the host does not answer in 5 seconds, the link dials again. If the host waits for a Tailscale SSH sign-in, the link dials every few seconds for two minutes. A dial in progress continues.

ParamTypeRequiredDefaultDescription
hoststringA host by name from the [hosts] config table.
Result fieldTypeDescription
hoststringThe host.
statusstringThe link state when the call was made.
approval_urlstringThe Tailscale sign-in page, when the link waits for one and has it. Omitted otherwise.
approval_refusedboolTrue when the link waits for a sign-in and the banner named an address that is not a Tailscale login origin. Omitted otherwise.
{"id":1,"verb":"retry-host","params":{"host":"build"}}

run-task-verify Added in v0.13.1

Run a board's verify command in the worktree of a pane here, for the card's owner. Only over a link.

ParamTypeRequiredDefaultDescription
windowstringyesThe pane.
commandstringThe shell line.
probeboolfalseOnly say if the pane is here.
timeout_msint600000The limit.
Result fieldTypeDescription
hereboolWith probe: the pane is here.
exitintThe exit status.
notestringWhy it did not end.
tailstringThe end of the output.
{"id":1,"verb":"run-task-verify","params":{"window":"a1b2c3d4","command":"go test ./...","timeout_ms":600000}}

set-agent-quiet Added in v0.13.1

Mark a window quiet, or clear the mark. A quiet window opens no finished, question or errored item in the Inbox, and its open items of those kinds close. A pane that calls this leaves an open question open. Its agent state and agent-state events do not change, and an approval or a login still reaches the person. The window must run an agent. Needs the admin grant.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
quietbooltrueTrue marks the window quiet, and false clears the mark. Clearing it opens no old item, except a question the pane waits on now.
Result fieldTypeDescription
sessionstringThe session that holds the window.
window_idstringThe window that was marked.
quietboolWhether the window is now quiet.
closedintHow many open Inbox items this call closed.
{"id":1,"verb":"set-agent-quiet","params":{"session":"work","window":"build"}}
{"id":1,"verb":"set-agent-quiet","params":{"session":"work","window":"build","quiet":false}}

set-buffer Added in v0.9.0

Store content in a paste buffer and put it on top. With no name a new buffer is made, append or not, as tmux does; a name makes the buffer a named one. Empty content stores nothing and is no error. When the buffers tuios named pass the limit, the oldest of them go; past the byte cap the oldest go whatever their name. A set from outside every pane, or from a pane with admin, makes the person's buffer; a set from a pane without admin makes that pane's own. From a pane this needs the write grant, and a pane without admin may set only its own buffers, or make a new one with no name.

ParamTypeRequiredDefaultDescription
datastringThe content as text. Give data or data_b64. It may not be empty or larger than the byte cap.
data_b64stringThe content as base64, for any bytes. It wins over data.
uploadstringAn id that sends the content in parts, each in its own call on one connection. The buffer is set once, when the part without more arrives.
moreboolfalseMore parts of this upload follow.
namestringThe buffer to set: 1 to 64 printable characters. Omit for a new buffer.
appendboolfalseAdd the text to the end of the buffer instead of replacing it.
Result fieldTypeDescription
namestringThe buffer's name: bufferN for one tuios named, or the name set-buffer gave it.
bytesintHow many bytes the buffer holds.
createdintUnix-nano time the content was last set.
versionintA number that changes each time the content is set. Pass it back as version to act only on this content.
automaticboolTrue when tuios named the buffer.
samplestringThe start of the content on one line, with control characters and bytes that are not UTF-8 shown as escapes. It never cuts a character. Print it as it is.
panestringThe pane that owns the buffer, by its window name, or its short id once it is gone. Absent for the person's buffers.
storedboolFalse when the content was empty and nothing was stored. The other fields are then absent.
{"id":1,"verb":"set-buffer","params":{"data":"make test"}}
{"id":1,"verb":"set-buffer","params":{"name":"deploy","data":"kubectl rollout restart deploy/api"}}

set-fan-verdict Added in v0.11.0

Record a judge's pick among the attempts of a fan: the attempt it recommends, the verdict, its reasons and notes on each attempt. Only the judge pane judge-fan started for the fan, or a call from outside every pane, records one: a pane of an attempt is refused. The daemon records which of the two it was as by. It is written on every attempt, and compare-fan and the agents view show it. A later call replaces it. Nothing is kept or removed: keep-fan does that.

ParamTypeRequiredDefaultDescription
sessionstringyesAny session of the fan.
pickstringyesThe session of the attempt the judge recommends.
summarystringyesThe verdict in a sentence or two, at most 400 bytes.
reasons[]stringThe reasons, one sentence each, at most 6.
notesobjectNotes per attempt: session name to a list of sentences, at most 4 each.
Result fieldTypeDescription
groupstringThe fan's group.
pickstringThe attempt picked.
bystringjudge for the judge's pane, you for a call from outside every pane.
attempts[]stringEvery attempt the verdict was written on.
{"id":1,"verb":"set-fan-verdict","params":{"session":"api-fan-retry","pick":"api-fan-retry-2","summary":"Keep B. It is the smallest change and passes the tests.","reasons":["A reads hits without the lock."],"notes":{"api-fan-retry":["Adds a test for eviction."]}}}

set-keep-awake Added in v0.13.1

Set [daemon] keep_awake: off, on (while the daemon runs) or agents (while an agent pane on this machine works). It applies at once and is saved to config.toml, so the settings page, the file and every client show one value.

ParamTypeRequiredDefaultDescription
modestringyesThe new mode. One of off, agents or on.
Result fieldTypeDescription
modestring[daemon] keep_awake in force.
heldboolTrue while the daemon holds the machine awake.
workingintAgent panes that work now on this machine.
methodstringHow the hold is made.
errorstringWhy the machine could not be held awake. Absent when nothing failed.
savedboolTrue when config.toml now holds the mode.
save_errorstringWhy config.toml could not be written. The mode applies until the daemon stops.
{"id":1,"verb":"set-keep-awake","params":{"mode":"agents"}}

set-note Added in v0.12.0

Set the return note of a session, or of one pane with window: one short line that says what it is for or what comes next. Every client shows it, the dock shows it when a person comes back to the session, and it survives a reattach and a daemon restart.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name for a pane's note. Omit for the session's note.
notestringThe note. Newlines and tabs become spaces, other control characters are dropped, and it is cut to 200 bytes. Omit or pass an empty string to clear it.
Result fieldTypeDescription
typestringAlways note_set.
sessionstringThe session's name.
windowstringThe id of the pane the note is on, empty for the session's note.
notestringThe note as stored, empty when cleared.
{"id":1,"verb":"set-note","params":{"session":"work","note":"next: run the migration"}}
{"id":1,"verb":"set-note","params":{"session":"work","window":"build","note":""}}

set-session-order Added in v0.12.0

Put the sessions in an order. Every client lists them in it: the rail, go-to, tuios ls. It survives a daemon restart. A session the list leaves out, and one made later, goes after the named ones in creation order.

ParamTypeRequiredDefaultDescription
order[]stringyesSession names in their new order. Every name must be a live session, or nothing changes. Repeats are dropped.
skip_missingboolLeave out a name that is no live session, rather than refusing the order. The result lists them as missing.
Result fieldTypeDescription
typestringAlways session_order_set.
order[]stringEvery session's name, in the order the daemon lists them now.
missing[]stringWith skip_missing, the names that were no live session. Omitted when there were none.
{"id":1,"verb":"set-session-order","params":{"order":["work"]}}

set-task-dispatch Added in v0.13.1

Change task dispatch. mode sets a board to manual, pull or auto: in pull, an agent that finishes its card is given the board's next open card, as mail from tuios; in auto, the daemon starts the board's preset agent for each open card, in a new worktree, and mails it the card. preset sets that agent; auto needs one. cap bounds the agents at once. verify sets the command run in a card's worktree when its agent is done: a pass moves the card to review, a fail to todo. pause stops all dispatch at once, and any pane may pause. resume lifts the pause and every stop. quiet sets the hours when dispatch gives no card. A pane needs admin for every action but pause, and verify is refused from every pane. Refused over a link.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
projectstringThe project board, by origin URL. Omit for the session's own cards.
actionstringyesWhat to change. One of mode, pause, resume, quiet, preset, cap or verify.
modestringWith mode: the board's new mode. One of manual, pull or auto.
quietstringWith quiet: a span of local time such as 22:00-07:00, or off.
agentstringWith preset or mode auto: the agent auto starts. A card's own agent comes first.
modelstringWith preset: as start-agent takes it.
effortstringWith preset: as start-agent takes it.
permission_modestringWith preset: as start-agent takes it. Omit for the agent's own default.
machinestringWith preset: here (the default), any, or a linked machine.
capintWith cap: agents at once in total, 0 for 3.
machine_capintWith cap: on one machine, 0 for 2.
verifystringWith verify: a shell line, or off.
verify_timeoutintWith verify: seconds, 0 for 600.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
Result fieldTypeDescription
pausedboolTrue while dispatch is paused.
paused_bystringWho paused it.
stoppedstringWhy all dispatch stopped on its own, such as usage limit. Empty when it did not.
quietstringThe quiet hours, local time, such as 22:00-07:00.
quiet_nowboolTrue inside the quiet hours.
boards[]objectThe boards with a mode or a stop: board, project or session, mode, failures (dispatched cards in a row that did not finish), stopped, verify and verify_timeout.
capintAuto's agents at once, in total.
machine_capintAuto's agents at once on one machine.
runningintAuto's agents now.
boardobjectThe board the call named, also when it is manual. An auto board adds preset, running, waiting and note.
{"id":1,"verb":"set-task-dispatch","params":{"action":"mode","mode":"pull","project":"git@github.com:acme/api.git"}}
{"id":1,"verb":"set-task-dispatch","params":{"action":"pause"}}

show-buffer Added in v0.9.0

Return the content of one paste buffer. A buffer can hold any bytes: data_b64 carries them all, and data carries them as text. From a pane this needs the read grant, and reaches only the buffers of the sessions the pane may read.

ParamTypeRequiredDefaultDescription
namestringThe buffer to show. Omit for the newest buffer tuios named, as tmux does: for the person, the newest of the person's own, and for a pane without admin, the newest of its own.
versionintAct only while the buffer holds the content of this version, as list-buffers or show-buffer gave it. Otherwise the call answers no_buffer.
encodingstringbase64 to get data_b64 alone, without the text in data. One of base64.
Result fieldTypeDescription
namestringThe buffer's name: bufferN for one tuios named, or the name set-buffer gave it.
bytesintHow many bytes the buffer holds.
createdintUnix-nano time the content was last set.
versionintA number that changes each time the content is set. Pass it back as version to act only on this content.
automaticboolTrue when tuios named the buffer.
samplestringThe start of the content on one line, with control characters and bytes that are not UTF-8 shown as escapes. It never cuts a character. Print it as it is.
panestringThe pane that owns the buffer, by its window name, or its short id once it is gone. Absent for the person's buffers.
datastringThe whole content as text. A byte that is not UTF-8 reads as U+FFFD here.
data_b64stringThe whole content, every byte, as base64.
{"id":1,"verb":"show-buffer"}
{"id":1,"verb":"show-buffer","params":{"name":"buffer3"}}

speed-test Added in v0.9.3

The far end of a link speed test. ping answers at once. sink takes bytes after the reply and drops them, then answers one line {bytes, ms}. source sends bytes of random data after the reply, then closes.

The connection stays open after the reply when mode is sink or source.

ParamTypeRequiredDefaultDescription
modestringyesping, sink or source. One of ping, sink or source.
bytesintHow many bytes sink takes or source sends, at most 1 GiB.
Result fieldTypeDescription
modestringThe mode.
{"id":1,"verb":"speed-test","params":{"mode":"ping"}}

stop-recording Added in v0.13.1

Stop a pane's recording. Answers once the file is closed.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
Result fieldTypeDescription
pathstringThe file written.
windowstringThe id of the pane recorded.
eventsintHow many events the file holds, the snapshot included.
bytesintThe size of the file.
secondsfloatThe time of the last event.
reasonstringWhy the recording ended: stopped here, or what ended it first.
started_atstringWhen the recording started, RFC 3339 in UTC.
{"id":1,"verb":"stop-recording","params":{"session":"work","window":"build"}}

swap-window Added in v0.13.1

Swap two tiled panes of one workspace. Works with no client attached. The focus stays where it is.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringOne pane. Omit for the caller's own pane, or outside a pane the focused one.
withstringyesThe other pane.
Result fieldTypeDescription
window_idstringId of the first pane.
withstringId of the other pane.
{"id":1,"verb":"swap-window","params":{"session":"work","window":"build","with":"review"}}

tml-close Added in v0.11.0

Close a TML surface and its window. A tml-open that waits on it answers with the value.

ParamTypeRequiredDefaultDescription
surfacestringThe surface id tml-open answered with.
valueanyA JSON value for the waiting caller. Omit for null.
Result fieldTypeDescription
surfacestringThe surface that closed.
{"id":1,"verb":"tml-close","params":{"surface":"tml-4f1a9c02","value":"done"}}

tml-get Added in v0.11.0

Read a TML surface: its tree as TML JSON, its state and its version.

ParamTypeRequiredDefaultDescription
surfacestringThe surface id.
Result fieldTypeDescription
docobjectThe tree as TML JSON, with the state it was opened with.
stateobjectThe state now.
versionintThe version: it counts every change of the tree or the state.
window_idstringThe window the surface is drawn in.
titlestringThe surface's title.
ownerstringWho opened it: a pane, or tuios tml show.
{"id":1,"verb":"tml-get","params":{"surface":"tml-4f1a9c02"}}

tml-input Added in v0.11.0

Report what the person did on a TML surface: the state its local actions changed, and a close. The attached client sends it, with its attach nonce.

ParamTypeRequiredDefaultDescription
surfacestringThe surface id.
human_noncestringThe attach nonce of the person's client.
ops[]objectA JSON Patch (RFC 6902) on the surface's state.
closeboolfalseClose the surface.
valueanyWith close: the value. Omit when the person dismissed the surface.
events[]objectThe emit actions the person ran, each {name, value}. Each becomes a tml-event for the owner.
actions[]objectThe pane() actions the person ran, each {verb, params}: focus, new-window or send-text. Each runs with the grants of the pane that opened the surface, never the person's.
viewobjectThe client's view state, as loom keeps it: open tabs, cursor rows, scroll places, sorts, filters and folds, without typed text. capture-pane draws the surface with the last view reported.
Result fieldTypeDescription
versionintThe surface's version after the change.
actions[]objectEach pane() action's result: verb, ok, and error and code when it was refused.
{"id":1,"verb":"tml-input","params":{"surface":"tml-4f1a9c02","human_nonce":"...","ops":[{"op":"replace","path":"/tab","value":"log"}]}}

tml-list Added in v0.11.0

List the open TML surfaces of a session.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
Result fieldTypeDescription
surfaces[]objectEach surface: surface, window_id, title, owner and version.
{"id":1,"verb":"tml-list","params":{"session":"work"}}

tml-open Added in v0.11.0

Show a TML document as a popup or a pane. Every attached client draws it, and the daemon keeps it while nobody is attached.

The connection stays open after the reply when events is true.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
docstringThe document: TML text or TML JSON as a string, or a TML JSON object. It is checked as tml-validate checks it, and a document with errors is refused with invalid_tml and the problem list.
targetstringpopupWhere to show it: popup, a floating box over the panes that needs an attached client, or pane, a tiled pane. One of popup or pane.
namestringName for the window. Omit to use the document's title.
widthstring80%Popup width, in cells ("60") or as a share of the pane region ("60%"). Popup only.
heightstring60%Popup height, in cells ("20") or as a share of the pane region ("50%"). Popup only.
workspaceintWorkspace to open it on. Omit for the current one.
waitboolfalseKeep the call open until the surface closes, and return the close value in a tml_result.
timeoutint0With wait: milliseconds to wait before failing with the timeout code. The surface stays open. 0 waits as long as it is open.
eventsboolfalseKeep the connection and stream the surface's tml-event events on it after the answer, as subscribe does: each emit, and the close as the last one. Not with wait.
Result fieldTypeDescription
surfacestringId of the surface. Use it to patch, replace, read or close the surface.
seqintWith events: the last event number when the stream went live, as subscribe answers.
boot_idstringWith events: the daemon start that numbers the events.
window_idstringId of the window the surface is drawn in.
targetstringpopup or pane.
workspaceintWorkspace the surface was opened on.
valueanyWith wait: the value the surface closed with. null when the person dismissed it.
reasonstringWith wait: closed when the person ran a close action, so the value is the person's answer; program when a tml-close gave the value; dismissed when the window closed without one.
{"id":1,"verb":"tml-open","params":{"session":"work","doc":"<tml version=\"1\" title=\"Hi\"><text>Hello</text></tml>"}}
{"id":1,"verb":"tml-open","params":{"doc":{"type":"tml","version":1,"title":"Build","children":[{"type":"progress","value":0.4}]},"target":"pane"}}
{"id":1,"verb":"tml-open","params":{"doc":"<tml version=\"1\"><button key=\"y\" on-press=\"close('yes')\">Yes</button></tml>","wait":true}}

tml-patch Added in v0.11.0

Change a TML surface's state with a JSON Patch (RFC 6902). Only the parts of the surface that read the changed paths are drawn again.

ParamTypeRequiredDefaultDescription
surfacestringThe surface id tml-open answered with.
ops[]objectyesThe JSON Patch: add, remove, replace, move, copy and test operations on the state. A test that does not match refuses the whole patch, so read the state again with tml-get.
Result fieldTypeDescription
versionintThe surface's version after the patch.
changed[]stringThe JSON Pointers the patch changed.
{"id":1,"verb":"tml-patch","params":{"surface":"tml-4f1a9c02","ops":[{"op":"replace","path":"/failed","value":0}]}}

tml-place Added in v0.11.0

Move a TML surface between a popup and a tiled pane, as the person chose. The surface keeps its state, so a form keeps what the person typed. Needs the attach nonce of a client.

ParamTypeRequiredDefaultDescription
surfacestringThe surface id.
targetstringpopup or pane. One of popup or pane.
human_noncestringThe attach nonce of the client the person uses.
Result fieldTypeDescription
window_idstringThe surface's window.
targetstringWhere the surface is now.
{"id":1,"verb":"tml-place","params":{"surface":"tml-4f1a9c02","target":"pane","human_nonce":"..."}}

tml-replace Added in v0.11.0

Swap a TML surface's tree. Each client keeps its view state (the open tab, the cursor row) for the nodes whose ids stay.

ParamTypeRequiredDefaultDescription
surfacestringThe surface id.
docstringThe new document, as tml-open takes it.
keep_stateboolfalseKeep the state the surface has now instead of the new document's state.
Result fieldTypeDescription
versionintThe surface's version after the swap.
{"id":1,"verb":"tml-replace","params":{"surface":"tml-4f1a9c02","doc":"<tml version=\"1\"><text>Done</text></tml>"}}

tml-validate Added in v0.11.0

Check a TML document as tml-open would. Needs no session.

ParamTypeRequiredDefaultDescription
docstringThe document: TML text or TML JSON as a string, or a TML JSON object.
Result fieldTypeDescription
warnings[]objectThe warnings, each with at, code and message. A document with errors fails with invalid_tml instead.
{"id":1,"verb":"tml-validate","params":{"doc":"<tml version=\"1\"><text>Hello</text></tml>"}}

transfer-answer Added in v0.9.3

Answer a copy in state conflict: what to do with files that are there and differ. Answer one file, several, or every file with all. The copy goes on when every file it waits on has an answer.

ParamTypeRequiredDefaultDescription
idstringyesThe transfer's id.
choicestringyesreplace the file there, keep both (the copy gets a new name), or skip the file. One of replace, keep-both or skip.
relstringThe file, as the row's conflicts name it.
rels[]stringSeveral files.
allboolThis answer for every file of the copy, now and later.
Result fieldTypeDescription
idstringThe transfer's id.
statestringqueued, running, verifying, waiting (for a machine that went away), paused, conflict (waits for transfer-answer), done, failed or cancelled. One of queued, running, verifying, waiting, paused, conflict, done, failed or cancelled.
sizeintBytes to copy in all.
doneintBytes copied, or found to be there already.
wireintBytes that crossed a link, fewer than done when they were compressed.
ratefloatBytes per second over the last five seconds.
eta_msintTime left, once two seconds of data came.
resumed_fromintWhere the copy went on from after a machine came back. Absent when it never had to.
verifiedboolThe copy's sha256 matched the original's.
finalstringWhere the file is now, which keep-both can change.
sameintFiles that were there with the same bytes, which were not copied again.
conflicts_skippedintFiles that were there and differed, left as they were.
conflicts[]objectIn state conflict: the files that wait for an answer, rel, path, src_size, src_mtime, dst_size, dst_mtime.
errorstringWhat happened and what to do, for failed and waiting.
{"id":1,"verb":"transfer-answer","params":{"id":"3f9a1c2b7d00","choice":"keep-both","all":true}}

transfer-cancel Added in v0.9.3

Stop a transfer and remove what it copied so far of the file in flight.

ParamTypeRequiredDefaultDescription
idstringyesThe transfer's id.
Result fieldTypeDescription
idstringThe transfer's id.
statestringqueued, running, verifying, waiting (for a machine that went away), paused, conflict (waits for transfer-answer), done, failed or cancelled. One of queued, running, verifying, waiting, paused, conflict, done, failed or cancelled.
sizeintBytes to copy in all.
doneintBytes copied, or found to be there already.
wireintBytes that crossed a link, fewer than done when they were compressed.
ratefloatBytes per second over the last five seconds.
eta_msintTime left, once two seconds of data came.
resumed_fromintWhere the copy went on from after a machine came back. Absent when it never had to.
verifiedboolThe copy's sha256 matched the original's.
finalstringWhere the file is now, which keep-both can change.
sameintFiles that were there with the same bytes, which were not copied again.
conflicts_skippedintFiles that were there and differed, left as they were.
conflicts[]objectIn state conflict: the files that wait for an answer, rel, path, src_size, src_mtime, dst_size, dst_mtime.
errorstringWhat happened and what to do, for failed and waiting.
{"id":1,"verb":"transfer-cancel","params":{"id":"3f9a1c2b7d00"}}

transfer-clear Added in v0.9.3

Remove the transfers that ended (done, failed, cancelled) from the list. A failed one takes its parts with it.

ParamTypeRequiredDefaultDescription
ids[]stringOnly these transfers. Omit for every one that ended.
Result fieldTypeDescription
clearedintHow many left the list.
{"id":1,"verb":"transfer-clear"}

transfer-resume Added in v0.9.3

Go on with a paused transfer, try a waiting one now, or try a failed one again from where it stopped.

ParamTypeRequiredDefaultDescription
idstringyesThe transfer's id.
Result fieldTypeDescription
idstringThe transfer's id.
statestringqueued, running, verifying, waiting (for a machine that went away), paused, conflict (waits for transfer-answer), done, failed or cancelled. One of queued, running, verifying, waiting, paused, conflict, done, failed or cancelled.
sizeintBytes to copy in all.
doneintBytes copied, or found to be there already.
wireintBytes that crossed a link, fewer than done when they were compressed.
ratefloatBytes per second over the last five seconds.
eta_msintTime left, once two seconds of data came.
resumed_fromintWhere the copy went on from after a machine came back. Absent when it never had to.
verifiedboolThe copy's sha256 matched the original's.
finalstringWhere the file is now, which keep-both can change.
sameintFiles that were there with the same bytes, which were not copied again.
conflicts_skippedintFiles that were there and differed, left as they were.
conflicts[]objectIn state conflict: the files that wait for an answer, rel, path, src_size, src_mtime, dst_size, dst_mtime.
errorstringWhat happened and what to do, for failed and waiting.
{"id":1,"verb":"transfer-resume","params":{"id":"3f9a1c2b7d00"}}

wait-dir Added in v0.8.5

Wait until the names in a directory on this machine change: a file added, removed or renamed. The daemon that owns a window on another machine asks it, so the rail's file section can follow that machine's disk. It answers changed false when the timeout ends first.

ParamTypeRequiredDefaultDescription
dirstringThe directory to watch.
timeoutintMilliseconds to wait. Omit for 30 seconds.
afterstringThe names value of the last answer. When the names differ from it, the wait answers at once with changed true.
Result fieldTypeDescription
dirstringThe directory watched.
changedboolThe names changed before the timeout ended.
namesstringA short sum of the names in the directory, empty when they cannot be read or there are more than 100000.
{"id":1,"verb":"wait-dir","params":{"dir":"/tmp","timeout":1}}

zoom-window Added in v0.13.1

Zoom a pane to fill its workspace, or end the zoom. Works with no client attached. Zooming a pane on the workspace the session shows focuses it.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow to zoom. Omit for the caller's own pane, or outside a pane the focused one.
zoomboolTrue to zoom, false to end the zoom on the window's workspace. Omit to toggle.
Result fieldTypeDescription
window_idstringId of the window.
zoomedboolWhether the window is zoomed now.
changedboolFalse when the zoom was already as asked.
{"id":1,"verb":"zoom-window","params":{"session":"work","window":"build","zoom":true}}

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

agent-message-receipts Added in v0.13.1agent-preset Added in v0.13.1agent-readiness Added in v0.13.1clear-history Added in v0.11.0close-pane Added in v0.8.0daemon-upgrade Added in v0.13.1delegate Added in v0.13.1delete-buffer Added in v0.9.0drop-files Added in v0.9.3exec Added in v0.13.1file-abort Added in v0.9.3file-check Added in v0.9.3get-keep-awake Added in v0.13.1get-note Added in v0.12.0host-speed-test Added in v0.9.3judge-fan Added in v0.11.0link-peer Added in v0.8.0list-buffers Added in v0.9.0list-push Added in v0.9.3list-recordings Added in v0.13.1list-routes Added in v0.12.1mark-recording Added in v0.13.1open-pane Added in v0.8.0open-tree-stream Added in v0.9.3pane-agent Added in v0.8.0pane-calls Added in v0.8.0pane-cwd Added in v0.8.0pane-kitty-medium Added in v0.11.0paste-buffer Added in v0.9.0paste-pane-image Added in v0.8.3place-agent Added in v0.13.1plugin-cell Added in v0.13.1plugin-notify Added in v0.13.1rail-pane Added in v0.12.0read-dir Added in v0.8.0record-pane Added in v0.13.1remove-push Added in v0.9.3report-program-status Added in v0.13.1resize-pane Added in v0.8.0resize-window Added in v0.13.1retry-host Added in v0.9.0run-task-verify Added in v0.13.1set-agent-quiet Added in v0.13.1set-buffer Added in v0.9.0set-fan-verdict Added in v0.11.0set-keep-awake Added in v0.13.1set-note Added in v0.12.0set-session-order Added in v0.12.0set-task-dispatch Added in v0.13.1show-buffer Added in v0.9.0speed-test Added in v0.9.3stop-recording Added in v0.13.1swap-window Added in v0.13.1tml-close Added in v0.11.0tml-get Added in v0.11.0tml-input Added in v0.11.0tml-list Added in v0.11.0tml-open Added in v0.11.0tml-patch Added in v0.11.0tml-place Added in v0.11.0tml-replace Added in v0.11.0tml-validate Added in v0.11.0transfer-answer Added in v0.9.3transfer-cancel Added in v0.9.3transfer-clear Added in v0.9.3transfer-resume Added in v0.9.3wait-dir Added in v0.8.5zoom-window Added in v0.13.1