CLI Reference

Remote Control Commands (part 2 of 2)

Remote Control Commands (part 2 of 2): part of the CLI Reference of TUIOS.

This page is one part of docs/CLI_REFERENCE.md of the tuios repository. The CLI Reference page lists every part.

tuios list-attention Added in v0.8.0

List the Inbox: every approval and question an agent is blocked on, mail to you, errored agents, conversations a daemon restart left to resume, and finished turns nobody has looked at, in every session on the daemon and on every linked host it streams. Rows are grouped Approvals, Questions (an agent's own and those put with ask-human), Mail, Errored, Resume, Done, oldest first, with how long each has waited, its id, its session and pane, and what it said. The TUI's Inbox (prefix i) is the same list. A row of another machine names it, build:api/claude, and a row of a machine whose link is down ends in [unreachable, seen 5m ago]: it is what that machine said last.

An item closes by itself when what opened it stops being true. Dismissing one is for the person at an attached client and is done from the Inbox; there is no command for it, because a command run from a pane is exactly what must not be able to clear the person's queue. Snoozing, marking unread and undo are the person's acts too and have no command either. --snoozed lists the items the person snoozed, after the rest under a Snoozed heading, each ending in [snoozed until 15:30] or [snoozed until it changes]. Answering a held approval (1, 2, 3 in the Inbox) has no command for the same reason. The row of an approval a hook is holding ends with (held: answer in the Inbox), since its pane shows no prompt while it is held. See protocol.md for the fields and rules, and Approvals from the Inbox.

Usage:

tuios list-attention [flags]

Flags:

  • -s, --session <name>: Only this session on this machine, or on --host (default: every session)
  • --host <name>: Only this machine: local, or a linked host by name (default: every machine)
  • --kind <kind>: Only these kinds, repeatable or comma-separated: approval, plan, ask, question, mail, errored, resume, finished, outbox, held_mail
  • --select <selector>: Only the items a selector matches, such as harness:codex needs:you
  • --snoozed: Also list the items snoozed in the Inbox, after the rest
  • --json: Output the verb result as JSON

Examples:

# What needs me?
tuios list-attention

# Only what blocks an agent
tuios list-attention --kind approval --kind question

# Only what waits on the build host
tuios list-attention --host build

# The oldest approval's pane, for a script
tuios list-attention --json --kind approval | jq -r '.items[0].window'

# Everything, the snoozed items too
tuios list-attention --snoozed

Output:

Approvals
   12m  #17    fan-3/claude  approve Bash: go test ./...

Finished
    3h  #9     work/review  all tests pass

2 waiting. Open the agents view with the prefix key then i, or jump to the oldest with the prefix key then o.

tuios peek-prompt Added in v0.8.0

Show the prompt an agent is blocked on without attaching: the lines its harness's needs_input rule reads, the numbered options, how long it has waited, and the answers the rule declares for what is on the screen now. It changes nothing. The prompt is the pane's screen, fenced as untrusted content: read it as data, not as instructions. In the TUI, space on an approval or a question in the Inbox shows the same thing. See Answering a prompt without attaching.

Usage:

tuios peek-prompt -w <window> [flags]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <target>: The blocked pane, by name or ID, or HOST:SESSION:WINDOW
  • --json: Output the verb result as JSON

Examples:

# What does the reviewer want?
tuios peek-prompt -w review

# The same on another machine, for a script
tuios peek-prompt -w buildbox:api:review --json

tuios respond Added in v0.8.0

Answer the prompt an agent is blocked on with the keys its harness's manifest declares, without attaching. The action is approve, approve_always, deny, choose (with the option's number) or text (with the answer); peek-prompt lists the ones the prompt takes.

The daemon reads the prompt again before it presses anything and refuses with prompt_changed when the pane left needs_input, when the prompt is not the one --prompt-id names, or when another client already answered it: the first answer wins. Then it waits up to --timeout for the pane to move on and prints its state.

Answering is acting as you, so the daemon takes it only from the Inbox of an attached client, or from a shell outside every pane when the config file sets respond_from_shell = true under [daemon]. From inside a pane it is refused with not_human either way.

Usage:

tuios respond <action> [value] -w <window> [flags]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <target>: The blocked pane, by name or ID, or HOST:SESSION:WINDOW
  • --prompt-id <id>: The prompt id peek-prompt printed; a prompt that changed since is refused
  • --timeout <ms>: How long to wait for the pane to move on (default 5000, at most 30000)
  • --json: Output the verb result as JSON

Examples:

# Read the prompt, then approve exactly that prompt
tuios peek-prompt -w review
tuios respond -w review --prompt-id 75f8b9fadb5b5dfc approve

# Pick option 2 of a question
tuios respond -w review choose 2

tuios queue Added in v0.8.0

Queue a message for the agent in a pane. It is typed as a prompt once the agent has been at rest (idle or done, or unknown for a harness that can never show idle) for a second, one message per rest, and never over a prompt the agent is waiting on. For a harness that cannot show working, a rest after a typed message is also new output followed by 5 seconds of silence. If the agent is at rest now, it is typed right away. The daemon then waits for the agent to show it took the message, the way fan waits for its first prompt. A message the agent shows no sign of taking is marked stalled, is never typed again, and opens a question in the Inbox; it holds the messages behind it until the agent next works, shows on its screen that it took it, or you drop it, and the next message is then typed at the next rest. A message also waits while you type into the pane, and while the agent's input box holds your draft. See Queued messages.

A pane holds at most [agents.queue] max messages (8 by default) of at most 16 KiB each. A reply from the Inbox with a long paste can carry more, as a file the daemon writes when it types the reply (see queue-prompt in protocol.md). The queue lives in the daemon's memory, so a daemon restart drops it, and so do the pane closing and the agent leaving the pane. From inside a pane the message is checked like send-text when it is queued, and against the pane's grants again when it is typed. See Queued messages.

Usage:

tuios queue [flags] TEXT...
tuios queue ls [-w <window>] [flags]
tuios queue rm ID | --all -w <window> [flags]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <target>: The agent's pane, by name or ID, or HOST:SESSION:WINDOW (default: the focused pane; for ls, every pane of the session)
  • --all (rm): Drop every message queued for the pane that you may drop
  • --json: Output the verb result as JSON

The words of TEXT are joined with spaces. To queue a message that reads ls or rm, put -- before it. ls prints one line per message: its id, state (waiting, delivering or stalled), who queued it (human from the Inbox, shell from outside every pane, a pane's id, or link:HOST), its age, the pane, and the message's first line. rm from inside a pane drops only what that pane queued, and from a shell every message but the ones you queued from the Inbox, which only the attached client can drop.

Examples:

# Reply to the agent in the build pane once it finishes its turn
tuios queue -w build 'make the backoff jitter configurable'

# What waits, and drop one message
tuios queue ls
tuios queue rm q3

# Everything queued for one pane
tuios queue rm --all -w build

tuios task Added in v0.12.0

Hand out a session's work as task cards. A card is one unit of work: a title, the prompt for the pane that takes it, a stage, and the pane that holds it. The daemon keeps the cards with the session, so they outlive the pane that added them. After a daemon restart they come back with every holder let go. A card is also let go when its pane closes or its agent leaves the pane. See Task verbs.

The stages are todo, plan, doing, verify, review, shipped and done. claim moves a card in todo or plan to doing, and done moves it to done and lets it go.

tuios also moves a card when it records a fact about the card's work, unless [tasks] auto_stage = false (CONFIGURATION.md):

FactFromTo
A plan held for approval on the pane that holds the cardtodo, doingplan
The plan approved from the Inboxplandoing
tuios fan verify starting in the card's fan (fan --task)doingverify
Every attempt's check ended and none passedverifydoing
A pull request on the branch opened (cards held in the worktree's session, or in its fan)plan, doing, verifyreview
The pull request mergedplan, doing, verify, reviewshipped
The pull request closed without a mergereviewdoing

A move fires only from its stages, so a card put in another stage by hand stays there. A blocked card and a done card never move on their own, and done is always set by hand. The history entry is by tuios and names the fact.

A plan is held only when [agents.approvals] holds plans for the harness and the pane is not in front of you, so a plan you answer in the pane moves no card. A plan kept planning, or a hold that times out, leaves the card in plan until its pull request opens: the pull request is proof enough that the plan went through. A pull request moves every card held in the worktree's session, so a second pane there holding an unrelated card moves with the branch. With a fan, each attempt's pull request reaches the card: one closing without a merge moves it back to doing while another may still be open.

Usage:

tuios task add [-p PROMPT] [--stage STAGE] [--project URL] [--machine any|HOST] TITLE... [flags]
tuios task ls [--stage STAGE] [--open] [--all-sessions | --project URL [--hosts]] [flags]
tuios task get ID [flags]
tuios task claim ID | --next [-w <window>] [flags]
tuios task done ID [flags]
tuios task stage ID STAGE [flags]
tuios task block ID REASON... | --clear [flags]
tuios task release ID [flags]
tuios task rm ID [flags]
tuios task attach ID FILE... [--name N] [--note TEXT] [--replace] [flags]
tuios task attach ID --link URL [--name N] [--note TEXT] [flags]
tuios task attach ID --screenshot -w PANE | --capture -w PANE [--scrollback] [--lines N] [flags]
tuios task attachments ID [flags]
tuios task detach ID NAME [flags]
tuios task attachment get ID NAME -o FILE|- [flags]
tuios task dispatch [status | pause | resume | mode manual|pull|auto | preset | cap N | quiet SPAN|off | verify COMMAND|off] [--project URL] [flags]

Flags:

  • -s, --session <name>: Session of the cards (default: this pane's session, else the most recently active)
  • -p, --prompt <text> (add): What the pane that takes the card is to do, at most 16 KiB; - reads it from standard input
  • --stage <stage> (add, ls): The stage it starts in; for ls, only the cards in it
  • --open (ls): Leave out the cards that are done
  • --all-sessions (ls): List the cards of every session on this machine, with a SESSION column first. Takes no --session
  • --project <url> (add, ls): The repository the card is for, by its origin URL, or . for the repository of the current folder. For ls, list that repository's cards from every session, with HOST and SESSION columns. Takes no --session. Two spellings of one URL (git@host:a/b.git, https://host/a/b) name one project; a local path is refused
  • --machine <m> (add): Where the card's agent starts: any for the machine with the most room, this one or a linked one (Any machine), or one linked machine's name. Omit it for this machine. The capture sheet's Machine pill sets it
  • --hosts (ls): With --project, also list the project's cards on each linked machine. A machine that does not answer is named under the table
  • --next (claim): Take the oldest card no pane holds that is not blocked or done, and that no fan of another session works on
  • -w, --window <target> (claim): The pane that takes the card (default: this pane; required outside a pane)
  • --clear (block): Lift the block
  • --name <name> (attach): The name the card shows (default: the file's name; PR #N for a pull request link, else the link's host and path). One file only
  • --note <text> (attach): A line about the attachment. One file only
  • --link <url> (attach): Attach an http or https address instead of a file. A GitHub pull request's address is kind pr
  • --replace (attach): Put it in the place of the attachment with the same name. Without it a name in use with other content is refused; the same file again is left as it is, so a retry succeeds
  • --screenshot, --capture (attach): Have the daemon take a PNG, or the text, of the pane -w names in the card's session, and attach it as screenshot NAME.png or capture NAME.txt. From a pane this needs the read grant
  • --scrollback, --lines <n> (attach): With --screenshot or --capture, take the history above the screen too, at most n lines (--capture keeps 2000 by default)
  • -o, --output <file> (attachment get): Where to save it, or - for standard output. An existing file is not written over
  • --verify-timeout <seconds> (dispatch verify): The verify command's time limit, at most 3600 (default 600)
  • --json: Output the verb result as JSON

The words of TITLE and REASON are joined with spaces. ls prints one line per card: its id, stage (with ! when it is blocked), the pane that holds it, its age, and its title. claim prints the card's id and title on its first line, so a script can read the id with cut -d' ' -f1; with nothing to take it fails with no_task, and a card another pane holds fails with task_held.

attach puts files or a link on a card, so the board shows them beside it. Several files go in one change, one entry in the card's history: a screenshot, a log, a diff, a Markdown note, a Mermaid diagram, the pull request. The command reads each file and sends its bytes; the daemon stores them once by their sha256 under its state folder and keeps them until the card is removed or they are detached, also after a restart. The kind (image, markdown, mermaid, diff, text, link, pr, file) is read from the content, then the name. task get lists them under Attachments, and attachment get --json on a pull request link adds its state, title and checks, read through your gh at most once a minute. On a project card another machine owns, -s HOST:SESSION from the pane that holds it passes the attach on, at most 3 MiB. A pane attaches to the card it holds, and to the card it finished while that card waits in verify or review. The limits are [tasks] attachment_max_mib, attachments_per_card and attachment_session_mib (CONFIGURATION.md).

A card with a project shows on that repository's board in every session and on every linked machine. The machine where it was added owns it. A pane on another machine claims, releases and finishes it with -s HOST:SESSION: its own daemon passes the call over the link, and the owner records the holder as that pane on the link's peer. The card is let go on the owner when the pane closes or its agent leaves. If the link is down then, the card stays held until tuios task release frees it on either machine. A retried claim by the pane that holds the card succeeds, so a claim whose answer was lost to a dropped link can be run again. A card without a project stays on its machine.

From inside a pane, changing a card needs the task grant. A pane claims only for itself and finishes, stages, blocks or releases only the card it holds, unless it holds admin. rm from a pane needs admin.

add also takes --harness ID, the agent the card is for, and --ask-first, which keeps the card for a person to start.

done from the pane that holds the card is its agent saying the work is done: the card is let go and goes on to review, or to verify when the board has a verify command. tuios runs that command (dispatch verify) in the pane's worktree, on the pane's machine, as sh -c COMMAND, never in a pane, with a time limit (--verify-timeout, default 600 seconds) that ends the command and every process it started, and keeps only the end of its output. A pass moves the card to review. A fail (an exit other than 0, the time limit, a worktree that is gone) sends it back to todo with its attempts one higher and the last line of the output as its note; get shows the end of the output. A verify that cannot reach the pane's machine leaves the card in verify and says why; stage ID verify runs it again, and lets go of a pane that holds the card, since the card now waits on the command. A card moved out of verify by hand stops its run. An agent that errors while it holds a card dispatch gave it keeps the card, blocked, with its attempts one higher and its last message as the note, since the agent may go on; no second agent is started for it. The block lifts when the agent works again, and the card goes back to todo once it is let go (the agent leaves, its pane closes, or release). A merged pull request moves the card to shipped; done from you, a shell outside the panes, or a pane that holds admin closes it. With [tasks] auto_stage = false, or [tasks] stages without review, an agent's done closes the card as before. The verify command is refused from every pane, and so is a move to review or shipped by a pane while the board has one.

dispatch shows and changes how cards go to agents. A board is a project's cards (--project) or a session's own cards. In manual mode, the default, a person starts each card. In pull mode, an agent that finishes its card with tuios task done is given the board's next open card: the oldest card in todo, plan or doing that no pane holds, that is not blocked, not --ask-first, and names no harness or the agent's own. The claim is made in one state change of the session, so two agents that finish at once take two cards. The agent hears of it as mail from tuios, which names the card, its prompt and the command that finishes it. An agent that only ends its turn (its agent state goes to done, as each Claude Code Stop does) keeps its card and gets no new one: a turn can end on a question or part way. A card leaves doing only by tuios task done, a stage move, a release, or its verify. Dispatch types nothing into a pane, and gives no card to a pane that waits for the person. In v1 the agent and the card are on one machine and in one session.

In auto mode tuios starts an agent for each open card in todo or plan that no pane holds, is not blocked and is not --ask-first, oldest first. Each gets a new worktree on a branch named from its title (task/fix-the-retry; -2 and on when that branch, its folder or its session exists, so your own branch is never checked out), on the machine --machine names: here (the default), any (picked as Any machine picks), or a linked machine. A card's own --machine and --harness come first. The agent holds the card from the start and gets it as mail from tuios; nothing is typed into its pane. At most cap agents run at once (default 3), and --machine-cap on one machine (default 2); each machine's [tasks] machine_cap still holds. Cards over a cap wait, and the status says how many. A card in doing is never started by auto: one let go mid-work (its pane closed, a restart) waits for you, so a restart never starts a second agent. Auto needs a preset: mode auto --agent claude [--model M] [--effort E] [--permission-mode P], or preset with the same flags. With no --permission-mode the agent runs in its own default mode; auto never turns approvals off unless you name such a mode. A start that fails counts toward the 3 failures in a row, and auto closes what it opened for it: the agent's pane, its session and its worktree (one with changes or commits is kept; the branch is kept). A preset whose agent no machine has stops the board at once. If a far machine goes down, its card stays held until tuios task release frees it.

The safety switches: pause stops all dispatch at once, and any pane may pause. quiet 22:00-07:00 gives no card in those hours, local time (off clears it). A board stops after 3 dispatched cards in a row end without being finished (let go or blocked; a card blocked on its errored agent counts when it is let go). All dispatch stops when an agent reports a usage limit (the state limit_reached, which tuios set-agent-state errored --kind usage_limit also reports, or an errored message that says "usage limit"). resume lifts the pause and every stop. On a pull board an offer that a switch held is made when the switch lifts: on resume, when quiet hours end or change, and when a board is set to pull, each agent at rest (idle or done) that holds no card is offered the next one. So is a card that comes free: added, let go, moved back to todo or plan, or unblocked. Such an offer never gives a pane the card it let go itself. From inside a pane, every action but pause needs admin, and verify is refused. A dispatched card counts as finished when its verify passes (or when it reaches review with no verify command), and as a failure when its verify fails. The settings are saved, so they survive a restart.

Examples:

# A conductor adds the work
tuios task add -p 'Read api/retry.go and add a jitter option, with a test.' make the backoff jitter configurable

# A worker pane takes the next card, and finishes it
tuios task claim --next
tuios task done t1

# Stuck on something, then free again
tuios task block t1 waiting on the staging key
tuios task block t1 --clear

# What is open
tuios task ls --open

# A card for the repository, and every machine's cards of it
tuios task add --project . add retries to the client
tuios task ls --project . --hosts

# A worker on this machine takes a card that build owns
tuios task claim t3 -s build:api
tuios task done t3 -s build:api

# Agents that finish take the next card of this repository; stop it all at once
tuios task dispatch mode pull --project .
tuios task dispatch pause

# An agent for each open card, at most 4 at once and 2 on one machine
tuios task dispatch mode auto --agent claude --effort high --project .
tuios task dispatch cap 4 --machine-cap 2

# Run the tests on each card its agent is done with
tuios task dispatch verify "go test ./..." --verify-timeout 900 --project .

tuios review Added in v0.8.0

Show what the agent in a pane changed, leave notes on its lines, and send the notes to the agent. The diff is the pane's worktree against the base it was made from, or for a plain repository against the merge base with its upstream branch, else only what is not committed. Committed and uncommitted work show together, untracked files included and ignored files left out. An untracked file larger than [agents.checkpoints] max_untracked_mb (50 by default) is listed as not read, with no counts. It is read by the daemon through a temporary git index, so the repository, its index and its files are not changed. See Reviewing an agent's changes.

Usage:

tuios review [SESSION] [-w <window>] [--base <ref> | --against <session> | --uncommitted] [--stat] [--path <path>]... [--context <n>] [--json]
tuios review note [-w <window>] FILE:LINE TEXT... [--side old]
tuios review note [-w <window>] --hunk '<header>' FILE TEXT...
tuios review note --edit ID TEXT... | --remove ID
tuios review notes [-w <window>] [--clear] [--json]
tuios review send [-w <window>] [--id ID]... [--now] [--json]

Flags:

  • -s, --session <name>: Target session, also accepted as the argument (default: this pane's, else the most recently active)
  • -w, --window <target>: The pane, by name or ID (default: the focused pane)
  • --base <ref>: Diff against this branch, tag or commit, through its merge base with HEAD
  • --against <session>: Diff against another attempt of the same fan
  • --uncommitted: Only what is not committed yet
  • --stat: The list of changed files with their counts, without the diff
  • --path <path>: Only this path, relative to the repository root. Repeatable
  • --context <n>: Lines of context around each change, 0 to 20 (default 3)
  • --side old (note): LINE is a removed line, numbered as in the base
  • --hunk <header> (note): The note is on the whole hunk with this header
  • --edit <id>, --remove <id> (note): Change or drop a note
  • --clear (notes): Remove every note you may remove
  • --id <id> (send): Send only this note, sent before or not. Repeatable
  • --now (send): Send only if the agent is at rest with nothing queued; never queue
  • --json: Output the verb result as JSON

tuios review prints a heading, one line per changed file (its status A, M, D, R, or U for untracked, and its counts), then each file's hunks with both line numbers and the notes under the lines they are on. A diff stops at 400 files, 2 MiB of text or 5000 lines in one file; files past that show their counts only.

A note keeps its line's text and follows it when the file changes; one whose line is gone is marked outdated. review notes lists each note's id, place, author (human, shell, a pane, or link:HOST), state and text. From inside a pane only the notes that pane wrote can be edited or removed; from a shell, any but the ones left from the attached client.

review send sends the unsent notes as one message through the delivery queue (tuios queue): typed when the agent is at rest, never over a prompt. The message says who sent it: "a script" from a shell, the pane from inside one, and "the person" only from the attached client. A note written by someone else says who wrote it. A note whose author may not type into the pane now, or whose pane is gone, is withheld and listed after the summary. From inside a pane, notes can be added only on a pane you could type into.

The review commands work on this machine's sessions. A HOST:SESSION or HOST:SESSION:WINDOW target is refused: attach to that machine and review there, or bring the work here with tuios worktree pull and review that.

Examples:

# What the agent in the focused pane changed
tuios review

# A fan attempt against its base, or against another attempt
tuios review api-fan-retry-2
tuios review api-fan-retry-2 --against api-fan-retry

# Leave two notes and send them
tuios review note -s api-fan-retry-2 api/retry.go:42 'log the attempt number here too'
tuios review note -s api-fan-retry-2 --hunk '@@ -88,4 +100,6 @@' api/retry.go 'wrap with context'
tuios review send -s api-fan-retry-2

tuios checkpoint Added in v0.9.0

List, read and restore the checkpoints of an agent's turns. The daemon saves a pane's git work tree each time its agent finishes a turn that changed a file. The index, HEAD, the branch and the stash do not change. See Turn checkpoints.

Usage:

tuios checkpoint list [-s <session>] [-w <window>] [--json]
tuios checkpoint diff [N] [-s <session>] [-w <window>] [--stat] [--path <path>]... [--context <n>] [--json]
tuios checkpoint restore N [-s <session>] [-w <window>] [--force] [--json]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <target>: The pane, by name or ID (default: the focused pane)
  • --stat (diff): The list of changed files with their counts, without the diff
  • --path <path> (diff): Only this path, relative to the repository root. Repeatable
  • --context <n> (diff): Lines of context around each change, 0 to 20 (default 3)
  • --force (restore): Restore while the agent is working or waiting on a prompt
  • --json: Output the verb result as JSON

checkpoint list prints one row per checkpoint: its number, the turn, the agent state, the time, the commit and the label. checkpoint diff N shows what turn N changed, against the checkpoint before it. Without N it shows the newest. checkpoint restore N saves the work tree as a safety checkpoint, then puts the files back as checkpoint N holds them. It prints the number of the safety checkpoint. Restore that number to undo the restore.

tuios ship Added in v0.9.0

Take an agent's work from its worktree to a merged change: commit it, merge the branch into its base, push the branch, and open a pull request. See Shipping a worktree.

Usage:

tuios ship commit [-s <session>] [-w <window>] [-m <message>] [--force] [--json]
tuios ship merge [-s <session>] [-w <window>] [--into <branch>] [--squash | --ff-only] [-m <message>] [--json]
tuios ship push [-s <session>] [-w <window>] [--remote <name>] [--yes] [--wait <duration>] [--request <id>] [--json]
tuios ship pr [-s <session>] [-w <window>] [--base <branch>] [--title <text> [--body <text>]] [--draft] [--remote <name>] [--yes] [--wait <duration>] [--request <id>] [--json]
tuios ship status [-s <session>] [-w <window>] [--refresh] [--json]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <target>: The pane, by name or ID (default: the pane this runs in, else the focused pane)
  • -m, --message <text> (commit): The commit message. The default is the pane's last prompt, or the line its last turn ended with
  • --force (commit): Commit while the agent is working or waiting on a prompt
  • --into <branch> (merge): The branch to merge into. The default is the base the worktree was made from
  • --squash, --ff-only (merge): Make one commit, or only fast-forward
  • -m, --message <text> (merge): The message of the merge or squash commit
  • --remote <name> (push, pr): The remote. The default is the one the branch follows, else the only one, else origin
  • -y, --yes (push, pr): Do not ask before sending
  • --wait <duration> (push, pr): How long to wait for your answer in the Inbox, when one is needed (default 2m)
  • --request <id> (push, pr): Wait again for the answer to a question an earlier call put in the Inbox
  • --base <branch> (pr): The branch the pull request merges into
  • --title <text>, --body <text>, --draft (pr): The pull request's title, body and draft state. Without --title, gh fills the title and body from the commits
  • --refresh (status): Ask gh now
  • --json: Output the verb result as JSON. A failure prints success, error, code and, for a conflict or a dirty checkout, files

Examples:

tuios ship commit -s api-feat-retry -m 'Add a retry to the client'
tuios ship merge -s api-feat-retry
tuios ship merge -s api-feat-retry --squash -m 'Add a retry to the client'
tuios ship pr -s api-feat-retry --draft
tuios ship status -s api-feat-retry --refresh

git runs in the daemon with your own environment: your name, email, signing setup and hooks. tuios sets no identity and adds no trailer. ship commit stages every change, untracked files included and ignored files not. When a hook or the signing program refuses the commit, the index goes back to what it was. A call from inside a pane runs git with no hooks, and with no program that only the repository's own config names.

ship merge merges into the main checkout. That checkout must have the target branch checked out and no uncommitted change to a tracked file. When the merge conflicts, it is undone with git reset --merge, and the command lists the files that conflict (code merge_conflict). Uncommitted changes in the worktree are not merged, and the command says how many there are.

ship push and ship pr send work off this machine. The first call shows what would be sent: the branch, its commit, the remote, the commits and the pull request. The command asks [y/N] at a terminal. Elsewhere it needs --yes. When the command runs inside a tuios pane, the person must also allow it in the Inbox. The question pops up on the client that shows the pane, and the command waits for the answer. A push is never forced. ship pr needs the gh CLI, installed and logged in (gh auth login). tuios holds no GitHub token.

The pull request and its checks show on the agent's row in the rail (PR #12 open pass), in tuios worktree ls, and in the pr field of ls --json and worktree ls --json. While a client is attached, the daemon reads each open pull request again every minute with gh pr view. With no open pull request, or no client, nothing is read.

fan keep <session> --merge merges the kept attempt the same way before it removes the others. --squash, --ff-only and --into choose how. When the merge is refused, no attempt is removed.

tuios set-agent-state Added in v0.8.0

Report a pane's agent state so the session can show which panes need attention.

Usage:

tuios set-agent-state <state> [flags]

States: none, working, needs_input, idle, done, errored, unknown

Flags:

  • -s, --session <name>: Target session (default: the pane's own session in a pane, else the most recently active)
  • -w, --window <id-or-name>: Target window (default: the pane this runs in, else the focused one)
  • -m, --message <text>: Short note reported with the state
  • --source <source>: Where the state came from: report, osc, screen, stall (default: report)
  • --harness <id>: Id of the harness the state is about, e.g. claude-code
  • --kind <kind>: What a needs_input state waits for: approval, question or auth. Only valid with needs_input
  • --agent-session-id <id>: The harness's own conversation id. Stored on the pane, and turns on the nested-session guard (below)
  • --transcript-path <path>: The transcript file the harness writes. For a harness whose manifest has a transcript reader, the pane is joined to this exact file
  • --if-state <states>: Apply only when the pane is in one of these comma-separated states

Hook fields: The last four flags are what tuios agent-hook sends, and each is sent only when set, so a call that uses none of them works against an older daemon. An older daemon ignores these fields rather than refusing them, so --if-state asks the daemon first and fails, sending nothing, when the daemon does not support it. --if-state is how "the tool ran after an approval" moves a pane from needs_input back to working without also turning a done pane back to working. A report with --agent-session-id is refused while the pane's own agent is working or needs_input by its own report and the report names a different session, or a different harness: that is a nested run, such as a claude -p a tool call started inside the pane. At rest a different session takes the pane over, as /clear or a restart should. tuios agent-hook also sends the harness's pid, which lets a new session from the same harness process take the pane over mid-turn, as /clear after an interrupted turn does. This command has no flag for it, so a report from here with a different --agent-session-id is refused mid-turn.

Sources and precedence: More than one source can have an opinion about the same pane. Each source is ranked, and a source may write over a claim ranked at or below its own and never over one ranked above it. A source updating its own claim is the same-rank case and is always allowed.

SourceRankWhat it is
reporthighestThe harness, or its hook shim, calling for itself
oscAn escape sequence the pane emitted
screenA rule matched against the pane's rendered text
stalllowestThe output-stall heuristic

There is one exception, for the case ranking alone gets wrong: a screen rule that matched a blocking prompt may write over a higher-ranked claim that has gone stale, meaning the pane has painted since that claim was stamped and the claim has stood unrefreshed for two seconds. The displaced claim is put back the moment a later look finds the prompt gone. It applies only to the daemon's own screen tier, which has actually read the pane; passing --source screen here never overrides anything. See Agent state.

report is the default, so a caller written before sources existed keeps its authority. A report the daemon declines prints to stderr and leaves the state alone:

Not applied: a higher-ranked source owns this pane. It still reports working.

The other refusals name their own reason on that line: an --if-state that did not hold, or a nested run from another conversation or another harness.

Examples:

# Mark the focused pane as working
tuios set-agent-state working

# Mark a specific pane as needing input, with a note
tuios set-agent-state needs_input -w build -m "awaiting approval"

# Say the block is an approval, for a named conversation
tuios set-agent-state needs_input --kind approval --agent-session-id 5f1c -m "approve Bash: make"

# Clear a block after the tool ran, and leave any other state alone
tuios set-agent-state working --if-state needs_input

# Report on behalf of a named harness, from an escape sequence
tuios set-agent-state working --source osc --harness claude-code

# Clear a pane's agent state
tuios set-agent-state none

tuios set-agent-meta Added in v0.8.0

Record short facts about the agent in a pane, such as its model, how full its context is, or a one-line summary of the task. The rail draws them on the second line of the agent's row. They are display only: they never change the agent state, a wait, an alert or a message.

Usage:

tuios set-agent-meta [key=value ...] [flags]

Each argument is key=value, and key= removes the key. A key is 1 to 24 lower-case letters, digits, _ or -, starting with a letter. A value has its control characters replaced and is cut to 80 characters; the keys that were cut are named on stderr. One call sets at most 16 keys, and a pane holds at most 32. Keys keep the position they first arrived in, so an update does not reorder the row. The metadata clears when the agent leaves the pane.

A call that repeats the values the pane already holds changes nothing and sends nothing to attached clients, and renews a TTL only once less than half of it is left, so a feed may write on every tick. The keys now, prompt and subagents are written by tuios from what the harness hooks report, and are refused here; see tuios agent-log.

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <id-or-name>: Target window (default: focused)
  • --source <name>: Who is writing, so --clear removes only this writer's keys
  • --ttl <duration>: Drop the keys this call sets after this long, at most 24h (default: keep until removed)
  • --clear: Remove every key this source wrote (every key with no --source) first. The keys tuios writes, now, prompt and subagents, stay
  • --json: Print the result

Examples:

# From a statusline or hook: the model and context use, for a minute
tuios set-agent-meta -w "$TUIOS_PANE_ID" --source statusline --ttl 60s model=opus context=42%

# Remove one key
tuios set-agent-meta summary=

# Remove every key this source wrote
tuios set-agent-meta --source statusline --clear

With --json:

{
  "type": "agent_meta_set",
  "window_id": "3f2a9c1e",
  "meta": {"context": "42%", "model": "opus"},
  "truncated": []
}

tuios agent-log Added in v0.8.0

Show what the agent in a pane has been doing, from the activity ring the daemon keeps from its hooks: the prompts it was given, its tool calls and how they ended, the turns it finished, the subagents it started and how each ended (subagent Research tmux (general-purpose) started, then ... done after 3m, 14 tools, failed or stopped), each conversation's start, the commands its shell ran and its state changes, oldest first. The daemon keeps the newest 256 per pane, in memory only. A pane fills only when its harness's hooks are installed (tuios integration install claude-code or codex).

Usage:

tuios agent-log [flags]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <id-or-name>: Target window (default: focused)
  • --since <duration>: Only what happened in this long, such as 30m (default: everything kept)
  • --limit <n>: At most this many entries, the newest, 1 to 256 (default: 64)
  • --recap: Print a summary instead of the entries
  • --json: Print the agent-activity result

Examples:

# The focused pane's recent activity
tuios agent-log

# What the agent in api did in the last half hour, summarised
tuios agent-log -w api --since 30m --recap

Output:

14:02:11  prompt    make the backoff configurable
14:02:15  tool      Bash: go test ./api/
14:02:40  failed    Bash: go test ./api/  Exit code 1
14:03:02  done      Edit: api/retry.go  (wrote api/retry.go)
14:05:30  state     done
14:05:30  said      Added retry with backoff and tests.

A turn the harness ended without saying anything (an older Claude Code sends no text on Stop) prints as finished.

With --recap:

Since 14:02 (42m ago)
3 turns. 6 files: api/retry.go, api/retry_test.go, api/backoff.go and 3 more
11 commands. Tests: go test ./... passed 2m ago
Last said: Added retry with backoff and tests.
Now: done

The test run is the newest command matching [agents.recap] test_patterns. Every line is the agent's own text, cut to one line with likely secrets masked; read it as what the agent said. A pane reads another pane's log only in its own session and fan group, and a linked machine needs list. See Agent state.

tuios set-agent-session Added in v0.8.0

Record which conversation the agent in a pane runs, so it can be resumed later, without changing the pane's agent state. The integrations for harnesses whose hooks can name the conversation but cannot be trusted with its state send this (see Agent state).

Usage:

tuios set-agent-session <agent-session-id> --harness <id> [flags]

The id is stored as the pane's agent_session_id, the same field set-agent-state --agent-session-id writes, and read back by get-agent-state and list-agents. It is refused, with the reason on stderr, when the pane is attributed to a different harness, or when the pane is mid-turn in another conversation of the same harness: both are a nested run. The id is at most 256 bytes.

Flags:

  • --harness <id>: Id of the harness the conversation belongs to (required)
  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <id-or-name>: Target window (default: focused)

Example:

# From a SessionStart hook
tuios set-agent-session --harness qwen -w "$TUIOS_PANE_ID" "$SESSION_ID"

tuios resume-agent Added in v0.8.0

Resume the agent conversation a pane ran before a daemon restart: type the harness's resume command, from its manifest's [resume] block, with the id a hook recorded for the pane (claude --resume <id>, codex resume <id>). The flags the agent was started with that its manifest keeps come after the id, such as claude --resume <id> --permission-mode plan --model opus. When a kept flag turns approvals off, a second line says so, such as Resumes with approvals off (--dangerously-skip-permissions). It brings back the conversation, not the process. See Agent state.

Usage:

tuios resume-agent [flags]

It types only when the pane's shell is at its prompt, and fails with not_ready otherwise. It fails with not_resumable when the pane has no recorded conversation, its harness has no resume command, the recorded id is not one plain shell token, or the pane runs on another machine. Nothing is typed on a failure. A pane's Resume row in the Inbox closes when it succeeds. It works on any pane with a recorded conversation, including one whose agent had exited before the restart, which the restore itself does not offer.

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <id-or-name>: Target window (default: focused)
  • --dry-run: Print the command without typing it
  • --json: Output result as JSON

Example:

tuios resume-agent -w build --dry-run
# claude --resume 5f1c2b7e-9a3d-4c1e-8f00-1234567890ab

tuios resume-agent -w build
# Resumed claude-code conversation 5f1c2b7e-... in 3f2a9c1e: claude --resume 5f1c2b7e-...
{
  "success": true,
  "message": "command executed",
  "window_id": "3f2a9c1e-0000-4000-8000-000000000000",
  "harness": "claude-code",
  "agent_session_id": "5f1c2b7e",
  "argv": ["claude", "--resume", "5f1c2b7e"],
  "command": "claude --resume 5f1c2b7e",
  "typed": true
}

What a daemon restart does with these conversations is daemon.resume_agents: ask (default) opens a Resume row per pane in the Inbox, answered with y; auto types the command into each restored shell; off does neither.

tuios rename-session Added in v0.8.2

Rename a session.

The new name is what tuios ls shows and what attach and -s take. New panes get it as TUIOS_SESSION. Panes that already run keep the old name, and tuios commands from them still reach the session. Attach and kill-session by the old name fail and name the new one. The rename also clears a label set with tuios set-session-name. The name of a running or saved session is refused. A daemon older than this command answers that it does not know it. Run tuios restart-server.

With one argument, the session is the one given by -s, or else the session of the pane you run it in.

Usage:

tuios rename-session [session] <new-name> [flags]

Flags:

  • -s, --session <name>: Session to rename (default: the session of this pane)

Examples:

# Rename the session "test" to "work"
tuios rename-session test work

# Rename the session of this pane
tuios rename-session work

tuios set-session-name Added in v0.8.0

Set the label a session shows in the sidebar and the dock.

The session keeps its own name for addressing, persistence and TUIOS_SESSION, so a script that targets it by name keeps working. Pass no name to clear the label. To change the name itself, use tuios rename-session.

Usage:

tuios set-session-name [name] [flags]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)

Examples:

# Label the current session
tuios set-session-name "Payments API"

# Label a specific session
tuios set-session-name -s work "Payments API"

# Clear the label
tuios set-session-name

tuios set-session-accent Added in v0.8.0

Set the accent a session uses. It is shared by every client attached to the session and kept across a reattach. Pass no accent to clear it.

Usage:

tuios set-session-accent [accent] [flags]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)

Examples:

# Accent the current session
tuios set-session-accent cyan

# Accent a specific session
tuios set-session-accent -s work cyan

# Clear the accent
tuios set-session-accent

tuios note Added in v0.12.0

Set, read or clear the return note of a session or a pane. A note is one short line. It says what the session is for or what comes next. tuios shows it in the dock when you attach or switch to the session. The sidebar, the session switcher and the Inbox show it too.

The note is kept with the session. It survives a detach and a daemon restart. A note is at most 200 bytes. Newlines become spaces.

Usage:

tuios note set TEXT... [flags]
tuios note get [flags]
tuios note clear [flags]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • -w, --window <pane>: A pane by name or id, for the pane's note (default: the session's note)
  • --json: Output result as JSON

tuios note get prints the note, and prints nothing when there is none. tuios ls --json also gives each session's note.

Examples:

# Say what comes next before you stop
tuios note set next: run the migration

# Read it back
tuios note get

# A note on one pane
tuios note set -w build waiting for CI

# Remove the note
tuios note clear

tuios set-session-space Added in v0.10.0

File a session under a space, a named group of related sessions that tuios ls and the sidebar list together, under the space's name. A space is only a label on its sessions: it exists while at least one session is in it, and it survives a daemon restart with them. Pass no space to take the session out of any.

Surrounding whitespace is trimmed. A space name then follows the session name rules (no slash, backslash or control character) and is at most 64 bytes. A global session cannot be in a space.

--global marks the session global. A global session holds panes from more than one machine, and a new window in it asks which machine to use. The session leaves its space. --global=false takes the mark off. Use it for a session that lost the mark, or that was made without --global.

Usage:

tuios set-session-space [space] [flags]

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)
  • --global: Mark the session global. Use --global=false to take the mark off

Examples:

# File the current session under the space payments
tuios set-session-space payments

# File a specific session
tuios set-session-space -s work payments

# Take the session out of any space
tuios set-session-space

# Mark the session work global
tuios set-session-space -s work --global

# Take the global mark off and file the session under payments
tuios set-session-space -s work --global=false payments

tuios set-session-order Added in v0.12.0

Put the sessions in an order. Every client attached to the daemon lists them in it, at once: the sidebar, go-to and tuios ls. Moving a session up or down on the sidebar does the same. The order survives a daemon restart.

Every name must be a live session. A session you leave out, and one made later, goes after the named ones in creation order.

Usage:

tuios set-session-order <session>... [flags]

Examples:

# List work first, then notes, then everything else
tuios set-session-order work notes

tuios set-workspace-name Added in v0.8.0

Name a workspace so the dock and the sidebar show the label instead of the number. The number stays the workspace's identity. An unnamed workspace shows the name its active pane's program gave with OSC 1 (printf '\033]1;logs\007'), else its number. Pass no name to clear it.

Usage:

tuios set-workspace-name <workspace> [name] [flags]

Arguments:

  • workspace: Workspace number, 1-based
  • name: Label for the workspace. Omit to clear it.

Flags:

  • -s, --session <name>: Target session (default: this pane's session, else the most recently active)

Examples:

# Name workspace 2
tuios set-workspace-name 2 review

# Name a workspace in a specific session
tuios set-workspace-name -s work 2 review

# Clear the name
tuios set-workspace-name 2

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