Daemon Mode (Session Persistence)
Daemon Mode (Session Persistence): 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.
Daemon Mode (Session Persistence)
TUIOS supports persistent sessions through a daemon process, similar to tmux or screen. Sessions continue running in the background even when you disconnect, allowing you to reattach later with all windows and content preserved.
tuios new
Create a new persistent session.
Usage:
tuios new [session-name] [flags]Flags:
--theme <name>: Set color theme for the session--ascii-only: Use ASCII characters instead of Nerd Font icons--show-keys: Enable showkeys overlay--no-animations: Disable UI animations-d, --detach: Create the session headless without attaching a client--host <name>: Create the session on this host from the[hosts]table--ssh: With--host, run ssh to the host and its own tuios instead of attaching here--global: Create a global session, which holds panes from more than one machine--hold: After a failure, wait for enter before the command exits--cwd <dir>: Directory the session's windows start in. The default is the current directory--space <name>: File the session under a space, a named group of related sessions. It follows the session name rules and is at most 64 bytes- The appearance flags of the root command (
tuios new --helplists them)
The session's windows start in the directory where you run tuios new.
--cwd names a different directory. The directory applies to the first
window, and to each later window that has no pane to take a directory from.
--cwd does not work with --host.
--space files the session under the space as it is made, so tuios ls and the sidebar list it with the space's other sessions. It does not work with --host, and with --global it is refused: a global session cannot be in a space. See tuios set-session-space.
Examples:
tuios new # Create session with auto-generated name
tuios new mysession # Create session named "mysession"
tuios new api --cwd ~/dev/api # Create a session whose windows start in ~/dev/api
tuios new work --theme dracula # Create session with Dracula theme
tuios new ci --detach # Create a headless session and return
tuios new api --space payments # Create a session in the space payments
tuios new --host build # Create a session on the host build and attach it
tuios new deploy --global # Create a global sessiontuios attach
Attach to an existing session.
Usage:
tuios attach [session-name] [flags]Flags:
-c, --create: Create session if it doesn't exist--host <name>: Attach to a session on this host from the[hosts]table--ssh: With--host, run ssh to the host and its own tuios instead of attaching here--hold: After a failure, wait for enter before the command exits--terminal-mode: Start in terminal mode, whateverstartup.start_in_terminal_modesays-d, --detach-others: Detach every other client of the session, astmux attach -ddoes- Same as
tuios new(theme, ascii-only, etc.)
Examples:
tuios attach # Attach to most recent session (or only session)
tuios attach mysession # Attach to session named "mysession"
tuios attach -d mysession # Attach and detach the other clients of mysession
tuios attach mysession -c # Attach or create if doesn't exist
tuios attach mysession --theme nord # Attach with different theme
tuios attach --host build api # Attach the session api on the host buildWhen the session already has a client, tuios attach says so and names the
window_size policy of the session. For example: "The session uses the size of
the client that last had input (window_size latest)." See
SESSIONS.md.
With -d, each other client of the session detaches as this client attaches.
The session continues to run. Each detached client exits with status 0 and
prints this message:
Another client attached to this session.
Detached from session 'mysession'.To do this on every attach, set single_client = true in [daemon]. See
CONFIGURATION.md. To detach clients without an attach,
use tuios detach-client.
With ssh_agent = "follow" in [daemon], tuios attach points the ssh
agent link of the session at the SSH_AUTH_SOCK of this client. See
tuios ssh-agent-path.
With display = "follow" in [daemon], the default, tuios attach sends the
display of this client. A daemon with no display of its own gives it to new
panes of the session. See tuios display-env.
Inside a tuios pane, tuios attach refuses to attach the session that holds
the pane. A bare tuios attach or tuios in a pane also refuses, because
it does not name a session. To show a different session in the pane, name
that session. To attach the same session, open a new terminal outside tuios.
To attach anyway, use --force or set TUIOS_ALLOW_NESTED=1.
To move the client that shows the pane to a different session, use
tuios switch-session.
The same refusal applies when the session would show itself through a chain. For example, session A shows session B in a pane, and a pane of B then attaches A.
tuios finds the pane in these ways:
- The client runs on the pane's terminal.
- The client's output reaches the pane. This finds
script, and ssh from the pane to the same machine or to the tuios SSH server. The attach does not wait for this check. If tuios finds it in the first 2 seconds after the attach, it detaches the client with the same message. - A client with no terminal runs under the pane's shell or has the pane's
TUIOS_variables.
A terminal window started from a pane attaches. Its output does not reach the pane.
tuios cannot find a client behind tmux or mosh in a pane. These redraw the screen and do not pass the output through. Such an attach goes through, and the session shrinks to 20x6. It stays at 20x6 until the inner client exits. A forced attach also stays at 20x6 or more.
tuios switch-session Added in v0.9.0
Switch an attached client to a different session, in place. This is what go-to does. Nothing is nested.
Usage:
tuios switch-session [HOST:]NAME [flags]Flags:
-s, --session <name>: Switch the client that shows this session--client <id>: Switch the client with this id, fromtuios list-clients-c, --create: Create the session if it does not exist--cwd <dir>: With--create, the directory the new session's windows start in--json: Output as JSON
The command switches one client:
- The client that
--clientnames. - Else the client that shows the session that
-snames. - Else, from a pane or a popup, the client that shows the session of the pane.
- Else the only client that is attached. With more than one client, name one.
HOST is a machine from the [hosts] table. Without HOST, the session is
on this machine. A session that --create makes has one window. When the
session exists, --create and --cwd do nothing, and the client switches to
it.
When the session is not arranged yet, [startup] applies to it, as on a first
attach. For example, startup.tiled = true tiles a session that
tuios new --detach made. A session that a person arranged keeps its layout.
From a pane, the command needs the admin grant.
Examples:
tuios switch-session api # From a pane: show the session api
tuios switch-session --create --cwd ~/dev/api api # Show api, and make it in ~/dev/api if it is missing
tuios switch-session build:api # Show the session api on the host build
tuios switch-session -s work api # From outside tuios: switch the client that shows workSee Sessionizer for a key that opens a project.
tuios ls
List all TUIOS sessions.
Usage:
tuios ls [flags]Flags:
--json: Output as JSON. Saved sessions carry"saved": true--all-hosts: Also list the sessions on every host in the[hosts]table. A host that does not answer gets a row saying so and never fails the command. Its sessions from when it last answered follow, under "As of ..., when it last answered", and are not counted in the total--host <name>: List the sessions on one host (localmeans this machine)
With no daemon running, tuios ls lists the sessions saved on disk instead,
marked saved, and exits 3.
Output: Shows a table with:
- Session name
- Number of windows
- Status (attached/detached)
- Creation time
- Last activity time
Example output:
╭───────────────┬─────────┬──────────┬───────────────┬─────────────────╮
│ NAME │ WINDOWS │ STATUS │ CREATED │ LAST ACTIVE │
├───────────────┼─────────┼──────────┼───────────────┼─────────────────┤
│ work │ 3 │ detached │ 2 hours ago │ 5 mins ago │
│ dev │ 2 │ attached │ 1 day ago │ just now │
╰───────────────┴─────────┴──────────┴───────────────┴─────────────────╯When any session is in a space, the listing is one table per space, in name order, each under the space's name, and the sessions in no space follow last with no heading. With no session in a space it is the one table above. The saved listing groups the same way, by the space each saved session was in. tuios ls --all-hosts groups each host's sessions under that host's line, by the spaces on that host, so a space of the same name on two hosts is two groups. A host whose daemon predates spaces sends no space, and its sessions list as in none. tuios ls --json stays one flat list, with space on each row that has one, saved rows included, and tuios ls --all-hosts --json carries space on each session row the same way.
tuios ls --json prints one object per session. Two fields say where the session's focused pane is:
diris the base name of the shell's directory. It is~for the home directory.branchis the git branch checked out there. A detached HEAD reads as its short hash.
Both come from the directory the shell last reported over OSC 7, or the directory the shell started in. Both are omitted when unknown. The sidebar labels a session with a generated name (session-0) by dir, and shows branch after any session name.
A session whose directory is inside a linked git worktree (not a main
checkout) also carries worktree: the repository (repo, repo_root), the
branch and the worktree's path, gone: true once the directory no longer
exists, and for one tuios made, its base, its fan group and the prompt a
fan sent it. It is what the rail groups by. global: true marks a global session, and
restored: true one rebuilt from saved state that nobody has attached to yet.
tuios list-clients Added in v0.9.0
List every connection to the daemon with its client id, kernel peer pid, and
current session. The session is empty while the connection is detached. The
command's own short-lived connection is included. The pid is 0 on Windows and
the BSDs. An SSH or web client's pid names the local server process, not the
remote SSH process or browser.
Usage:
tuios list-clients [--json]--json prints an array with one object per connection:
[
{"client_id":"client-1790941960197517900","pid":4242,"session":"work"}
]client-session-changed carries the session a client entered or left and sets
attached to true or false. A session rename sends one with the new name
and attached: true for each client in the session.
tuios detach-client Added in v0.9.0
Detach attached clients from their sessions, as tmux detach-client does.
The sessions continue to run. Each detached client exits with status 0 and
prints "The tuios detach-client command detached this client."
Usage:
tuios detach-client [--client ID | --session NAME] [--all-other] [--json]Flags:
--client <id>: Detach the client with this id, fromtuios list-clients-s, --session <name>: Detach every client of this session-a, --all-other: Keep one client and detach every other client of its session--json: Output as JSON
The command detaches:
- The client that
--clientnames. - Else every client of the session that
-snames. - Else, from a pane, the client used last in the session of the pane.
- Else the client used last in the only session with a client.
With --all-other, the command keeps the client that --client names, or
the client used last in the session. It detaches every other client of that
session.
From a pane, the command needs the admin grant. See
tuios pane-grants.
Examples:
tuios detach-client --client client-1790941960197517900
tuios detach-client -s work # Detach every client of work
tuios detach-client -s work --all-other # Keep the client used last in work--json prints the ids of the detached clients:
{"detached":["client-1790941960197517900"]}tuios ssh-agent-path Added in v0.9.0
Print the ssh agent link of a session. With ssh_agent = "follow" in
[daemon], the link points at the agent socket of the client that attached
to the session or used it last. New panes get SSH_AUTH_SOCK set to the link.
See CONFIGURATION.md.
Usage:
tuios ssh-agent-path [-s NAME] [--json]Flags:
-s, --session <name>: Session whose link to print. In a pane, the default is the session of the pane--json: Output as JSON, withfollowand the socket the link points at (target)
The command fails when ssh_agent is not "follow". A shell that started
before the option was set keeps its old SSH_AUTH_SOCK. Add this line to
your shell rc:
p=$(tuios ssh-agent-path 2>/dev/null) && export SSH_AUTH_SOCK="$p"tuios display-env Added in v0.9.3
Print the display of a session as export lines. A daemon that started without
a display gives new panes the display of the local client that attached or
used the session last. This is display = "follow" in [daemon], the
default. See CONFIGURATION.md.
Usage:
tuios display-env [-s NAME] [--json]Flags:
-s, --session <name>: Session whose display to print. In a pane, the default is the session of the pane--json: Output as JSON, withfollow,own, the Waylandlink, the socket it points at (target) and the variables (env)
The command prints an export line for each of WAYLAND_DISPLAY, DISPLAY
and XAUTHORITY that the session has. It prints nothing when the session has
no display to give. A shell that started before a desktop client attached
has no display. Run this line in that shell, or add it to your shell rc:
eval "$(tuios display-env 2>/dev/null)"tuios keep-awake Added in v0.13.1
Show or set keep_awake in [daemon]. The daemon keeps the machine from
sleeping while an agent pane on this machine works (agents), while the
daemon runs (on), or never (off, the default). See
CONFIGURATION.md.
Usage:
tuios keep-awake [off|on|agents] [--json]Flags:
--json: Output as JSON, withmode,held,working,methodand, when the hold failed,error
With no argument, the command shows the mode, whether the daemon holds the
machine awake now, and how many agents work. With a mode, it applies the mode
at once and saves it to the config file. The daemon uses systemd-inhibit on
Linux, caffeinate on macOS and SetThreadExecutionState on Windows. Only
sleep is held off. The display can still dim and lock.
tuios keep-awake agents
tuios keep-awaketuios kill-session
Kill a specific session.
Usage:
tuios kill-session <session-name>Examples:
tuios kill-session mysession # Kill session named "mysession"tuios worktree Added in v0.8.0
A git worktree as a session. worktree new makes a worktree of the repository
you are in and a session whose directory is that worktree. The rail groups these
sessions under the repository and labels each by its branch.
A worktree of a bare repository is grouped under the project's name: api for
api.git, and for a bare repository kept as api/.bare or api/git beside
its worktrees, the api directory. A repository whose refs are in reftable
(git clone --ref-format=reftable) holds no branch name in its HEAD file.
tuios asks git for its branches instead, so it needs git 2.45 or later on
PATH, and asks again only after a ref changes.
The same verb is reachable from the rail. Right-click a repository's group
header, or a worktree session's row, and take "New worktree...". The dialog
asks for the branch and the session name. Leave the name empty and the dialog
derives one from the repository and the branch. It does not ask for the
folder: the daemon places the worktree by [worktree] path (see
Where worktrees go), else under
TUIOS_WORKTREE_DIR in the daemon's environment, else under
$XDG_DATA_HOME/tuios/worktrees, and the notification reports where it
went. A worktree inside the repository that git does not ignore is reported
with a warning.
Usage:
tuios worktree new <branch> [--repo <dir>] [--base <ref>] [--name <session>] [--agent <cli> [--prompt <text>]] [--setup <command> [--setup-async]] [--host <host> [--clone]] [--detach]
tuios worktree ls [--repo <name>] [--group <stem>] [--host <host>] [--fast] [--json]
tuios worktree rm [<host>:]<session> [--stash | --force] [--keep-session]
tuios worktree diff <session> [--stat]
tuios worktree pull <host>:<session> [--repo <dir>] [--branch <name>] [--name <session>] [--detach] [--json]Examples:
tuios worktree new feat/retry # A new branch from HEAD, attached
tuios worktree new feat/retry --agent claude --detach # Headless, running Claude Code
tuios worktree new feat/retry --agent claude --detach --prompt 'Add a retry.' # And give it its task
tuios worktree new feat/retry --agent claude --setup 'pnpm i' # Install, then start Claude Code
tuios worktree ls # Repo, branch, agent state, changes, merged
tuios worktree rm api-feat-retry --stash # Keep the changes in git stashThe session is named <repo>-<branch>, with every slash turned into a hyphen.
Worktrees go under $XDG_DATA_HOME/tuios/worktrees/<repo>/<branch>, unless
[worktree] path puts them elsewhere (see
Where worktrees go).
--prompt gives the --agent its first task. tuios types it once the agent
is at its prompt and checks that the agent took it, the way
start-agent --prompt and fan do, and the command returns then. It prints
"The prompt was typed and taken.", or the prompt's status and why, and exits
1 when the prompt was not taken. With a sync --setup, the agent starts after
the setup, the prompt is typed then, and worktree ls shows its
prompt_status. --prompt without --agent is refused.
An after-new-worktree hook runs in the new worktree before its first window
starts, for example to copy .env from the main checkout. See
HOOKS.md. When the hook fails, worktree new prints a warning
and keeps the worktree and the session.
--setup runs a shell command in the new worktree, in a window named setup,
before the agent or shell starts. [worktree] setup sets one for every
worktree (see Setup before the agent).
The agent starts when the setup passes. When the setup fails, tuios removes the
new worktree and the branch it made, if they hold no change and no commit. The
session stays with the setup window open. --setup-async starts the agent at
once, and a failed setup then keeps the worktree and the branch. The SETUP
column of worktree ls shows the state, and the exit status of a failure.
worktree ls --fast skips the git walk behind the change columns, which is the
slow part of the listing, and leaves those columns empty.
worktree rm refuses a worktree with uncommitted changes and removes nothing.
--stash keeps the changes in git stash as tuios: <branch>. --force
discards them, and is the only option that does. The branch is never deleted.
A session whose worktree directory was removed under it shows gone in the
listing and is kept.
The MERGED column of worktree ls shows into <ref> when the branch is
merged. A branch is merged when it has commits of its own, and merging it into
its base changes nothing. tuios checks the base, then the upstream of the base,
such as origin/main. It does not fetch. A merge commit, a fast-forward, a
rebase and a squash merge all count. A new branch with no commits is not
merged. A branch that only fast-forwarded to its base is not merged. A commit
and its revert are not merged. --json gives merged and merged_into. tuios does not remove a
merged worktree. Use worktree rm to remove it.
On another machine. --host runs worktree new and worktree ls on a
machine from the [hosts] table, and worktree rm takes HOST:SESSION. Run
them inside your checkout: the repository is sent as its origin URL, and the
host finds its own checkout of it under [hosts.NAME] repos_root (set with
tuios hosts add NAME ADDR --repos-root ~/src), or else under ~/src,
~/dev, ~/code, ~/projects, ~/repos, ~/git, ~/work and ~/go/src
there. --clone clones it there when it has none; only https, ssh and git URLs
are cloned. With --host, --repo names a directory on the host. A host whose
tuios is too old for this is named, with what to upgrade.
worktree diff reads files on this machine, so it refuses HOST:SESSION and
names worktree pull.
Pulling work back. worktree pull HOST:SESSION copies a worktree session's
work on another machine into a new worktree session here. Its commits cross as
a git bundle and are fetched into a new branch of the repository you are in,
named as there or by --branch. The branch carried is the one the worktree's
HEAD is on now, so an agent that made its own branch there has that branch
pulled. A worktree with a detached HEAD is refused. When the commits cannot be
fetched, or the branch they make does not end where the other machine said,
the new branch is removed again, so the pull can simply be run again. Its uncommitted work, untracked files
included, crosses as a patch and is applied, uncommitted, in the new worktree.
Only the commits past the worktree's base cross when this repository has the
base commit, and the whole branch otherwise. A branch that already exists here
is refused and nothing is overwritten. A repository here whose origin differs
from the one there is refused. Nothing on the other machine changes. When the
patch does not apply, it is kept under the temporary directory and the command
names it.
tuios worktree new feat/retry --host build --clone --detach
tuios worktree ls --host build
tuios worktree pull build:api-feat-retry --detach
tuios worktree rm build:api-feat-retry --stashtuios fan Added in v0.8.0
Fan a prompt out across several agents, each in its own worktree.
Usage:
tuios fan <count> --agent <agent>[,<agent>...] [--env NAME[=VALUE]]... [--repo <dir>] [--base <ref>] [--name <stem>] [--setup <command> [--setup-async]] [--host <host> [--clone]] [--wait] <prompt>
tuios fan [<count>] --agent <agent>[,<agent>...] --prompt <prompt> --prompt <prompt>... [flags]
tuios fan keep [<host>:]<session> [--stash | --force] [--merge [--squash | --ff-only] [--into <branch>]]
tuios fan compare [[<host>:]<session>] [--no-changes] [--json]
tuios fan verify [<host>:]<session> [--timeout <duration>] [--no-wait] [--json] -- <command>...
tuios fan diff <session-a> <session-b> [--stat]
tuios fan verdict [<host>:]<session> --pick <session> --summary <text> [--reason <text>]... [--note <session>=<text>]... [--json]Flags:
--agent <agent>: The agent as you would type it, arguments included:claude,'codex --model o5', or any program. Several, comma-separated or repeated, are cycled across the sessions (required)--prompt <prompt>: One session's prompt, repeated once per session, in place of the prompt argument. The count is then how many there are--env NAMEor--env NAME=VALUE: Pass your value of a variable, or set one, for every agent. Repeatable.PATHis always sent, so the agents are found where your shell finds them--grants <grant>[,<grant>...]: What every agent may do through tuios, as forstart-agent--name <stem>: The fan's name, which its branches start with. A name that is already a fan in the repository is refused. Omitted, the name comes from the prompt and moves on to a free one--join <session>: Add the attempts to the fan of this session, on purpose, instead of starting a new fan. Your pane must reach that session--task <id>: The task card the fan works on. It gets the fan's name and holds no pane, sotuios task claim --nextskips it while the fan lasts. With[tasks] auto_stageon it moves todoing, andfan verifyand the attempts' pull requests then move it (seetuios task). Needs whattuios task claimneeds, and the card must be held by no pane but yours, not blocked and not done. Not with--host: the card is on this machine--task-session <name>: The session of--task(default: this pane's session, else the most recently active)--repo <dir>,--base <ref>,--wait,--json
Examples:
tuios fan 3 --agent claude 'Add a retry with backoff to the HTTP client.'
tuios fan 3 --agent 'claude,codex --model o5,gemini' 'Add a retry with backoff.'
tuios fan --agent claude --env ANTHROPIC_API_KEY --prompt 'Add a retry.' --prompt 'Add a timeout.'
tuios worktree ls --group fan/add-retry-backoff-http # Which prompts were sent, what changed
tuios worktree diff api-fan-add-retry-backoff-http-2 # What one of them produced
tuios fan compare api-fan-add-retry-backoff-http # Every attempt side by side
tuios fan verify api-fan-add-retry-backoff-http -- go test ./...
tuios fan diff api-fan-add-retry-backoff-http api-fan-add-retry-backoff-http-2
tuios fan keep api-fan-add-retry-backoff-http-2 --stashtuios fan verdict records a judge's pick among the attempts: the attempt
it recommends, the verdict, its reasons and a note on each attempt. The
agents view shows it on the fan's row and in the comparison (c on an
attempt), where k keeps the recommended attempt. In that comparison, j
starts a judge: an agent in a session of its own that reads the attempts and
reports with this command. Only that judge's pane, or a call from outside
every pane, records a verdict. The judge can read the attempts and nothing
more: tuios refuses it typing into their panes, commands in their sessions and
agents there. It runs in the main checkout as a program with your rights to
files, and its prompt asks it to change none.
The branches are a stem, then stem-2, stem-3. The stem is fan/ and the
first words of the prompt, or --name. Each prompt is typed once its agent
shows it is at its prompt, as one paste submitted with a carriage return (the
Enter key), so the command returns at once and tuios worktree ls shows
pending, held: look at the pane, sent, not sent or stalled per
session. held means the agent has not been ready for 30 seconds, most often
because it shows a first-run choice; the Inbox asks you to look, and the
prompt is typed once it is ready. A program no harness manifest recognises is
ready only once it reports a state (tuios set-agent-state idle). stalled
means the prompt was typed and the agent showed no sign of taking it within
five seconds: it did not turn working or needs_input. Look at the pane before
sending it again, since the text may be in the agent's input box. --wait
blocks until every prompt is sent or given up on.
The agent string is split into words the way a shell splits them and exec'd
directly: nothing in it is expanded. TUIOS_ variables, TMUX and
TMUX_PANE cannot be passed with --env.
fan compare prints one line per attempt of the fan the session belongs to:
its agent and state, the files and lines it changed against the fan's base
(committed or not, untracked files included, ignored files left out), and its
last check. The check is the last fan verify result, or else the last
command a shell in the session finished, from its OSC 133 marks. The counts
run from where each attempt left the base, so a base that moves on after the
fan started (a fetch, or one attempt merged into it) does not change them.
They run git in every worktree, at most 10 seconds each; --no-changes skips
them. The worktrees are read
through a temporary index, so nothing in them changes.
fan/retry in api, 3 attempts against main
api-fan-retry claude done 4 files +120 -31 go test ./... passed 14m ago
api-fan-retry-2 codex working 2 files +40 -3 no check yet
api-fan-retry-3 claude errored 0 files +0 -0 last command exited 1 (make lint)
Keep one with 'tuios fan keep <session>'. Compare two with 'tuios fan diff A B'.fan verify runs the command after -- in every attempt, in a window named
verify in each session, with sh -c in the worktree and your PATH. One
word after -- is a shell line, so 'make lint && make test' keeps its &&.
Several words are one command and its arguments: each is quoted for the shell
as you gave it, so -- go test -run 'TestA|TestB' ./... passes the pattern
as one argument. The command is always yours: tuios never reads one from the repository. The
window holds no grants, so the check cannot drive tuios. A window whose check
passed closes; one whose check failed stays open with the output until you
press enter in it. The command waits for every check, prints one line each,
and exits 1 when any failed. --timeout fails a check that runs longer and
closes its window. --no-wait returns once the checks are started. A check
still running in an attempt is stopped first, and the window an earlier
failed check left open is closed.
fan diff A B shows what B's files hold that A's do not, committed or not,
untracked files included. git runs on this machine, as for worktree diff,
so both sessions must be here.
fan keep removes every sibling of the session you keep, the way worktree rm
does: a sibling with uncommitted changes is left in place unless --stash or
--force is passed, and the command exits 1 to say so. The daemon does the
removal (keep-fan), so the TUI and the CLI share it; against a daemon from
before that verb the CLI removes the siblings itself, with the same result.
--merge first merges the kept session's branch into its base in the main
checkout, as tuios ship merge does. When that merge is refused or
conflicts, it is undone and no sibling is removed.
--host runs the fan-out on another machine, in its checkout of the repository
you are in, found and cloned the way worktree new --host does it. The agent
must be installed there, and is looked up on that machine's PATH: yours is
not sent, and --env is refused. The sessions show in the rail under the
host. fan keep HOST:SESSION keeps one there, and worktree pull HOST:SESSION brings its work here.
tuios fan 3 --host build --agent claude 'Add a retry.'
tuios worktree pull build:api-fan-add-retry-2
tuios fan keep build:api-fan-add-retry-2 --stashAny machine
tuios start-agent -s any:SESSION and tuios fan --host any let this
machine's daemon pick the machine, this one or a linked one from [hosts],
and print the pick and why. tuios call place-agent '{"agent":"claude"}'
asks the same question and starts nothing. Nothing goes to another machine
unless you ask for any or name the machine.
The rule has three steps:
- A machine is left out when its link is not up or does not allow starting
agents, the agent is not installed or not signed in there, the agent
reached its usage limit there, it has no checkout of the repository (and
clonewas not asked) or more than one, its memory is 95% used, it is at its[tasks] machine_cap, or, for a card, it has no link back to this machine to claim the card with. A card of the session only stays here. - Of the rest, the most spare cores wins: the cores times the share the one-minute load leaves free, less half a core for each agent that works, starts, or was just picked there. Memory over 80% used lowers it.
- Two machines within one core tie: the one with the checkout wins, then this machine.
The repository is the one the current directory is in. The pick counts as a busy agent on that machine for 90 seconds, or until that machine reports the start, so a burst of starts spreads out.
Examples:
tuios start-agent -s any:api claude --prompt 'Fix the flaky test.'
# Placed on build. build: 16 cores, 0 working, the repo is there.
tuios task add --project . --machine any 'Fix the retry'
tuios start-agent -s any:home claude --task t1 --prompt 'Take task t1.'
tuios call place-agent '{"agent":"claude","reserve":false}'With --task and another machine, that machine's agent claims the card here
over its own link back, so the card shows who holds it while the agent works
there, and the pane's close lets it go. It fails with no_machine when no
machine passes, and the message gives each machine's reason.
tuios start-agent Added in v0.8.0
Start an agent in a new pane, here or on another machine, and return once it is ready for a prompt.
Usage:
tuios start-agent [<agent>] [--preset <name>] [-s [<host>|any:]<session>] [--name <name>] [--cwd <dir> | --repo <dir> | --clone] [--workspace <n>] [--focus] [--prompt <prompt>] [--ready-timeout <ms>] [--no-wait] [--protocol acp|codex] [--env NAME[=VALUE]]... [--grants <grant>[,<grant>...]] [--task <id>] [--parent <window-id>] [--model <model>] [--effort <level>] [--permission-mode <mode>] [--print-id] [--json] [-- <args>...]--parent names the agent pane the new agent reports to, by window id. It
defaults to the agent pane the command runs in.
--model, --effort and --permission-mode pass the harness's own flags for
them, as the [launch] table of its manifest names them. For Claude Code they
are --model, --effort (low, medium, high, xhigh, max) and
--permission-mode (manual, acceptEdits, plan, auto, dontAsk,
bypassPermissions). A harness with no such flag refuses the option, and a
value it does not list is refused with the ones it takes, before anything
starts. A model is one word that does not start with -. Started from an
agent pane, the permission mode is held to that agent's own.
--task claims a task card of the session for the new pane as soon as the
pane exists. The card must be held by no pane, not blocked and not done, and
the call needs what tuios task claim needs. It is checked before anything
starts, and the session must exist already.
-s any:SESSION lets this machine pick the machine first, as
Any machine says, and prints the pick and why.
With --task, the card is this machine's, in SESSION.
--grants says what the agent may do through tuios: read, write, fan,
respond, admin, or none (see tuios pane-grants).
Without it the pane holds the default of [agents.permissions], or, started
from a pane without admin, that pane's own grants.
Examples:
tuios start-agent claude --name reviewer
tuios ask-agent -w reviewer 'review the diff on this branch'
tuios start-agent 'codex --model o5' --name tests --prompt 'Run the tests and fix what fails.'
tuios start-agent claude --model opus --effort high --permission-mode plan<agent> is written as for fan. The command waits until the agent shows it
is at its prompt (idle or done), then types --prompt if one was given, and
prints the pane and the evidence. It exits 1 when the agent is not ready: it
stopped on a question of its own (the pane is kept for you to answer, and the
Inbox shows it), showed nothing before --ready-timeout (default 120000), or
exited. It also exits 1 when a --prompt was not taken. The pane is not
focused unless --focus is passed. Without --workspace it opens on the
calling pane's workspace, or outside every pane on the one the session shows.
--no-wait returns as soon as the agent's process has started and has not
exited within a second, without waiting for it to be ready. It exits 1 only
when the agent could not start or exited at once, with the reason. --prompt
is then typed in the background once the agent is ready. An agent that stays
unready shows in the Inbox. A caller with a time limit of its own, such as a
Rex action, uses it.
Without --cwd or --repo, the agent starts in your directory when you run
the command in a pane. Outside a pane it starts in the focused pane's
directory. With appearance.new_window_inherit_cwd off, it starts in the
session's directory.
The command sends your PATH with any --env, as fan does, when the
session is on this machine. An agent that is not on your PATH is looked up
on the daemon's, the PATH a new pane gets, and then runs with that PATH.
The command says so on stderr. This is what lets a caller with a bare PATH,
such as an app, start an agent the person installed. For a session on another machine
(-s host:session) it sends no PATH, and the agent is looked up on that
machine's PATH. --env there is refused with forbidden, because
variables do not cross machines.
The session -s names is created when it does not exist. The agent starts in
--cwd, or the main checkout of the repository --repo names, or else the
focused pane's directory. With -s HOST:SESSION and neither, it starts in that
machine's checkout of the repository you are in, found and cloned the way
worktree new --host does it (--clone clones it there when it has none).
Arguments after -- are passed to the agent as an argv.
tuios start-agent -s build:api claude --prompt 'Profile the build.' -- --model opus--protocol runs the agent headless over a structured protocol instead of in
its own TUI, and the pane shows the conversation as a transcript you type
prompts into:
tuios start-agent --protocol acp 'opencode acp' --name helper --prompt 'List the TODOs.'
tuios start-agent --protocol codex codex --name tests--preset NAME starts from an [agents.presets.NAME] entry of your config
(see CONFIGURATION.md), which may name the agent,
so <agent> can be left out. A flag you pass wins over the preset's. args,
env and after_ready are the preset's, then yours. --grants replaces the
preset's grants, and a preset never gives more than you may give. The preset
is read from this machine's config, merged by this machine's daemon, and sent
in full to a session on another machine, so your presets work on every host.
An unknown name is refused with the names there are, and nothing starts.
--print-id prints the new pane's full id alone. When the agent is not
ready, it still prints the id, says why on stderr and exits 1, so a script
can close the pane. The plain success line ends with the full id too.
id=$(tuios start-agent --preset worker --name w3 -s crew --print-id)
tuios send-agent-message -s crew -w "$id" 'Read the brief and start.'acp is the Agent Client Protocol, version 1, for any agent command that
speaks it. codex is the Codex app-server, and app-server is added to the
codex command. The pane runs tuios agent-proto,
which reports the agent's state itself, so the command returns once that
report says idle. A permission the agent asks for is answered in the pane with
a number key, or from the Inbox when one line shows the whole request, with no
[agents.approvals] needed. A daemon older than --protocol refuses it by
name.
tuios delegate Added in v0.13.1
Hand a task to a child agent, and get its answer back as mail.
Usage:
tuios delegate '<task>' [--agent <agent>] [--role <role>] [--isolation shared|worktree] [--wait <duration>] [--name <name>] [-s <session>] [--cwd <dir>] [--parent <window>] [--grants <grant>[,<grant>...]] [--env NAME[=VALUE]]... [--ready-timeout <ms>] [--json] [-- <args>...]The command starts the agent with start-agent, links it to you as its
parent, and types the task as its first prompt. Without --wait it returns at
once, and you end your turn. When the child finishes, tuios sends its answer
to you as mail from the child, with the subject Delegated task done: ROLE.
The mail wake then types one line into your pane once you are at rest. A
question the child stops on comes as mail too. An approval stays in the Inbox.
--wait returns the outcome instead, at most 10m: done, errored,
question, approval or timeout. The end of the wait does not stop the
child, and its answer then comes as mail when there is a parent.
--isolation worktree starts the child in a new worktree, in a session of its
own, made from the commit of your checkout. It does not have your uncommitted
changes. --role is implementation, research, review, design, test
or general. research and review give the child the read grant unless
--grants says otherwise. --agent defaults to your own harness.
A child is never wider than its parent: the grants and permission mode rules
of start-agent apply. From outside every pane, name the parent with
--parent or pass --wait. The command exits 1 when the task was not typed
into the child.
Examples:
tuios delegate --role review 'Review the diff on this branch and list the bugs.'
tuios delegate --agent codex --isolation worktree --role test --wait 10m 'Add tests for the parser.'tuios agent-proto Added in v0.8.0
The pane program of start-agent --protocol: run an agent headless over ACP
or the Codex app-server, and show it as a transcript with a prompt line.
Usage:
tuios agent-proto --protocol acp|codex [--harness <id>] [--cwd <dir>] [--acp-version 1|2] [--resume <id>] -- <agent> [args...]It starts the agent with pipes, in a session of its own with no controlling terminal, and offers it no file system and no terminal, so the agent acts under its own sandbox and approval settings. Everything the agent sends is cleaned of escape sequences before it is written. Type a prompt and press Enter to send it; a paste arrives as one prompt. Ctrl+C cancels a turn, and Ctrl+D on an empty line quits. A permission is shown with a number key per answer; a key counts once the question has been up for half a second, and a paste never answers one.
Inside a tuios pane it reports the pane's state under --harness (default:
the protocol): idle, working, done or errored, and needs_input with
kind approval for a permission, which it also holds for the Inbox with
request-approval when one line shows the whole request. Outside tuios it
reports nothing and works the same. When the agent exits, the pane shows the
end of its stderr and waits for Enter.
It also writes what the agent says about itself to the pane's agent metadata,
under the source protocol, each key only when its value changes: model
(the model the conversation opened with, from Codex's thread/start or ACP's
session/new models, and Codex's model/rerouted), context (tokens in
context of the model's window, from Codex's thread/tokenUsage/updated or
ACP's usage_update), cost (the session's cost from ACP's usage_update;
Codex sends none) and plan (steps done of the plan's steps, 3/7). Every
field is optional: one the agent does not send is not written, and every key
is sent again at the start of each turn. Each prompt, tool call and finished
turn also goes to the daemon as set-agent-state activity, when the daemon's
set-agent-state lists that parameter; the activity changes no state (its
if_state is none). Both are sent off the pane's input loop. A Codex pane
now shows the turn's plan in the transcript, as an ACP pane does, and an ACP
pane whose agent names its model shows it in the first line, connected to opencode 1.2 (Claude Sonnet 4), as a Codex pane does.
--acp-version is the ACP version to ask for: 1, the default, or 2, a draft
of the spec. start-agent passes [agents] acp_version here. An agent that
speaks only version 1 answers 1 or refuses, and the pane then speaks version
1, starting the agent again when it has to; the first line names the version.
In version 2 a turn ends when the agent reports it idle. --resume reattaches
to a conversation the agent kept, by its session id, with session/resume.
See ACP versions.
tuios agent-proto --protocol acp -- opencode acp
tuios agent-proto --protocol acp --acp-version 2 -- my-v2-agenttuios agent-statusline Added in v0.8.0
What Claude Code's status line runs once tuios integration install claude-code --statusline is installed: read the status line payload on stdin
and write the model, context use and cost to the pane's agent metadata.
Usage:
tuios agent-statusline claude-code|opencode|kilo [-s SESSION] [-w PANE] [--then CMD] [--turn-end] [--explain] [--timeout D]-s, --session names the session of the pane (default: TUIOS_SESSION), and
-w, --window the pane (default: TUIOS_PANE_ID, then the controlling
terminal, then the parent processes).
| Payload field | Metadata key |
|---|---|
model.display_name, else model.id (Claude Code); modelID (opencode, Kilo) | model |
context_window.used_percentage (Claude Code) | context, as 42% |
the input side of context_window.current_usage (Claude Code) | context_tokens, as 612012 |
context_window.context_window_size (Claude Code) | context_window, as 1000000 |
cost.total_cost_usd (Claude Code); cost (opencode, Kilo) | cost, as $1.20 |
Every field is optional, and one that is missing, null or of another type is
not written. The keys go under the source statusline, with no TTL: they
clear when the agent leaves the pane. It prints nothing of its own. --then
runs your own status line command through sh -c with the same stdin and
prints its output unchanged, and the command exits with its status. That is
how a status line of your own is kept.
The pane is found from -w, then TUIOS_PANE_ID, then the process's terminal
and parent processes, as for agent-hook; a process in no pane asks the
daemon again at most once a minute. It calls only set-agent-meta, for that
pane, at most once every 15 seconds while the values change, and not at all
while they stay the same. A model change, context use crossing 80%, and a
change passed with --turn-end (the opencode plugin passes it when the
session goes idle) go at once, and unchanged values are sent again after 10
minutes so a daemon that restarted gets them back. The last values sent, and
any the interval held back, are kept in statusline-<session>-<pane>.json
(mode 0600) beside the daemon's socket. Held values go with the next run that
is due, or when the turn ends: Claude Code's Stop hook (tuios agent-hook claude-code) sends them, and a run after the Stop goes at once. It reads at most 1 MiB of stdin, gives up on the daemon after 300ms
(--timeout), and exits 0 whatever goes wrong on the tuios side.
tuios agent-statusline claude-code --then '~/.claude/statusline.sh'
echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":42}}' | tuios agent-statusline claude-code --explaintuios kill-server
Stop the TUIOS daemon process. This stops all sessions.
Usage:
tuios kill-serverContract: the command is synchronous. It returns only once the daemon has written every session's resurrection state and removed its socket, so a script may start a new daemon as soon as it returns:
tuios kill-server && tuios start-server # safe: no raceThe daemon unlinks its socket last, after the final saves, and that unlink is what this command waits for. A refused connection is not the same signal: the daemon closes its listener at the start of shutdown, while state is still unsaved, so polling the socket for connectivity can report "stopped" before anything has been persisted.
If the daemon has not finished within 10 seconds the command fails, naming the
pid and the socket, rather than returning success while the old process is still
running. Re-running it re-checks. Force killing with kill -9 skips the final
save and loses any state written since the last periodic save.
When no daemon is running, the command reports that and removes a stale socket if one is present. It exits 0 in that case.
--restart tells the attached clients that a new daemon follows, so they wait
for it and attach again. Without it the clients quit at once.
tuios restart-server passes it.
tuios restart-server Added in v0.11.0
Stop the daemon and start it again with the newest tuios installed. Use it after an update: the daemon runs the build it started with until it stops.
Usage:
tuios restart-server # show what stops, ask, then restart
tuios restart-server --dry-run # show what stops, and change nothing
tuios restart-server --yes # restart without a question
tuios restart-server --last # show the steps of the last restartThe command first says what a restart does:
Daemon now 0.10.0
After restart 0.10.2 (from ~/.local/bin/tuios)
These stop:
nvim in "edit" (session work)
claude in "agent" (session work)
Only shells in notes.
These come back:
Each session, with its layout, its pane history and new shells.
claude-code in "agent" (session work) can resume.
The Inbox offers to resume each one.
Restart the daemon? [y/N]Then it stops the daemon, starts the new one and waits until it answers:
Stopping the daemon...
Starting the daemon 0.10.2...
The daemon restarted on 0.10.2.
These sessions came back: work, notes.- The new daemon runs the newer of two binaries: the tuios at the path of
this command, which an update replaces, and the
tuioson PATH, which an install in the Nix store, mise, asdf or Linuxbrew moves.--versiondecides. When the version after the restart is the daemon's own, the plan says "This restart starts the same version." - The stop is
kill-server, so every session is saved first. The new daemon restores every saved session before it answers. - The stop and the start run in a process of their own, in a session of its
own and deaf to SIGHUP. So a restart run in a pane of the daemon it stops
finishes. Each step goes to
restart.logbeside the daemon log, and--lastshows it. - One restart runs at a time. A second one refuses while the first runs.
daemon.resume_agentssays what the new daemon does with the agent conversations:askputs a Resume item in the Inbox,autoresumes them, andoffleaves them totuios resume-agent.- The command asks in every state but a stopped daemon, a daemon that did
not answer included. With no terminal to ask on, it refuses unless
--yesis given.--jsonneeds--yes. Nothing is changed when it refuses. - When the daemon is not running, the command starts it.
The app runs this command from the command palette ("Restart the daemon"), from the version notice, from the Daemon tab of the settings and from the rail's menu for this machine. It then starts again in the same session. Other attached clients wait up to 15 seconds for the new daemon and attach to their session again. See KEYBINDINGS.md.
--expect DIGEST refuses the restart unless the plan has that digest. The
app passes the digest of the plan the person agreed to, so a program that
started since makes the restart refuse: "What a restart stops changed after
you agreed to it." Nothing is changed.
--json writes one JSON object per line: plan, then stopping,
starting and done. The plan object holds binary, version, daemon
(with each session's busy panes and its resume agents) and
resume_mode. The done object holds restarted, after, back and
missing. A failed step sets error and fix, and the command exits 1.
| Error | Next step |
|---|---|
| "The daemon did not stop. It still runs version X." | Run tuios kill-server to see why. |
| "The daemon did not start." | Run tuios start-server to see why. The sessions come back when the daemon starts. |
| "The daemon started and did not answer." | Run tuios ls to check it, or tuios logs. |
| "Another restart of the daemon is running." | Wait for it to end. tuios restart-server --last shows its steps. |
| "The restart stopped before it finished." | Run tuios restart-server --last, then tuios ls. |
A restart ends every program running in a pane. To move the daemon to another build with the programs still running, use tuios daemon upgrade instead.
tuios daemon
Run the daemon in the foreground (for debugging).
Usage:
tuios daemon [flags]Flags:
--log-level <level>: Debug log level:off,errors,basic,messages,verbose,trace--no-restore: Do not restore saved sessions on start. Runtuios resurrectto restore one on demand
Debug log levels:
off: No debug output (default)errors: Only error messagesbasic: Connection events and errorsmessages: All protocol messages except PTY I/Overbose: All messages including PTY I/Otrace: Full payload hex dumps
Note: This is primarily for debugging. The daemon starts automatically in the background when you run tuios new or tuios attach. Use this command to run the daemon in the foreground with debug logging.
tuios daemon-app
macOS only. Write a small app, TUIOS Daemon, that starts the daemon. Panes of a daemon that the app started keep local network access after the terminal quits. See Local Network Access on macOS.
Usage:
tuios daemon-app install [--login] [--force] [--binary PATH] [--path PATH]
tuios daemon-app status
tuios daemon-app uninstall [--path PATH]Flags of install:
--login: Also write a LaunchAgent that opens the app at login--force: Replace an app that is already there. This removes its Local Network permission--binary <path>: The tuios that the app starts. The default is the tuios onPATH--path <path>: Where to write the app. The default is~/Applications/TUIOS Daemon.app
When the app is installed, each new daemon starts through it. Set
TUIOS_NO_DAEMON_APP=1 to start a daemon directly.
tuios daemon install-service Added in v0.13.1
Install the daemon as a service of your user: a systemd user unit on Linux, a launchd agent on macOS, a Task Scheduler task on Windows. The service starts the daemon at boot (Linux, with linger on) or at login, and again after a crash. See Running the Daemon as a Service.
Usage:
tuios daemon install-service [--dry-run] [--binary PATH]
tuios daemon service-status [--json]
tuios daemon uninstall-serviceFlags of install-service:
--dry-run: Show the service file and change nothing--binary <path>: The tuios the service runs. The default is the tuios onPATH
A daemon that runs now continues. It moves under the service when it starts
again, for example after tuios restart-server. uninstall-service removes
the service and leaves the daemon that runs now. When a service is installed,
tuios starts each new daemon through it. Set TUIOS_NO_SERVICE=1 to start a
daemon directly.
service-status shows the service, its state, the tuios it runs, linger on
Linux, and whether the daemon that runs now is the service's.
tuios daemon upgrade Added in v0.13.1
Upgrade the running daemon to another tuios binary in place, without ending any pane's program. Every pane's program keeps running with the same pid, the same terminal and the same screen, and the daemon keeps its pid. Live upgrades are experimental, opt-in, and macOS and Linux only.
Usage:
tuios daemon upgrade [flags]Flags:
--binary <path>: The tuios binary to run the daemon as (default: the tuios running the command)--json: Print the outcome as one JSON object--or-restart: When the daemon cannot be upgraded live, restart it with the binary instead, which ends running programs. With no daemon running, start one
Examples:
tuios daemon upgrade
tuios daemon upgrade --binary ~/bin/tuios-next
tuios --server test daemon upgrade --binary ./tuios # upgrades only the daemon named test
tuios daemon upgrade --binary ~/.local/bin/tuios --or-restart # live where it can, else a restartOutput:
Checking /usr/local/bin/tuios (v0.10.1) accepts this daemon's state (handoff v3)... ok
Paused 4 panes, saved their screens (34.3 KB).
Starting v0.10.1 in place (pid 8615 kept)...
Upgraded in 0.06 s. 4 panes and their programs kept.With attached clients the last line adds how many the upgrade dropped, such as 2 attached clients were dropped; tuios clients on this machine reattach by themselves. --json prints one object with action, pid, from, to, binary, panes, clients, seconds, fallback, recovered, instance and handoff, the measurements of the handoff in the shape of hello's upgrade field (see protocol.md). action is what happened: upgraded live, restarted or started by --or-restart, fallback to the old binary (also after a recovery by the keeper), refused with nothing changed, or failed. reason says why the daemon was not upgraded live, and unconfirmed is set when that was the person not answering Yes in the dialog. error holds the failure when the command fails. The object is printed on a failure too, and the error goes to stderr.
How it runs:
- The binary is run once as
<binary> daemon handoff-accepts, before anything pauses. A binary that does not run, or reads another handoff version, is refused and nothing changes. A tuios from before live upgrades fails this check. Before that run, the command and the daemon refuse a binary owned by neither you nor root, or one its group or others can write. The daemon runs and execs the very file it checked, so renaming a folder on the path afterwards cannot put another file in its place. On Linux it runs the open file. On macOS and other systems it runs a private copy of the file in its own state folder. A script, such as a wrapper, still runs by its path. A binary you cannot read, only run, runs by its path on macOS. For these two, keep the binary in folders no other user can write. - The daemon pauses every pane and writes its state down. A chatty program blocks in
write()for the pause and loses nothing; 60 busy panes with 1000 rows of history each pause for about 0.3 s. - Attached clients are told and dropped, and the daemon execs the new binary, which takes the panes over. Calls made during the swap wait in the socket's backlog and the new image answers them.
What is kept: sessions and windows as they stand; each pane's screen, the alternate screen with the main one under it, terminal modes (bracketed paste, mouse, kitty keyboard flags), titles and the title stack; the last 1000 rows of history per pane (deeper history is not carried); the folder and branch the shell reported; OSC 133 marks and command history; program status (OSC 7501) and agent state; pane tokens, so TUIOS_PANE_TOKEN keeps verifying; agent mailboxes; exit statuses, including a pane that exits during the upgrade; and the event stream's boot id and numbering, so subscribe, stream-pane and pane-view resume.
What ends:
- Attached clients are dropped. A tuios client on this machine waits up to 15 seconds for the new image, attaches to its session again by itself, and says
The daemon was upgraded. tuios reattached.When the new image is a newer build than the client's, the client runs it instead: it starts the binary the upgrade named astuios attach <session>in the same process and terminal, with the flags it was started with, and saysThe daemon was upgraded to <version>. This window runs it too.daemon.client_follows_upgrade = falsekeeps the old client. When the new image speaks another wire protocol than the client's build, the client finds it at the handshake, before it attaches, and printsThe daemon is being upgraded to <version>. Your programs are still running. Run 'tuios attach <session>' to continue.and exits 0. It prints the same when no new image takes the session back within the wait, and so does a client attached to another machine's session. SSH and web clients say to connect again. A client from a build without live upgrades reports the daemon as lost.tuios pane-viewreconnects on its own. - A JSON verb call that was running or waiting (
wait-for, a waiting popup,ask-agent) ends withdaemon_upgrading. Call it again; the new image answers. - Size leases end with their connection. Plugins and links to other machines are stopped and started again by the new image, and links redial.
- A pane's
close_on_exitis not carried: after the upgrade, a window whose program exits with no client attached stays open.
Refusals: the command exits 1 with upgrade_refused and nothing changes when the daemon runs on Windows, is embedded in another program (tuios-web, the SSH server), holds panes hosted here for another machine or a window whose process runs on another machine, is running a tuios fan verify check, or is running a popup with capture_stdout. A second upgrade while one runs is refused as busy. Run from inside a pane, the upgrade waits for the person: every attached client shows a dialog with the binary's full path, its version, and the pane that asked by its title, id and session. No is the default, and only a key pressed at a client answers it: Down or Right moves to Yes, any other key, Tab included, moves back to No, and Enter chooses. The first answer closes the dialog on the other clients. No, Esc, 60 seconds without an answer, no client attached that shows the dialog (a view-only client, a gui-bridge renderer and a client too old for the dialog do not), or the agent features turned off refuses it with forbidden and daemon-upgrade is for the person, followed by which of these it was and what to do, and nothing changes. A plugin is refused the same way without a dialog. A daemon from before live upgrades answers unknown_verb, and the command says to restart it with tuios restart-server, which stops every program in every pane. On Windows, tuios restart-server is the way to move to another build.
With --or-restart: an upgrade that cannot start is a restart instead. That covers a daemon from before live upgrades, a refusal, a binary that fails the preflight, a daemon that speaks another control protocol, and Windows. The command prints Not upgraded live: <reason>., then runs <binary> kill-server, which saves every session, and <binary> start-server, which restores them with their layout and new shells. Both run on the server the command runs on. Before it stops anything it checks that the binary runs at all, so a binary that is not a tuios stops nothing. It runs the binary by its path three times, and before each run it checks that the path still names the file it checked, so a file put there in between is never run. It reports restarted or started only once a daemon answers after start-server, and for a restart only when that daemon is not the old one; otherwise the command fails and says which. With no daemon running, it starts one with the binary and reports started. A daemon that went back to its old binary (below) is never restarted: every program in it still runs, and the command fails so the reason can be read in tuios logs. Nor is a binary owned by neither you nor root, or one its group or others can write: the command checks that before it runs the file at all, reports refused, and neither restarts a daemon nor starts one. Nor is a running daemon when the command runs in a pane (TUIOS_PANE_ID is set), whatever stopped the live upgrade: the restart's kill-server would end that pane and the command in it before start-server ran, and leave no daemon. The command reports refused, says the daemon was not restarted, and exits 1. When the refusal was the dialog's, because no Yes came, unconfirmed is set too. scripts/install.sh, tuios hosts sync --restart and just restart move the daemon this way.
Fallback: at start the daemon keeps the binary it runs at <state>/handoff/tuios.prev (a hard link, or a copy across file systems; one per server). If the new binary starts and cannot take the panes over (an error, a panic, or a 30 second watchdog), the daemon execs tuios.prev, which takes them back. The command then says the new binary could not take the panes over and the daemon went back to the old version, that every program is still running, to see tuios logs, and exits 1.
Crash of the new binary: before any pane pauses, the daemon starts a keeper, tuios.prev daemon handoff-keeper, that holds a copy of every pane's terminal, the sockets and the start lock until the new image is up, then exits. If the new image dies first (a crash, the out-of-memory killer, SIGKILL), the keeper runs tuios.prev in its own place, which takes the panes back: every program keeps running with the same pid, and the daemon comes back under the keeper's pid. The command says the new binary died before it was up and names both pids, and --json has recovered and fallback set; it exits 1. The daemon brought back this way is not the parent of the programs it took back: it still learns when one ends, with its exit status on macOS and without it (-1) on Linux. If the new image had already started reading the panes when it died, what it read is lost from their screens. A daemon stopped on purpose (kill-server) during the upgrade is not brought back.
The design is in design/live-handoff.md. What each kind of restart keeps is in SESSIONS.md.
Workflow Example
# Start a new session for work
tuios new work
# ... do some work, then detach with Ctrl+B d ...
# Later, list your sessions
tuios ls
# Reattach to continue working
tuios attach work
# When done, kill the session
tuios kill-session workCLI Reference
Every tuios command and flag, with examples. Sessions, windows, input and output, agents, remote hosts, tapes, environment variables and exit codes.
Remote Control Commands (part 1 of 2)
Remote Control Commands (part 1 of 2): part of the CLI Reference of TUIOS.
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.