Protocol Verbs

Files and worktrees

Files and worktrees: 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.

bundle-worktree Added in v0.8.0

Read a worktree session's work out in chunks so it can cross a link: its commits as a git bundle, then its uncommitted work as a binary patch. The first call makes the transfer and answers with its first chunk. Later calls pass the token and the next offset. tuios worktree pull is the caller.

ParamTypeRequiredDefaultDescription
sessionstringThe worktree session to read. Required on the first call. Never guessed.
fullboolfalseBundle the branch's whole history. Without it only the commits past the merge base with the worktree's base are carried, and the reader must have base_commit.
tokenstringThe transfer to read on, from the first call's reply. Only the connection that made a transfer can read it.
offsetint0Where to read from: the next of the previous reply.
releaseboolfalseWith token, end the transfer without reading the rest.
Result fieldTypeDescription
tokenstringThe transfer's token. It ends after its last chunk, on release, when this connection closes, or after ten minutes unread.
contentstringThis chunk, base64, at most 4 MB before encoding.
offsetintWhere this chunk starts.
nextintWhere the next chunk starts.
doneboolTrue on the last chunk, after which the token is gone.
repostringFirst call only: the repository's name.
origin_urlstringFirst call only: the repository's origin URL, empty when it has none.
branchstringFirst call only: the branch the worktree has checked out.
basestringFirst call only: the ref the worktree was made from, empty when it is not known.
base_commitstringFirst call only: the commit the bundle assumes the reader has, empty for a full bundle.
headstringFirst call only: the commit the branch is at.
fullboolFirst call only: true when the bundle carries the whole history.
bundle_bytesintFirst call only: how many bytes of the transfer are the bundle, zero when the branch has no commits past base_commit.
patch_bytesintFirst call only: how many bytes after the bundle are the patch, zero when nothing is uncommitted.
changesintFirst call only: how many paths the patch touches, untracked files included.
sizeintFirst call only: the transfer's whole length.
sha256stringFirst call only: the SHA-256 of the whole transfer, for the reader to check.
{"id":1,"verb":"bundle-worktree","params":{"session":"api-fan-add-retry-2"}}
{"id":2,"verb":"bundle-worktree","params":{"token":"<token>","offset":4194304}}

compare-fan Added in v0.8.0

Compare the attempts of a fan: one row per sibling session with its branch, agent, state, changed files and lines against the base (committed and uncommitted work, untracked files included), the last verify-fan check and the last command its shells finished. A sibling the caller could not name itself is left out.

ParamTypeRequiredDefaultDescription
sessionstringAny session of the fan. Omit for the most recently active session.
changesbooltrueCount the changed files and lines of each attempt, a few git calls per sibling.
detailboolfalseWith changes, also list each attempt's files (file_list, at most 8, most changed first) and its first changed lines (lines, at most 6). Two more git calls per sibling. From a linked machine, detail needs write in its policy.
Result fieldTypeDescription
groupstringThe fan's group.
repostringThe repository the fan is of.
repo_rootstringThe repository's main checkout.
basestringThe base the attempts were made from: the fan's base, or the main checkout's branch for a fan made from HEAD.
rows[]objectOne per sibling: session, branch, path, agent, harness, state, files, added, removed, ahead, dirty, base_sha, prompt_status, verify, last_command (cmdline, exit, at, window), gone, and note when git could not count. Also cost, the cost its agent reported, started_at and done_at, notes from the verdict, and file_list and lines with detail.
promptstringThe task the fan gave the attempts.
verdictobjectThe judge's pick, when set-fan-verdict recorded one: pick, summary, reasons, judge and at.
totalintHow many rows.
{"id":1,"verb":"compare-fan","params":{"session":"api-fan-retry-1"}}

fan Added in v0.8.0

Fan a prompt out across several agents. Creates count worktrees and sessions, starts an agent in each, and types each session's prompt into its agent once the agent shows it is at its prompt. Returns as soon as the sessions exist. An agent that is not ready for 30 seconds turns its prompt_status to held and raises a question in the Inbox; the prompt is still typed when it is ready.

ParamTypeRequiredDefaultDescription
countintHow many worktrees and agents, 1 to 16. Required unless prompts is given, which sets it.
agentstringThe agent to run in every session, as one string: a harness id or program name (claude, codex, gemini), or any program, with its arguments after it ("codex --model o5"). Words are split the way a shell splits them, quotes included, and exec'd directly; nothing is expanded. Required unless agents is given.
agents[]stringSeveral agents, each written as agent is, cycled across the sessions: ["claude","codex"] with count 4 is claude, codex, claude, codex. Takes no agent.
promptstringThe prompt every agent gets. It is typed as one paste (wrapped in bracketed paste when the agent has it on) and submitted with a carriage return, the way ask-agent types a question. Required unless prompts is given.
prompts[]stringOne prompt per session, in order. count defaults to how many there are and must equal it when given. Takes no prompt.
repostringA directory inside the repository. Required unless repo_url is passed.
basestringRef every branch starts from. Omit for HEAD of the main checkout.
namestringBranch stem, which names the fan. The branches are the stem, then stem-2, stem-3 and so on. A name that is already a fan in the repository is refused with fan_exists unless join is given. Omit for fan/ and the first words of the first prompt, which moves on to a free name. A name can have only A-Z, a-z, 0-9 and / . _ -. Any other character is refused.
joinstringA session of an existing fan to add the attempts to. The caller must reach that session. Omit to start a new fan.
ready_timeoutint600000Milliseconds to wait for each agent to be ready before giving up on its prompt.
envobjectEnvironment variables for every agent, name to value, on top of the daemon's. PATH in it is where the programs are looked up, so an agent the caller can run is found. The tuios CLI sends its PATH. TUIOS_ names, TMUX and TMUX_PANE are refused, and a call from another machine may not pass env at all. Not saved: a restored pane starts with the daemon's environment.
taskstringA task card the fan works on, such as t3. The card gets the fan's group and fan_id, and moves from todo or plan to doing. It keeps no holder, since the fan's attempts work on it, and claim-task next skips it while the fan has a session. A fan check and the attempts' pull requests then move it (see [tasks] auto_stage). The caller needs what claim-task needs, and the card must be held by no pane but the caller's, not blocked and not done, checked before anything is made.
task_sessionstringThe session of task. Omit for the caller's own session, or outside every pane the most recently active one.
human_noncestringWith task: the attached client's nonce, so the stamp is the person's (by human).
modelstringThe model for every agent, passed with the flag each harness's manifest names ([launch] model_flag). Refused when one of the agents takes no model flag.
effortstringThe effort for every agent, one of each harness's [launch] efforts.
permission_modestringThe permission mode for every agent, one of each harness's [launch] permissions. From an agent pane it is held to the caller's own mode.
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.
setupstringA shell line to run with sh -c in each new worktree, in a window named setup, before the agent or shell starts. It holds no grants. Omit for [worktree] setup in config.toml. An empty string runs none.
setup_asyncboolStart the agent at once beside the setup. Omit for [worktree] setup_async. Without it the agent waits for the setup to pass, and a failed setup removes the new worktree and the branch it made when nothing in them is anyone's work. A failed async setup keeps both.
repo_urlstringThe repository by its origin URL, for a caller on another machine. This daemon finds its own checkout whose origin is the same repository. Pass repo or repo_url, not both.
repos_rootstringWith repo_url, the directory on this machine to look under, and to clone into. Absolute, or starting with ~/. Omit to look under ~/src, ~/dev, ~/code, ~/projects, ~/repos, ~/git, ~/work, ~/go/src, the home directory itself and tuios's own clone directory.
cloneboolfalseWith repo_url, clone the repository when no checkout is found. Only https, ssh and git URLs are cloned.
Result fieldTypeDescription
groupstringThe branch stem, which is the group's name in list-worktrees.
repostringThe repository's name.
repo_rootstringThe repository's main checkout on this machine.
clonedboolTrue when the repository was cloned by this call. Absent otherwise.
agentstringThe harness id started in the first session, empty for a program no manifest recognises.
commandstringThe command started in the first session.
promptstringThe first session's prompt, as given.
sessions[]objectOne entry per session: session, branch, path, window_id, and the agent (harness id) and command started in it. hook_error is there when that session's after-new-worktree hook failed. setup is there when the session runs a setup, and agent_pending with no window_id while a sync setup holds the agent.
totalintHow many sessions were started.
taskobjectWith task: the card as stamped, as list-tasks gives a row.
task_notestringWith task: why nothing was stamped, when the card was removed while the fan was made.
{"id":1,"verb":"fan","params":{"count":3,"agent":"claude","prompt":"Add a retry to the client.","repo":"/src/api"}}
{"id":1,"verb":"fan","params":{"count":3,"agents":["claude","codex --model o5","gemini"],"prompt":"Add a retry to the client.","repo":"/src/api","env":{"PATH":"/usr/local/bin:/usr/bin:/bin"}}}

file-preview Added in v0.10.0

Make the preview of a file on this machine. An image comes scaled to max_px on its long side, a PDF page and a film frame as an image (with pdftoppm and ffmpeg there), text as its first 256 KiB, and anything else as its type and size.

ParamTypeRequiredDefaultDescription
pathstringyesThe file. An absolute path, or one that starts with ~.
max_pxint1600The longest side of an image, at most 4096.
pageint1The PDF page.
pages_knownboolfalseThe caller knows the page count, so pdfinfo does not run.
wordsboolfalseSend the PDF page's words from pdftotext in place of its picture.
at_msintThe position in a film of the frame to send. Without it the frame is 5 % in.
duration_knownboolfalseThe caller knows the film's facts, so ffprobe does not run.
no_frameboolfalseSend only the film's facts.
formatboolfalseLay out a JSON file for reading.
detailsboolfalseSend the file's permissions, what git says of it, its diff and a PDF page's words, in place of the preview.
offsetintSend a window of a text file from this byte, whole lines only, in place of the preview.
limitint262144The most bytes in that window, at most 1 MiB.
findstringLook for this text in a text file, in place of the preview. Lower case ignores case.
fromintThe byte find starts at.
backboolFind goes toward the start of the file.
lineintFind the start of this line number, in place of the preview.
Result fieldTypeDescription
kindstringimage, svg, pdf, video, text, dir or binary. One of image, svg, pdf, video, text, dir or binary.
imagestringThe picture, base64, as mime says: the image, the page or the frame.
mimestringThe picture's type for image, pdf and video, and the file's type otherwise.
widthintAn image's own width.
heightintAn image's own height.
textstringtext and svg: the content.
truncatedbooltext: the file is longer than what was sent.
offsetintA window: the byte it starts at. find and line: the start of the line found, or -1.
reachedintfind and line: how far the read went. Call again from there when the search ran out of time.
countedintline: the lines passed.
next_offsetintA window: the byte the next window starts at.
pdfstringpdf, when this machine cannot draw the page: the file, base64, at most 8 MiB.
pagesintpdf: the page count, when pdfinfo is there.
wordsstringpdf, when asked for: the page's words.
no_toolstringpdf: the tool this machine needs and does not have.
at_msintvideo: the position of the frame sent.
formattedbooltext: the JSON was laid out.
entriesarrayarchive: the listing, with name, size and dir.
cappedboolarchive: the listing stopped at a bound.
headstringbinary: the first 16 KiB, base64.
detailsboolThe reply holds the details asked for.
modestringdetails: the permissions.
ownerstringdetails: the file's owner.
groupstringdetails: the file's group.
gitstringdetails: what git says of the file.
diffstringdetails: the diff of a changed file.
video_codecstringvideo: the codec, from ffprobe.
audio_codecstringvideo: the codec of the sound, from ffprobe, when it has sound.
fpsnumbervideo: the frames each second, from ffprobe.
duration_msintvideo: the length.
notestringWhy there is no picture, in words a person can act on.
sizeintThe file's size.
mtimeintThe file's modification time, Unix ms.
{"id":1,"verb":"file-preview","params":{"path":"~/Pictures/cat.jpg","max_px":1200}}

keep-fan Added in v0.8.0

Keep one attempt of a fan and remove the others: each sibling's worktree and session go, the way remove-worktree removes them, each on its own. A sibling with uncommitted changes is left in place unless stash or force says what to do with them. Files git ignores are deleted with a worktree and never stashed: compare-fan with detail lists them. Branches are never deleted. With merge, the kept attempt's branch is first merged into its base, as ship-merge does.

ParamTypeRequiredDefaultDescription
sessionstringyesThe attempt to keep.
stashboolfalseStash a sibling's uncommitted changes before removing it.
forceboolfalseDiscard a sibling's uncommitted changes.
mergeboolfalseFirst merge the kept attempt's branch into its base in the main checkout, as ship-merge does. A merge that conflicts or is refused stops the call before any sibling is removed.
merge_modestringmergeWith merge: merge, squash or ff-only, as ship-merge takes mode. One of merge, squash or ff-only.
intostringWith merge: the branch to merge into. Omit for the base the attempt was made from.
groupstringThe fan's group, as compare-fan gave it. When given, a session of another fan is refused.
repo_rootstringThe fan's repository, as compare-fan gave it. When given, a session of another repository is refused.
fan_idstringThe fan's ID, as compare-fan gave it. When given, a session of another fan of the same name is refused.
siblings[]stringThe attempts the caller showed it would remove. When given, a fan whose other attempts differ is refused whole.
ignoredobjectPer attempt to remove, the ignored_hash compare-fan gave for the list the caller showed. When given, an attempt whose ignored files changed, or that has no entry, is refused, and nothing is removed.
Result fieldTypeDescription
keptstringThe session kept.
branchstringThe kept session's branch.
groupstringThe fan's group.
removed[]objectOne per sibling: session and removed, with remove-worktree's result when it was removed, or note and code when it was not.
leftintHow many siblings were not removed.
mergeobjectWith merge: what ship-merge returns for the kept attempt. Omitted without merge.
{"id":1,"verb":"keep-fan","params":{"session":"api-fan-retry-1"}}
{"id":1,"verb":"keep-fan","params":{"session":"api-fan-retry-1","stash":true}}
{"id":1,"verb":"keep-fan","params":{"session":"api-fan-retry-1","merge":true,"merge_mode":"squash"}}

list-worktrees Added in v0.8.0

List the sessions whose directory is a git worktree, with the repository, branch, agent state and fan prompt status of each.

ParamTypeRequiredDefaultDescription
repostringOnly worktrees of this repository, by name.
groupstringOnly the sessions of this fan-out, by its branch stem.
sessionstringOnly this session's worktree. The close dialog asks for the one it deletes, so the counts under changes run git there and nowhere else.
changesboolfalseRun git in the matching worktrees and report the count of uncommitted changes, the commits ahead of base, and whether the branch is merged. Off by default because it runs git.
Result fieldTypeDescription
worktrees[]objectOne entry per worktree session: session, repo, repo_root, branch, path, base, group, main (true when the entry is the repository's main checkout, which no worktree verb acts on), managed, gone, state, harness, windows, attached, prompt_status, prompt_note, launched_from (the session whose pane ran the fan, only when a pane did), pr (the branch's pull request as ship-status reports it, only when tuios knows of one), setup (the worktree setup's record, only when it ran one: command, async, state of pending, running, passed or failed, exit, started_at, finished_at, tail with the last four lines, agent of waiting, started or not_started, removed and branch_removed after a failed sync setup, and note), and with changes: changes, ahead, merged, and merged_into. merged is true when the branch has commits of its own and merging it into base, or into the upstream of base, changes nothing. A merge commit, a fast-forward, a rebase and a squash all count. merged_into names the ref, only when merged is true. No fetch is run, so a remote ref is as git last fetched it.
totalintHow many entries.
{"id":1,"verb":"list-worktrees"}
{"id":1,"verb":"list-worktrees","params":{"repo":"api","changes":true}}

new-worktree Added in v0.8.0

Create a git worktree of a repository and a session in it. The worktree goes under tuios's worktree directory, named by repository and branch. The branch is created from base when it does not exist.

ParamTypeRequiredDefaultDescription
repostringA directory inside the repository: its main checkout or any of its worktrees. Required unless repo_url is passed.
branchstringBranch to check out in the worktree. Created from base when it does not exist.
basestringRef a new branch starts from. Omit for HEAD of the main checkout.
namestringName for the session. Omit for <repo>-<branch>, with every slash in the branch turned into a hyphen.
command[]stringArgv to exec as the first window's process instead of a shell. No shell parses it, so nothing needs quoting.
new_branchboolRefuse with branch_exists when the branch, its worktree folder or its session exists already, instead of checking out a branch that exists.
promptstringA first prompt for the agent in command, typed once it is at its prompt, as start-agent and fan type theirs. The call waits for it to be taken, unless a sync setup holds the agent.
setupstringA shell line to run with sh -c in each new worktree, in a window named setup, before the agent or shell starts. It holds no grants. Omit for [worktree] setup in config.toml. An empty string runs none.
setup_asyncboolStart the agent at once beside the setup. Omit for [worktree] setup_async. Without it the agent waits for the setup to pass, and a failed setup removes the new worktree and the branch it made when nothing in them is anyone's work. A failed async setup keeps both.
repo_urlstringThe repository by its origin URL, for a caller on another machine. This daemon finds its own checkout whose origin is the same repository. Pass repo or repo_url, not both.
repos_rootstringWith repo_url, the directory on this machine to look under, and to clone into. Absolute, or starting with ~/. Omit to look under ~/src, ~/dev, ~/code, ~/projects, ~/repos, ~/git, ~/work, ~/go/src, the home directory itself and tuios's own clone directory.
cloneboolfalseWith repo_url, clone the repository when no checkout is found. Only https, ssh and git URLs are cloned.
Result fieldTypeDescription
sessionstringName of the new session.
session_idstringId of the new session.
repostringThe repository's name: the base name of its main checkout.
repo_rootstringThe repository's main checkout.
branchstringThe branch the worktree has checked out.
created_branchboolTrue when the branch was created by this call.
pathstringThe worktree's directory.
window_idstringId of the agent's or the shell's window. Absent while a sync setup holds it.
pty_idstringId of that window's PTY. Absent while a sync setup holds it.
clonedboolTrue when the repository was cloned by this call. Absent otherwise.
hook_errorstringWhy the after-new-worktree hook failed, with the last lines of its stderr. The worktree, the session and the first window are kept. Absent when the hook succeeded or none is set.
prompt_statusstringWith prompt: sent, stalled, not_sent, held, or pending while a sync setup holds the agent. list-worktrees reports it later too.
prompt_notestringWhy the prompt is not sent. Absent when it is.
setupobjectThe setup's record as list-worktrees reports it. Absent when no setup runs.
setup_window_idstringId of the setup's window. Absent when no setup runs.
setup_errorstringWhy the setup's window could not start. The worktree and the session are kept. Absent otherwise.
agent_pendingboolTrue while a sync setup holds the agent. There is then no window_id: the agent's window opens when the setup passes.
{"id":1,"verb":"new-worktree","params":{"repo":"/src/api","branch":"feat/retry"}}
{"id":1,"verb":"new-worktree","params":{"repo":"/src/api","branch":"feat/retry","base":"main","command":["claude"]}}
{"id":1,"verb":"new-worktree","params":{"repo_url":"git@github.com:acme/api.git","repos_root":"~/src","branch":"feat/retry"}}
{"id":1,"verb":"new-worktree","params":{"repo":"/src/api","branch":"feat/retry","command":["claude"],"prompt":"Add a retry to the client."}}

remove-worktree Added in v0.8.0

Remove a worktree session's worktree with git worktree remove, and kill the session. Uncommitted changes are refused unless stash keeps them in git stash or force discards them. The branch is never deleted.

ParamTypeRequiredDefaultDescription
sessionstringThe worktree session to remove. Never guessed.
stashboolfalseMove uncommitted changes into git stash before removing, under the message "tuios: <branch>".
forceboolfalseDiscard uncommitted changes. This is the one destructive option, and it does nothing without being passed.
keep_sessionboolfalseLeave the session running after the worktree is removed.
Result fieldTypeDescription
sessionstringThe session the worktree belonged to.
branchstringThe branch, which still exists.
pathstringThe directory that was removed.
changesintHow many uncommitted changes the worktree held.
stashedboolTrue when the changes went into git stash.
discardedboolTrue when the changes were discarded by force.
session_killedboolTrue when the session was killed.
branch_keptboolAlways true.
{"id":1,"verb":"remove-worktree","params":{"session":"api-feat-retry"}}
{"id":1,"verb":"remove-worktree","params":{"session":"api-feat-retry","stash":true}}

ship-commit Added in v0.9.0

Stage every change in a pane's git work tree, untracked files included and ignored ones not, and commit it on the branch checked out there. git runs with the person's own identity, signing and hooks, and the message is used as given. Refused while the pane's agent is working or waiting on a prompt, unless force is given.

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.
messagestringThe commit message. Omit to use the pane's last prompt or turn summary. The call is refused when there is none.
forceboolfalseCommit while the agent is mid-turn.
Result fieldTypeDescription
sessionstringThe session of the pane.
windowstringThe pane, by id.
worktreestringThe root of the work tree.
branchstringThe branch the commit is on.
commitstringThe new commit.
messagestringThe message the commit has.
{"id":1,"verb":"ship-commit","params":{"session":"work","window":"build","message":"Add a retry to the client"}}

ship-merge Added in v0.9.0

Merge a worktree pane's branch into its base branch in the repository's main checkout. The main checkout must have that branch checked out and no uncommitted change. A merge that conflicts is aborted, the main checkout is left as it was, and the conflicting files are reported. Uncommitted changes in the worktree are not merged. Nothing is forced.

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.
intostringThe branch to merge into. Omit for the base the worktree was made from, else the branch the main checkout is on.
modestringmergemerge fast-forwards when it can and makes a merge commit when it cannot. squash makes one commit. ff-only refuses a branch that cannot be fast-forwarded. One of merge, squash or ff-only.
messagestringThe message of the merge or squash commit. Omit for git's own.
Result fieldTypeDescription
sessionstringThe session of the worktree.
worktreestringThe root of the worktree.
repo_rootstringThe main checkout merged in.
branchstringThe branch merged.
intostringThe branch merged into.
modestringmerge, squash or ff-only.
beforestringThe commit into was on before.
afterstringThe commit into is on now.
commitsintHow many commits of the branch into did not have.
fast_forwardboolWhether into only moved forward.
up_to_dateboolWhether into already had every commit, so nothing changed.
uncommittedintHow many uncommitted changes the worktree holds, which the merge did not take.
{"id":1,"verb":"ship-merge","params":{"session":"work","window":"build"}}
{"id":1,"verb":"ship-merge","params":{"session":"work","window":"build","into":"main","mode":"squash"}}

ship-pr Added in v0.9.0

Push a pane's branch and open a pull request for it with the gh CLI, as the person is logged in to gh. tuios holds no GitHub token. When the branch already has an open pull request, the push updates it and no new one is opened. The first call answers confirm_required with what would happen and a token. Call again with that token. A caller inside a pane, or on a restricted connection, also needs the person to allow it in the Inbox.

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.
remotestringThe remote to push to. Omit for the one the branch follows, else the only one, else origin.
confirmstringThe token from the confirm_required answer to a call without it. The call goes ahead only with the token of what it would send now.
request_idstringCome back for the person's answer to a question an earlier call put in the Inbox.
waitint120000How long to wait for the person's answer in the Inbox, in milliseconds, at most 3600000.
basestringThe branch the pull request merges into. Omit for the base the worktree was made from, else the repository's default branch.
titlestringThe title. With title and body both omitted, gh fills them from the commits.
bodystringThe body. Needs title.
draftboolfalseOpen it as a draft.
Result fieldTypeDescription
sessionstringThe session of the pane.
windowstringThe pane, by id.
worktreestringThe root of the work tree.
branchstringThe branch pushed.
commitstringThe commit pushed.
remotestringThe remote pushed to.
createdboolWhether a new pull request was opened. False when one was already open.
probject or nullThe pull request: number, url, state (open, merged or closed), checks (pass, fail or pending, omitted when there are none), passed, failed, pending, branch and checked_at (Unix nanoseconds).
approved_bystringhuman when the person allowed it in the Inbox, omitted when the caller is the person.
{"id":1,"verb":"ship-pr","params":{"session":"work","window":"build","draft":true}}

ship-push Added in v0.9.0

Push a pane's branch to a remote and set it as the branch's upstream. Never forced. The first call answers confirm_required with what would be pushed and a token. Call again with that token to push. A caller inside a pane, or on a restricted connection, also needs the person to allow it in the Inbox, and the call waits for that answer.

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.
remotestringThe remote to push to. Omit for the one the branch follows, else the only one, else origin.
confirmstringThe token from the confirm_required answer to a call without it. The call goes ahead only with the token of what it would send now.
request_idstringCome back for the person's answer to a question an earlier call put in the Inbox.
waitint120000How long to wait for the person's answer in the Inbox, in milliseconds, at most 3600000.
Result fieldTypeDescription
sessionstringThe session of the pane.
windowstringThe pane, by id.
worktreestringThe root of the work tree.
branchstringThe branch pushed.
commitstringThe commit pushed.
remotestringThe remote pushed to.
urlstringWhere the push went: the push URL's host and path, without user name, password or token.
approved_bystringhuman when the person allowed it in the Inbox, omitted when the caller is the person.
{"id":1,"verb":"ship-push","params":{"session":"work","window":"build"}}

ship-status Added in v0.9.0

Read the pull request of a pane's branch as tuios last saw it, and with refresh ask gh now. A worktree session with an open pull request is polled in the background while a client is attached. Off when gh is not installed.

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.
refreshboolfalseAsk gh now instead of reading what tuios last saw.
Result fieldTypeDescription
sessionstringThe session of the pane.
windowstringThe pane, by id.
worktreestringThe root of the work tree.
branchstringThe branch checked out there, empty on a detached HEAD.
ghboolWhether the gh CLI is installed.
probject or nullThe pull request: number, url, state (open, merged or closed), checks (pass, fail or pending, omitted when there are none), passed, failed, pending, branch and checked_at (Unix nanoseconds). Null when tuios knows of none.
{"id":1,"verb":"ship-status","params":{"session":"work","window":"build"}}

stash-get Added in v0.8.0

Read one stashed file back as bytes, so it can cross a link. Only a path this session's stash printed is served, and a file over 8 MB is refused.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
pathstringA stored path, as stash-put or stash-list printed it.
Result fieldTypeDescription
pathstringThe stored path.
namestringThe stored file's base name.
hashstringThe sha256 of the content, hex.
bytesintHow many bytes the content holds.
media_typestringThe type read from the extension.
kindstringimage or file. One of image or file.
contentstringThe bytes, base64.
{"id":1,"verb":"stash-get","params":{"session":"work","path":"/run/user/1000/tuios/stash/<id>/<hash>.png"}}

stash-list Added in v0.8.0

List the files in a session's store, with the size of each, whether a message still names it, and how many the store has evicted. The oldest file no message names is the next one dropped when the session hits its cap.

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
dirstringThe directory holding this session's stored files.
entries[]objectOne entry per file, oldest use first: path, name, hash, bytes, media_type, kind, source, stored_at, referenced, missing.
totalintHow many files are stored.
bytesintHow many bytes they take together.
evictedintHow many files this store has deleted to make room since the session started.
max_file_bytesintThe per-file cap in bytes.
max_bytesintThe per-session cap in bytes.
{"id":1,"verb":"stash-list","params":{"session":"work"}}

stash-put Added in v0.8.0

Copy a file into the session's own file store and answer with the stored path. The stored file lives as long as the session and is deleted when the session is killed or the daemon stops. Attach the stored path to a message like any other path.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
pathstringAbsolute path to an existing regular file on the daemon's host. The daemon opens and copies it as the user that started it. With content, the daemon does not open it. It only names the stored file.
contentstringThe file's bytes, base64, for a file on another machine. At most 8 MB decoded. The path then gives the extension and the source label. From a linked machine, content is required.
Result fieldTypeDescription
pathstringThe stored path. Attach this, or hand it to another agent.
hashstringThe sha256 of the content, hex. The stored name is this plus the source's extension.
bytesintHow many bytes were stored.
media_typestringThe type read from the extension, the same way an attachment's is.
kindstringimage or file, from the media type. One of image or file.
stored_atintUnix-nano time the file was stored, or last asked for.
dedupedboolTrue when these bytes were already stored. Nothing new was written and the path is the one that already existed.
evictedintHow many files this put deleted to make room.
evictionsintHow many files this session's store has deleted in total. A number that moved means a file stashed earlier may be gone.
session_bytesintHow many bytes this session's store holds now.
session_entriesintHow many files this session's store holds now.
max_file_bytesintThe per-file cap in bytes.
max_bytesintThe per-session cap in bytes.
{"id":1,"verb":"stash-put","params":{"session":"work","path":"/tmp/flame.png"}}

verify-fan Added in v0.8.0

Run one check in every attempt of a fan: a window named verify in each sibling session runs the command with sh -c and records whether it passed. The window holds no grants, so the check cannot call tuios. It closes when the check passes and stays open, so the output can be read, when it fails. The command is always the caller's; none is read from the repository. A check still running in a sibling is stopped first.

ParamTypeRequiredDefaultDescription
sessionstringAny session of the fan. Omit for the most recently active session.
commandstringyesThe command to run, as a shell line, at most 4096 bytes.
timeout_msintHow long a check may run before it counts as failed and its window is closed, in milliseconds. Omit for no limit.
envobjectEnvironment variables for the check, name to value, on top of the daemon's, with the rules of fan's env. The tuios CLI sends its PATH. A call from another machine may not pass env.
Result fieldTypeDescription
groupstringThe fan's group.
commandstringThe command as it runs.
sessions[]stringThe sessions a check was started in. Results reach clients as the verify field of each session's worktree, and compare-fan reports them.
skipped[]objectSiblings no check was started in: session and reason. Omitted when none.
{"id":1,"verb":"verify-fan","params":{"session":"api-fan-retry-1","command":"go test ./..."}}

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