CLI Reference

tuios [flags]              # start or attach to TUIOS
tuios <command> [flags]    # run a command

Every command accepts --help, and its output always matches your build. tuios help <command> does the same. To search every command, run tuios help -i. See help.

Conventions

Most commands that act on a running session share these flags:

• -s, --session <name>: the target session. In a pane, the default is that pane's own session. Outside every pane, the default is the most recently active session.
• -w, --window <target>: the target window. The default is the focused one.
• --json: print JSON instead of a table.

A window target is matched in this order, and the first match wins:

1. The full window ID
2. The index list-windows prints
3. The custom name, then the window title
4. A unique ID prefix, such as the 8 characters list-windows shows

An index or ID therefore beats a window that happens to be named 2, and a name beats an ID prefix: a pane named db is never mistaken for a pane whose ID starts with db. An ambiguous name or prefix is an error, never a guess.

Before v0.11.0, a command in a pane without -s acted on the most recently active session, which can be another one. A script in a pane that relied on that must pass -s with the session it wants.

An error says what happened and names the next command, with the session in it. A wrong window name lists each window once, as name (id):

send-text failed: no window found matching "targt".
Most likely cause: the window target matched no window. A window is
addressable by its id, a unique id prefix, the index list-windows prints,
or its exact name.
Did you mean "target"?
Available: caller (a021e941), target (609d5afd).
Fix: run 'tuios list-windows -s work'.

Commands that talk to the daemon exit 3 when no daemon is running. See Exit codes.

Global flags

Four flags work on every command:

• --server NAME Added in v0.9.3: use the separate daemon with the name NAME. TUIOS_SERVER=NAME does the same. See A separate daemon.
• --debug: enable debug logging.
• --cpuprofile <file>: write a CPU profile.
• --pprof <addr>: serve net/http/pprof on this address, for example :6060. With no host, the server listens on 127.0.0.1 only. The profiles have no password. Give 0.0.0.0:6060 only on a network you trust.

These work only on a bare tuios:

• --standalone: run a session without the daemon, for this run. TUIOS_NO_DAEMON=1 does the same for a whole shell.
• --skill [TOPIC]: print the agent skill for driving TUIOS from a pane, then exit. --skill TOPIC prints one topic, and --skill all prints every topic. See Letting an agent drive TUIOS.
• --list-themes: print every theme id, then exit.
• --preview-theme <name>: print a theme's 16 ANSI colours, then exit.
• -v, --version: print the version, the VT backend (pure-Go or ghostty), commit, build date and builder. There is no version subcommand.

tuios --theme $(tuios --list-themes | fzf --preview 'tuios --preview-theme {}')

To install the skill for an agent harness, run tuios integration install Added in v0.10.1. See Letting an agent drive TUIOS.

A bare tuios attaches to a daemon session, because startup.daemon defaults to true. See The startup table.

Interface flags

These flags change how the TUI looks for one run. They are accepted by tuios, new, attach, ssh and tape play. Any other command rejects them. Each one overrides a config option.

Commands

agent-hook, agent-statusline and agent-proto are run by the harness integrations and by start-agent --protocol, not by hand. Their --help says what they do.

Aliases: attach is a, new is n, ls is list-sessions, resurrect is restore, keybinds is keys or kb, and hosts remove is hosts rm.

Sessions

A session lives in the daemon and keeps running after you detach (Ctrl+B d). The daemon starts on its own when a command needs it. See Sessions.

new

Create a session and attach to it. Alias: n.

tuios new [session-name] [flags]

• -d, --detach: create the session without attaching.
• --host <name>: create the session on a machine from the [hosts] table.
• --ssh: with --host, run ssh to the host and use its own tuios instead of attaching here.
• --global: create a global session, which can hold panes from more than one machine.
• --space <name> Added in v0.10.0: file the session under a space. It does not work with --host or --global.
• --hold: after a failure, wait for Enter before exiting.
• --cwd <dir>: the directory the session's windows start in. The default is the current directory. It does not work with --host.
• The interface flags.

tuios new                          # auto-generated name
tuios new api --cwd ~/dev/api      # windows start in ~/dev/api
tuios new work --theme dracula
tuios new build --detach           # headless, for scripting
tuios new --host buildbox ci -d    # on another machine
tuios new api --space payments -d  # in the space payments

tuios refuses a session name of dots only, a name that ends in a dot, and the Windows device names (con, prn, aux, nul, com1 to com9, lpt1 to lpt9), on every system. A saved session can then move between machines.

A detached session gets one window and works at once with send-keys, run-command and capture-pane. It is 80x24 until a client attaches. Run from a script, a service or CI, with no terminal on stdout, its panes still get TERM=xterm-256color and COLORTERM=truecolor, not dumb. See Headless Sessions.

attach

Attach to a session. Alias: a.

tuios attach [session-name] [flags]

• -c, --create: create the session if it does not exist.
• --host <name>: attach to a session on a machine from the [hosts] table.
• --ssh: with --host, run ssh to the host and use its own tuios. Press the prefix twice to send it to the remote client.
• --hold: after a failure, wait for Enter before exiting.
• --force: attach from inside a pane of the same session. See Attach from inside a pane.
• -d, --detach-others: detach every other client of the session, as tmux attach -d does.
• The interface flags.

tuios attach                  # the session you used last
tuios attach work -c          # attach, or create it
tuios attach -d work          # attach, and detach the other clients of work
tuios attach --host build api # the session api on the machine build

With no name, attach opens the session you last typed or clicked in. Windows that agents or scripts open, and keys that send-keys or a tape sends, do not count. The choice is saved with the session, so it holds across a daemon restart. If the daemon is not running, it starts, restores the sessions saved on disk, and opens one of them. With nothing saved, it opens a new session. A name that matches no session is an error unless you pass -c.

SIGINT or SIGTERM ends a client even when its terminal stopped reading, for example after a killed SSH connection. The client asks for a normal quit first. If the quit does not finish within 3 seconds, the client exits. A second signal makes it exit at once. A forced exit puts the terminal mode back, tries to reset the screen, and exits with 128 plus the signal number. If the screen stays wrong, run reset. The session keeps running in the daemon. tuios new, tuios --standalone and tape play do the same.

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 "Another client attached to this session." To do this on every attach, set single_client = true in [daemon]. See One client for each session.

With ssh_agent = "follow" in [daemon], attach points the ssh agent link of the session at the SSH_AUTH_SOCK of this client. See SSH Agent.

With display = "follow" in [daemon], the default, attach sends the display of this client. A daemon with no display of its own gives it to the new panes of the session. See display-env.

Attach from inside a pane

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 names no session.

• To show a different session in the pane, name that session.
• To attach the same session, open a terminal outside TUIOS.
• To attach anyway, use --force or set TUIOS_ALLOW_NESTED=1.

The same refusal applies to a chain. For example, session A shows session B in a pane, and a pane of B then attaches A. See Nested attach for how TUIOS finds the pane.

To move the client that shows the pane to a different session, use switch-session.

switch-session Added in v0.9.0

Switch an attached client to a different session, in place. This is what the session switcher does. Nothing is nested.

tuios switch-session [HOST:]NAME [flags]

• -s, --session <name>: switch the client that shows this session.
• --client <id>: switch the client with this id, from tuios 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: print the result as JSON.

The command switches one client: the client that --client names, else the client that shows the -s session, else, from a pane or a popup, the client that shows the pane's session, else the only client that is attached. With more than one client, name one.

HOST is a machine from the [hosts] table. 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. From a pane, the command needs the admin grant.

tuios switch-session api                           # from a pane: show the session api
tuios switch-session --create --cwd ~/dev/api api  # make api in ~/dev/api if it is missing
tuios switch-session build:api                     # the session api on the host build
tuios switch-session -s work api                   # from outside: switch the client that shows work

See Sessionizer for a key that opens a project.

ls

List sessions. Alias: list-sessions.

tuios ls [flags]

• --json: print JSON.
• --all-hosts: also list every machine in the [hosts] table.
• --host <name>: list one machine. local means this one.

The table shows name, window count, status, creation time and last activity. --json prints a bare array:

[
  {
    "name": "work",
    "id": "04623592-051c-49d5-9a29-69a2e2ccdb33",
    "created": 1790101795,
    "last_active": 1790101795,
    "window_count": 1,
    "attached": false,
    "width": 80,
    "height": 24,
    "windows": [
      { "id": "bef3bdc3-2b99-4bf5-9499-b1d3aabb7f9c", "title": "Terminal bef3bdc3", "workspace": 1 }
    ],
    "current_workspace": 1,
    "dir": "tuios",
    "branch": "main"
  }
]

• created and last_active are Unix seconds.
• dir is the base name of the focused pane's directory (~ for home). branch is its git branch. Both are omitted when unknown.
• display_name, accent and restored appear only when set. So does space.

When a session is in a space, the table is one table for each space, under the name of the space. The sessions in no space come last. --json stays one flat list.

With no daemon running, ls lists the sessions saved on disk, marks each saved ("saved": true in JSON), and exits 3.

A session with a label, set by set-session-name, shows in the table as name (label). The name field in JSON stays the real name; display_name carries the label.

With --all-hosts or --host, the JSON is an object with a hosts array. Each entry has host, status and sessions. A host that does not answer gets a row saying so and does not fail the command.

list-clients Added in v0.9.0

List every connection to the daemon: its client id, its process id and its session.

tuios list-clients [--json]

[
  {"client_id": "client-1790941960197517900", "pid": 4242, "session": "work"}
]

• session is empty while the connection is not attached.
• The list includes the connection of list-clients itself.
• pid comes from the kernel. It is 0 on Windows and the BSDs.
• For an SSH or web client, pid is the local server process, not the remote SSH process or the browser.

To follow changes, run tuios subscribe --types client-session-changed. Each event carries client_id, pid, session and attached. attached is true when a client enters a session and false when it leaves or disconnects. A session rename sends one event with the new name for each client in the session.

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."

tuios detach-client [--client ID | --session NAME] [--all-other] [--json]

• --client <id>: detach the client with this id, from tuios 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: print the ids of the detached clients.

The command detaches the first of these that applies:

1. The client that --client names.
2. Every client of the session that -s names.
3. From a pane, the client used last in the session of the pane.
4. 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 pane-grants.

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

{"detached":["client-1790941960197517900"]}

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.

tuios ssh-agent-path [-s NAME] [--json]

• -s, --session <name>: the session whose link to print. In a pane, the default is the session of the pane. Outside a pane, -s is required.
• --json: print JSON, with follow and the socket that the link points at (target).

Without --json, the command fails when ssh_agent is not "follow". A shell that started before you set the option 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"

See SSH Agent.

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 The display of the client.

tuios display-env [-s NAME] [--json]

• -s, --session <name>: the session whose display to print. In a pane, the default is the session of the pane.
• --json: print JSON, with follow, own, the Wayland link, 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)"

resurrect Added in v0.8.0

Restore a session saved on disk. Alias: restore.

tuios resurrect               # list what can be restored
tuios resurrect work          # restore it and attach

The daemon restores saved sessions when it starts, so you need this only after tuios daemon --no-restore, or to bring back one session on demand. Each window gets a fresh shell in its saved directory. Running programs and scrollback are not restored. See Session Resurrection.

rename-session Added in v0.8.2

Rename a session.

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

• -s, --session <name>: the session to rename. Default: the session of the pane you run it in.

tuios rename-session test work   # rename another session
tuios rename-session work        # rename the session of this pane

The new name is what tuios ls, attach and -s use, and what new panes get as TUIOS_SESSION. Panes that already run keep the old name, and TUIOS commands from them still reach the session. attach and kill-session with the old name fail and name the new one. The rename also clears a label set with set-session-name.

A name that another running or saved session has is refused, and so is an empty name or one with a slash or a control character. The rules of new for dots and device names apply too.

kill-session

Close every window in a session and disconnect its clients.

tuios kill-session <session-name>

kill-server

Stop the daemon and every session in it.

tuios kill-server

The command waits until the daemon has saved every session and removed its socket, so you can start a new daemon as soon as it returns. It fails if the daemon has not stopped within 10 seconds. Sessions are restored when the next daemon starts. To start clean, use tuios daemon --no-restore. With no daemon running, it removes a stale socket if there is one and exits 0.

--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. restart-server passes it.

restart-server Added in v0.11.0

Stop the daemon and start it again with the newest tuios installed. Use it after an update.

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 restart

• It lists the programs that stop, by pane and session, and the agents that can resume, then asks. Without a terminal it refuses unless you give --yes.
• The new daemon runs the newer of two binaries by --version: the tuios at this command's path, and the tuios on PATH.
• --json writes one object per step: plan, stopping, starting and done. It needs --yes.
• --expect DIGEST refuses the restart unless the plan has that digest.
• Attached clients on this machine wait up to 15 seconds and attach again by themselves.

See Restarting the Daemon.

daemon

Run the daemon in the foreground, for debugging.

tuios daemon [flags]

• --log-level <level>: off (default), errors, basic, messages (all protocol messages except PTY I/O), verbose (including PTY I/O), or trace (full hex dumps).
• --no-restore: do not restore saved sessions on start.

tuios daemon --log-level messages

tuios start-server starts the daemon in the background with no session. It is hidden from --help because commands start the daemon on their own.

daemon upgrade Unreleased

Move the running daemon to another tuios binary, and keep every program in its pane. Experimental, macOS and Linux only. See Upgrade in place.

tuios daemon upgrade [--binary PATH] [--json]

• --binary <path>: the tuios binary that the daemon runs next. Default: the tuios that runs the command.
• --json: print the result as one JSON object.

The command refuses a binary that neither you nor root owns, or one that its group or other users can write. It exits 1 with upgrade_refused, and nothing changes, when the daemon:

• runs on Windows, or inside another program (tuios-web, the SSH server),
• holds a pane for another machine, or a window whose process runs on another machine,
• runs a tuios fan verify check, or a popup with capture_stdout.

A second upgrade while one runs is refused as busy. From a pane, the upgrade waits for a person to choose Yes in a dialog on an attached client. No, Esc or 60 seconds without an answer refuses it with forbidden. A daemon from before live upgrades answers unknown_verb. Run tuios restart-server for it.

logs

Print the daemon's log.

tuios logs [flags]

• -n, --lines <n>: entries to show. Default 50. 0 shows all.
• --all: show every stored entry.
• -f, --follow: keep printing new entries.
• --clear: empty the log after printing it.

The daemon keeps the last 1000 entries in memory. It also appends errors and basic events to $XDG_STATE_HOME/tuios/daemon.log, so a crash leaves a record. To log more, run tuios set-config daemon.log_level messages. The levels verbose and trace also record pane content, titles and paths.

Worktrees

worktree Added in v0.8.0

Run a session in a git worktree. The rail groups these sessions under their repository and labels each with its branch.

tuios worktree new <branch> [flags]
tuios worktree ls [flags]
tuios worktree rm <session> [flags]
tuios worktree diff <session> [--stat]
tuios worktree pull <host:session> [flags]

worktree new creates a worktree and a session in it. A branch that does not exist is created from --base, or from HEAD. The session is named <repo>-<branch>, with slashes turned into hyphens. Worktrees go under $XDG_DATA_HOME/tuios/worktrees/<repo>/<branch>.

• --repo <dir>: a directory inside the repository. Default: the current directory.
• --base <ref>: the ref a new branch starts from. Default: HEAD.
• --name <session>: the session name.
• --agent <cli>: start an agent CLI instead of a shell, such as claude, codex or gemini.
• -d, --detach: do not attach.
• --host <name>: make the worktree on a machine from the [hosts] table, in its checkout of this repository. --clone clones it there when the host has none.
• --json: print JSON.

worktree ls lists worktree sessions with their repository, branch, agent state, uncommitted changes and fan prompt status. A row marked gone is a session whose worktree was deleted. Filter with --repo <name> or --group <stem>.

Added in v0.10.0 The MERGED column shows into <ref> when the branch is merged. A branch is merged when it has commits of its own, and a merge 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. --json gives merged and merged_into. TUIOS does not remove a merged worktree. Use worktree rm.

worktree rm runs git worktree remove and kills the session. It refuses a worktree with uncommitted changes and removes nothing. --stash keeps the changes in git stash, and --force discards them. --keep-session leaves the session running. The branch is never deleted.

worktree diff prints the commits the session made on top of its base, then its uncommitted changes, then its untracked files. --stat prints the summary form.

worktree pull <host:session> copies what a worktree session on another machine has done into a new worktree session here: its commits as a new branch, and its uncommitted work, untracked files included, applied uncommitted. --branch names the branch here, --name the session, --repo the repository, and -d does not attach. A branch that already exists here is refused.

tuios worktree new feat/retry --base main --agent claude --detach
tuios worktree ls
tuios worktree rm api-feat-retry --stash

fan Added in v0.8.0

Start the same prompt in several agents, each in its own worktree.

tuios fan <count> <prompt> --agent <cli> [flags]
tuios fan compare <session> [--no-changes]
tuios fan verify <session> -- <command>...
tuios fan diff <session-a> <session-b> [--stat]
tuios fan keep <session> [--stash | --force] [--merge [--squash | --ff-only] [--into <branch>]]
tuios fan verdict <session> --pick <session> --summary <text> [--reason <text>]... [--note <session>=<text>]...

• --agent <cli>: the agent to run, as you type it, arguments included. Several, comma-separated or repeated, are cycled across the sessions. Required.
• --prompt <text>: one session's prompt. Repeat it once per session instead of one prompt for all.
• --env NAME or --env NAME=VALUE: pass a variable to every agent. PATH is always sent.
• --base <ref>: the ref every branch starts from. Default: HEAD.
• --name <stem>: the branch stem, which is also the fan's name. Default: fan/ and the first words of the prompt, moved on to a free name such as -2 after it. A name can have only plain letters, digits and / . _ -. A name that is already a fan in the repository is refused with fan_exists.
• --join <session>: add the attempts to the fan of this session, instead of starting a new fan. Your pane must reach that session. A fan is never joined by giving the same name.
• --repo <dir>: a directory inside the repository.
• --grants <list>: what every agent may do through TUIOS. See pane-grants.
• --host <name>: run the fan-out on a machine from the [hosts] table. --clone clones the repository there when it has none.
• --wait: return only when every prompt is sent or given up on.
• --json: print JSON.

The branches are the stem, then stem-2, stem-3 and so on. Each prompt is typed once its agent is ready. tuios worktree ls --group <stem> shows whether each one was sent.

An agent that has not shown its prompt after 30 seconds puts a question in the Inbox asking you to look at its pane.

fan compare prints one line per attempt: its agent and state, the files and lines it changed against the fan's base, and its last check. fan verify runs a command in every attempt, in a window named verify, and exits 1 if any check failed. --timeout counts a slow check as failed, and --no-wait returns once the checks start. fan diff shows what the second attempt did differently from the first.

fan keep keeps one session and removes the others with the same stem, the way worktree rm does. A sibling with uncommitted changes is left in place unless you pass --stash or --force. HOST:SESSION works with compare, verify and keep.

fan keep --merge first merges the kept session's branch into its base in the main checkout, as ship merge does. --squash, --ff-only and --into <branch> choose how. When the merge conflicts or is refused, it is undone and no sibling is removed.

fan verdict Added in v0.11.0 records which attempt a judge recommends, and why. The agents view shows the verdict on the fan's row and in its comparison, where you keep an attempt. --pick and --summary are required. --reason and --note SESSION=TEXT can repeat. A new verdict replaces the last one. Only the judge that j in the agents view started, or a call from outside every pane, records a verdict. It keeps and removes nothing. See Fans, compare and judge.

tuios fan 3 --agent claude 'Add a retry with backoff to the HTTP client.'
tuios fan compare api-fan-add-a-retry-with
tuios fan verify api-fan-add-a-retry-with -- go test ./...
tuios fan keep api-fan-add-a-retry-with-2 --stash
tuios fan keep api-fan-add-a-retry-with-2 --merge --squash

See Worktrees.

ship Added in v0.9.0

Take an agent's work from its worktree to a merged change.

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

Every subcommand takes -s, --session, -w, --window and --json.

• commit stages every change in the pane's work tree, untracked files included, and commits it on its branch. Without -m, the message is the pane's last prompt. --force commits while the agent is working or waiting on a prompt.
• merge merges the branch into its base in the main checkout. A merge that conflicts is undone, and the command lists the files.
• push pushes the branch and sets its upstream. A push is never forced.
• pr pushes the branch and opens a pull request with your own gh login.
• status shows the pull request and its checks. --refresh asks gh now.

git uses your own identity, signing setup and hooks. From inside a pane, git runs with no hooks, and with no program that only the repository's own config names. push and pr show what they will send and ask [y/N] first. -y, --yes skips the question. Inside a TUIOS pane, they also need your yes in the Inbox. --wait sets how long to wait for it (default 2m).

The pull request and its checks show on the agent's row in the rail, in tuios worktree ls, and as pr in ls --json and worktree ls --json.

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

See Ship.

Remote control commands

The commands below drive a running session from a script or another pane. They are a thin layer over the daemon's JSON control protocol. For more than a few calls, or to get structured errors and blocking waits, use the protocol directly. tuios --skill prints a guide to this surface for agents.

Most of them work on a detached session. The ones that need an attached client say so.

Windows and workspaces

new-window Added in v0.8.0

Open a window and print its ID and name.

tuios new-window [name] [command...] [flags]

• --workspace <n>: the workspace to open it on. Default: the workspace of the pane that runs the command, else the one the session shows.
• --cwd <dir>: the starting directory. Default: the daemon's.
• --no-focus: leave the focus where it is.
• --host <name>: run the window's process on a machine from the [hosts] table. The window still belongs to this session.
• --grants <list>: what the window's process may do through TUIOS: read, write, fan, respond, admin, or none. See pane-grants.
• --print-id: print only the full window ID, for id=$(...).
• --json: print JSON.

Words after the name are a command the window runs instead of a shell. They are passed as they are, with no shell in between. Put -- before a command that has flags of its own, or tuios reads them as its own flags. The window closes when the command exits.

tuios new-window build                      # prints: e0657732  build
tuios new-window top htop                   # run htop with no shell
tuios new-window logs -- tail -f /var/log/system.log
tuios new-window tests --workspace 2 --cwd /src/api --no-focus
tuios new-window --json | jq -r .window_id

split-window Added in v0.8.0

Split a pane and print the new pane's ID. Needs an attached client with tiling on.

tuios split-window <horizontal|vertical|left|right|up|down> [flags]

horizontal and vertical put the new pane below or to the right. Added in v0.10.0 left, right, up and down name the side of the pane that the new pane takes.

• -w, --window <target>: the pane to split.
• --name <name>: a name for the new pane.
• --json: print JSON.

popup Added in v0.8.0

Run a command in a floating pane over the layout. The pane closes when the command exits. Needs an attached client.

tuios popup [flags] -- <command> [args...]

• --width <size>: cells, or a percentage of the pane area. Default 80%.
• --height <size>: cells or a percentage. Default 60%.
• --wait: stay open until the command exits, and exit with its status. --timeout <ms> bounds the wait.
• --capture-stdout: print the command's standard output here instead of in the popup. Implies --wait. Not on Windows.
• --dim <percent>: dim the screen behind this popup by 0 to 90 percent. Without it, the popup follows appearance.popup_dim Added in v0.11.0, which is 0 by default. --dim 0 turns the dim off.
• --name <name>, --cwd <dir>, --workspace <n>, --json.

The size flags have no short form, because -w means window and -h means help. A picker such as fzf draws on the terminal and prints only the choice, so with --capture-stdout the choice is what this command prints.

file=$(tuios popup --capture-stdout -- fzf)
tuios popup --wait -- gum confirm "Deploy?" && ./deploy.sh
tuios popup --width 90% --height 80% -- htop
tuios popup --dim 30 -- gum choose one two three

xpanes Added in v0.8.3

Open one pane per item in a new tiled workspace, and turn multifocus on for all of them. Then the keys you type go to every pane. This is like tmux-xpanes.

tuios xpanes [flags] [items...]
command | tuios xpanes [flags]

The items are the arguments. With no arguments, TUIOS reads one item from each line of stdin, when stdin is not a terminal. TUIOS ignores empty lines.

• -c, --command <cmd>: the command for each pane. TUIOS replaces {} with the item, in shell quotes.
• -s: speedy mode. The pane runs the command with sh -c, with no interactive shell, and stays until you press Enter.
• -ss: speedy mode. The pane closes when the command stops.
• --interval <seconds>: the time to wait between the panes, for example 0.5.
• -I, --replace <text>: the text that TUIOS replaces with the item. Default {}.
• --ssh: run ssh with the item in each pane. The same as -s -c 'ssh -- {}'. The -- makes sure that ssh does not read an item that starts with - as an option.
• -l, --layout <name>: tiled, even-horizontal or even-vertical, or t, eh and ev. Default tiled.
• -n, --items-per-pane <n>: the number of items for each pane. TUIOS joins them with spaces.
• --no-sync: do not turn multifocus on.
• --workspace <n>: the workspace for the panes. It must be empty. Default: the first empty workspace.
• --session <name>: default: the session of this pane, else the most recently active. It has no short form, because -s is speedy mode, as in tmux-xpanes.
• --force: open more than 64 panes.
• --json: print the result, with the window ids, as JSON.

Each pane starts a shell. With -c, TUIOS types the command into the shell, and the shell stays when the command stops, as in tmux-xpanes. With -s, the pane runs the command with no shell. When the command stops, the pane shows "The command stopped. Press Enter to close the pane." With -ss, the pane closes when the command stops. With --interval, TUIOS waits between the panes: between opening them with -s or -ss, and between typing the commands without them. Without -c, each pane is a shell. In a session on another machine, the daemon there chooses the shell, and the pane does not get the two variables below. Each pane gets the item in TUIOS_XPANES_ITEM and its number, from 1, in TUIOS_XPANES_INDEX. The item is the name of the pane. The panes start in the folder where you run tuios xpanes.

The layout and multifocus need a client attached to the session. The layout also needs tiling on and the bsp layout. When TUIOS cannot do one of them, it opens the panes and tells you what it did not do.

tuios xpanes --ssh host1 host2 host3
printf 'a\nb\nc\n' | tuios xpanes -c 'echo {}'
tuios xpanes -ss --interval 1 -c 'curl -s https://{}/health' web1 web2 web3
ls /var/log/*.log | tuios xpanes -l even-horizontal --no-sync -c 'tail -f {}'
tuios xpanes -n 2 -c 'diff {}' a.txt b.txt c.txt d.txt

close-workspace Added in v0.8.3

Close every pane on a workspace, like tmux kill-window. Without a number, TUIOS closes the panes of the current workspace.

tuios close-workspace [-s session] [workspace]

Scratch panes stay open. To close a scratch group, name its scratch workspace. A pane that runs this command needs the admin grant. The close_workspace action does the same from the keyboard. See Close every pane on a workspace.

tuios close-workspace 2

focus-window Added in v0.8.0

Move the focus and print the pane that has it. Pass exactly one of a window, --relative or --direction.

tuios focus-window build
tuios focus-window --relative next     # next or prev on this workspace
tuios focus-window --direction left    # left, right, up or down

Naming a window switches to its workspace. --direction needs an attached client.

pip Added in v0.8.3

Pin a pane as the picture-in-picture view of the attached client, or unpin it.

tuios pip agent        # pin the pane named agent. Name it again to unpin it
tuios pip              # pin the focused pane
tuios pip --off        # unpin whatever is pinned

The view belongs to the client, not to the session, so the command needs an attached client. --json prints pinned and window_id.

pane-view Added in v0.9.3

Show one pane in this terminal, with no tuios around it.

tuios pane-view -w <window> [flags]

The pane's output goes to this terminal as it is. What you type goes to the pane, Ctrl-C included. A terminal that draws its own panes, such as Tern, runs one pane-view for each tuios pane. Each pane then gets the terminal's own scrollback, selection and search.

pane-view does not attach. It reads the pane through stream-pane, so the clients of the session do not change. The daemon answers the requests that a program sends to its terminal. pane-view keeps these requests from the outer terminal, which would answer them a second time.

• -s, --session <name>: the session. Default: the session of this pane, else the most recently active.
• -w, --window <window>: the pane to show, by ID or name.
• --size follow|pane: whether the pane takes the size of this terminal. Default: follow.

With --size follow, the pane takes the size of this terminal while no tuios client shows the session. With several viewers, the largest decides. When the last viewer leaves, the pane goes back to its own size. While a client shows the session, the pane only gets smaller to fit this terminal. With --size pane, the pane keeps its size and only gets smaller. The daemon makes these decisions, so a client that attaches or detaches, or a rename, changes the size at once.

At start, pane-view asks this terminal for its colours and graphics, and tells the daemon. While no tuios client shows the session, a program in the pane can ask for these (OSC 10, 11 and 4, DA1, the kitty graphics query). It gets the answers of this terminal.

Close the terminal to stop viewing. The pane and its session keep running. After a daemon restart, pane-view resumes on the new daemon.

Exit status:

tuios pane-view -s work -w build              # show the pane named build of the session work
tuios pane-view -s work -w build --size pane  # keep the size that the session gives the pane

move-window Added in v0.8.0

Move a window to another workspace, or to another session.

tuios move-window [workspace] [-w <target>] [--to-session <name>] [--follow] [--json]

--follow switches to that workspace after the move.

Added in v0.10.0 --to-session <name> moves the window to another session. The program in it keeps running, and the window keeps its id and its scrollback. The workspace is optional then: without it, the window goes to the workspace that session shows. A popup, a scratch pane and a pane on another machine cannot move.

tuios move-window -s work -w build --to-session review

set-window Added in v0.8.0

Rename, minimize or restore a window. Pass only the flags you want to change.

tuios set-window --name "api tests"
tuios set-window -w build --name ""      # clear the custom name
tuios set-window -w build --minimize
tuios set-window -w build --restore

set-layout Added in v0.8.0

Turn tiling on or off, reset split ratios, or flip the focused split. Needs an attached client.

tuios set-layout --tiling true
tuios set-layout --equalize
tuios set-layout --rotate

Workspaces and labels

tuios set-workspace-name 2 review
tuios list-workspaces --json | jq '.workspaces[] | select(.window_count == 0)'

Input and output

send-keys

Send keystrokes to a session.

tuios send-keys <keys> [flags]

• -w, --window <target>: the target window.
• -l, --literal: write the text to the pane's PTY with no key parsing.
• -r, --raw: send each character as a key. Do not split on spaces or commas.
• -N, --repeat <n>: send the whole sequence this many times, 1 to 1000.
• --allow-blocked: from a pane, send keys into a pane that waits on a prompt. Read the prompt first.

With -w, the keys go to that window's program, whether or not a client is attached and whichever window has the focus. Without -w, they go to the attached client as if you pressed them, so window-mode bindings and the prefix work. With no client attached, they go to the focused window. The command prints where the keys went.

• Single keys: i, Enter, Escape, Space, Tab, BTab, Backspace, Insert, Delete, arrows (Up and so on), Home, End, PageUp, PageDown, F1 to F12. The arrows, Home and End go in their SS3 form (ESC O H) when the program in the pane has turned on application cursor keys (DECCKM), as a real terminal sends them.
• Chords: ctrl+c, alt+b, shift+Up. Not case sensitive. tmux's C-c and M-x, and ^C, work too.
• A named key or a chord goes in the keyboard mode the program in the pane asked for. TUIOS encodes it the same way as a key you press. A program that asked for the kitty keyboard protocol or modifyOtherKeys gets that encoding. For example, Vim with the kitty keyboard protocol gets ctrl+h as ESC [ 104;5u, not as Backspace. A shell gets 0x08. Text, --literal and --raw keys are not changed.
• An escape sequence written as \e[A, \x1b[A or \033[A.
• Sequences: separate keys with a space or a comma: "ctrl+b q" or "ctrl+b,q".
• PREFIX and $PREFIX expand to your leader key, without -w and with a client attached. In bash and zsh, use single quotes so the shell does not expand $PREFIX first: tuios send-keys 'PREFIX q'.

From inside a pane, send-keys works differently:

• -w is required. Without it the command is refused, because the focused pane may not be the one you mean.
• A pane that waits on a prompt (needs_input) is refused with agent_blocked, because the keys would answer the prompt. To answer it on purpose, pass --allow-blocked. This also needs the respond grant.
• send-keys with PREFIX is refused. The message names the TUIOS command to use instead, such as focus-window, new-window or split-window.
• The Inbox does not take an answer that send-keys typed.

You, outside every pane, are held to none of these rules.

A word that looks like a misspelled key, such as Dwon or F13, is refused with the list of names, and nothing is sent. To type text, use send-text: send-keys splits on spaces, so 'echo hello' types echohello.

tuios send-keys i                          # enter terminal mode
tuios send-keys 'PREFIX d'                 # detach the attached client
tuios send-keys -w docs Down --repeat 10   # scroll a pager
tuios send-keys -w build ctrl+c
tuios send-keys -w build --literal --raw "make test"
tuios send-keys -w build Enter

send-text Added in v0.8.0

Write text to a pane exactly as given. Nothing is parsed. End the text with a newline to run it.

tuios send-text -w build 'go build ./...
'
tuios send-text -w build 'partial input'         # type without running
printf 'go test ./...\n' | xargs -0 tuios send-text -w build

• -w, --window <target>: the target pane. Required from inside a pane.
• --allow-blocked: from a pane, type into a pane that waits on a prompt. Read the prompt first.
• --json: print the result as JSON. Without it the command prints nothing, and a failure exits 1.

From inside a pane, send-text follows the rules of send-keys: -w is required, and a pane on needs_input is refused unless you pass --allow-blocked. The error names the command that reads the prompt:

send-text failed: window 609d5afd is waiting on an approval, and text
typed now would answer it: approve Bash: make.
Most likely cause: Nothing was typed. Read the prompt with peek-prompt.
Tell the person which pane waits, with tuios ask-human. To answer the
prompt yourself, pass --allow-blocked.
Fix: run 'tuios peek-prompt -s work -w 609d5afd'.

run Added in v0.9.0

Type one command line at a pane's shell prompt, wait for it to finish, print what it printed, and exit with its exit status.

tuios run -w build --timeout 600000 -- go test ./... && echo passed
tuios run -w build --lines 40 -- make
tuios run -w build --json -- make lint

• --lines <n>: keep only the last n lines of the output.
• --timeout <ms>: how long to wait. Default 30000. A timeout does not stop the command, and the error names the wait-for command that picks it up.
• --json: print JSON with the output, the exit code and how long it took.

run reads where the command starts and ends from the shell's OSC 133 marks, so the pane's shell needs prompt integration. A pane whose shell sends no marks is refused with no_shell_integration, and a pane already running a command with not_at_prompt. Nothing is typed in either case. tuios doctor shell says which panes have the marks and prints the lines that turn them on for zsh, bash and fish.

The words after -- are joined with spaces into one line that the shell parses, so quote them as you would when typing.

capture-pane Added in v0.8.0

Print a pane's content.

tuios capture-pane [flags]

• -w, --window <target>: the pane.
• -S, --scrollback: include the scrollback, not only the screen. Without --lines, the capture keeps the last 3 commands in at most 2000 lines.
• --commands <n>: keep the last n commands of the scrollback, in at most 2000 lines. It needs the shell's OSC 133 marks. It does not take --lines, --last-command or --unwrap.
• --lines <n>: keep only the last n lines. 0 keeps all.
• --unwrap: join the rows that the pane wrapped, so each line comes back as the program wrote it.
• --trim: drop the blank lines at the end.
• --ansi: keep colour and style escape codes.
• --resolved: rewrite indexed colours to 24-bit RGB, so the capture matches what a themed client draws.
• --palette <colours>: 16 comma-separated #rrggbb colours for --resolved. Default: the xterm colours.
• --last-command: only what the last finished command printed. Needs a shell with OSC 133 marks, like run.

tuios capture-pane -w build --scrollback              # the last 3 commands
tuios capture-pane -w build --commands 10             # the last 10 commands
tuios capture-pane -w build --scrollback --lines 40   # the tail of a build
tuios capture-pane -w build --scrollback --lines 0    # the whole history
tuios capture-pane --ansi > pane.txt

--lines counts from the last line with content, so blank rows below the cursor do not count.

On a window that shows a TML surface, capture-pane prints the surface as drawn, at the window's size, with its state and the open tab.

A history holds 10,000 lines or more, which is too much for an agent to read. So --scrollback without --lines keeps the last 3 commands. It finds them by the shell's OSC 133 marks: each command runs from its prompt to the next prompt. The capture keeps at most 2000 lines. A command whose output is too long keeps its command line, the start of its output and its end, and one line replaces the middle:

$ seq 1 3000
1
2
...
496
497
… 1,007 lines omitted …
1505
1506
...
2999
3000
$ echo two
two
$ echo three
three

The ... lines stand for rows left out of this page. The capture shows them.

A note on stderr says what the capture left out:

note: capture-pane shows the last 3 commands of 4. It left out 1,007 lines from the middle of their output. To get the whole history, use --lines 0.

A shell that sends no marks gives the last 2000 lines, and so does --unwrap. tuios doctor shell prints the lines that turn the marks on. With --json, lines_omitted gives the count, command_marks says whether the marks cut the capture, and commands gives the kept and omitted lines of each command. The capture also drops the blank rows below the cursor.

clear-history Added in v0.11.0

Clear the scrollback of a pane, as tmux clear-history does. The screen stays.

tuios clear-history                    # the focused pane
tuios clear-history -w build --screen  # the scrollback and the rows above the prompt

• -w, --window <target>: the pane. Default: the focused pane.
• --screen: also remove the rows above the prompt, as Cmd+K does in Ghostty and iTerm2. The prompt row moves to the top of the pane.
• --json: print the result as JSON.

The daemon clears the pane for every client of the session. An attach later does not bring the old rows back. tuios clears nothing while a full-screen program, such as an editor, uses the pane. The clear_scrollback action does the same as --screen for the focused pane. It has no default key. The tmux shim answers clear-history too.

screenshot Added in v0.8.0

Render a pane to an image file and print its path. The daemon renders it, so this works on a detached session.

tuios screenshot [flags]

• -w, --window <target>: the pane.
• -f, --format <fmt>: png, svg, ansi, html or txt.
• --frame <style>: window, plain or none.
• --theme <name>: render in this theme instead of the session's.
• -o, --out <path>: write here instead of a generated name under screenshot.directory.
• -S, --scrollback: put the scrollback above the screen.
• --lines <n>: limit the scrollback to the last n rows.
• --cursor: draw the cursor.
• --copy, --no-copy: try, or do not try, to copy the image to the clipboard.
• --json: print JSON with path, host, format, cols, rows, bytes, copied and warnings.

tuios screenshot -s work -w build
tuios screenshot --format svg --out demo.svg
tuios screenshot --theme catppuccin_mocha

The picture is drawn from the pane's cells, so colours, styles and links are exact. png and svg include the frame. ansi and txt do not. The [screenshot] config table sets the defaults.

With no theme set, basic colours use the xterm defaults, because only your terminal knows its real palette. The result warns about this. Pass --theme to render in a named palette.

Region and full-screen captures need an attached client: press Ctrl+B C in the TUI.

wait-for Added in v0.8.0

Block until a condition matches, then exit 0. The daemon watches its own events, so there is no polling.

tuios wait-for <condition> [flags]

• --pattern <regexp>: required by window-output.
• --new: for window-output, match only output that the pane writes after the wait starts. Text already on the screen or in the scrollback does not match.
• --until <states>: comma-separated states, required by agent-state.
• --any-session: for agent-state, watch every session.
• --select <selector>: for agent-state, watch the agent panes a selector matches, in every session. --every waits until every one of them is in an --until state.
• --command-seq <n>: for command-finished, match the first command after n finished ones. It matches at once when that already happened.
• --idle <ms>: silence that counts as idle. Default 500.
• --thread <id>: for agent-message, only this thread.
• --timeout <ms>: give up after this long and exit non-zero. Default 30000.
• --json: print JSON.

tuios wait-for window-output -w build --pattern 'BUILD_OK' --timeout 120000
tuios wait-for window-output -w build --pattern 'BUILD_OK' --new   # not the marker of the last build
tuios wait-for window-idle -w build --idle 2000
tuios wait-for agent-state -s work --until needs_input
tuios wait-for agent-state --select 'group:fan/add-retry' --until idle,done --every --timeout 3600000
tuios wait-for command-finished -w build --timeout 600000

subscribe Added in v0.8.0

Print the daemon's event stream, one JSON object per line.

tuios subscribe --types agent-state
tuios subscribe -s work --types window-created,window-closed
tuios subscribe --types bell --count 1
tuios subscribe --hosts --types agent-state,host-changed

• --types <list>: only these event types.
• -s, --session <name>: only this session. Without it, the stream covers every session, unlike most commands.
• -w, --window <id>: only events about this window.
• --count <n>: exit after this many events.
• --hosts: also the agent-state and session events of every linked host.
• --after-seq <n> and --boot-id <id>: resume after a disconnect. The first line is an ack carrying seq and boot_id. When the daemon cannot replay everything you missed, a gap line says why, and you should read current state again.

See Control Protocol for the event types.

Paste buffers

Read and change the paste buffers, as the tmux commands of the same names do. A yank in copy mode adds a buffer. The daemon keeps the buffers, so every client and session on this machine shares them. [paste_buffers] sets how many to keep.

tuios list-buffers [--json]
tuios show-buffer [-b <name>] [--json]
tuios set-buffer [-b <name>] [-a] [<text> | -] [--json]
tuios delete-buffer [-b <name>] [--json]
tuios paste-buffer [-b <name>] [-s <session>] [-w <window>] [-d] [-r] [--allow-blocked] [--json]

• -b, --buffer <name>: the buffer. The default is the newest buffer that TUIOS named, as in tmux. For set-buffer, the default is a new buffer named bufferN.
• -a, --append: set-buffer adds the text to the end of the named buffer. With no -b, it makes a new buffer, as in tmux.
• -s, --session, -w, --window: the pane that paste-buffer pastes into. The default is the focused pane.
• -d, --delete: paste-buffer deletes the buffer after the paste, unless the buffer was set again in the meantime.
• -r, --raw: paste-buffer keeps each line feed. Without it, each line feed becomes a carriage return, as in tmux.
• --allow-blocked: from a pane, paste-buffer pastes into a pane that waits on a prompt. Without it, such a pane is refused with agent_blocked.
• --json: print the result as JSON.

A buffer can hold any bytes, a binary file included. show-buffer prints the content and adds no line feed. set-buffer - reads the standard input. With no text on a terminal, set-buffer stops and says how to give the text. set-buffer with empty text stores nothing and exits 0, as tmux does. Input larger than 64 MiB is refused, and nothing is stored.

paste-buffer removes control characters. It uses the bracketed paste marks when the program in the pane turned them on. With a session on another machine, paste-buffer sends the text of a buffer from this machine.

From inside a pane, reading the buffers needs the read grant. Changing them needs write, and paste-buffer needs both. A buffer that a pane without admin sets is that pane's own, and such a pane reaches only its own buffers. It cannot make a named buffer. With no -b, your own commands take the newest of your own buffers, never one that a pane set. See Who owns a buffer.

tuios list-buffers
tuios set-buffer -b deploy 'kubectl rollout restart deploy/api'
tuios paste-buffer -b deploy -w ops
git log -1 --format=%H | tuios set-buffer

Inspection

These commands read the daemon's state and work with no client attached.

list-windows

List the windows in a session.

tuios list-windows [--json]
tuios list-windows --all [--all-hosts] [--text N] [--json]

The table shows index, ID prefix, name, workspace, size and agent state. * marks the focused window. The index and the ID prefix both work with -w.

--all lists the panes of every session on this machine, one row each. --all-hosts adds every session on each host in [hosts]. --text N adds the last N lines of each pane's screen, up to 200. These are the rows the pane navigator shows. Each row has session, host (with untrusted for another machine), workspace, workspace_name, window_id, name, title, command, cwd, focused, agent_state, and with --text, text or text_error. The text is read with capture-pane, under the same grants. Text from another machine is printed inside the untrusted fence.

{
  "success": true,
  "message": "command executed",
  "windows": [
    {
      "window_id": "15ff15b6-472e-4b22-b5e6-a709d82ded31",
      "index": 1,
      "title": "dev",
      "custom_name": "dev",
      "display_name": "dev",
      "workspace": 1,
      "focused": false,
      "minimized": false,
      "x": 0,
      "y": 0,
      "width": 80,
      "height": 24,
      "pty_id": "3f42acd9-5c9f-4f93-a2dd-c7af358cae33",
      "agent_state": "none"
    }
  ],
  "total": 3,
  "focused_index": 2,
  "focused_window_id": "e0657732-bf81-4636-8b24-6052f7ad76fe",
  "current_workspace": 1,
  "workspace_windows": [3, 0, 0, 0, 0, 0, 0, 0, 0]
}

• The ID field is window_id, and the focused window is focused_window_id.
• shell is the base name of the shell that a new pane in the session runs. foreground_cmd is not on a pane at its prompt, so shell says what that pane runs.
• custom_name appears only on renamed windows. display_name is always present.
• cwd appears when the shell has reported its directory.
• pid is the process the pane started, and tty is its terminal device. Both appear only for a pane whose process runs on this machine.
• zoomed: true marks a zoomed window. history_rows counts the scrollback lines above the screen.
• workspace_windows counts windows per workspace, starting with workspace 1.

get-window

Print one window. With no argument, the focused window.

tuios get-window [id-or-name] [--json]

The JSON is the same window object as in list-windows, merged into the top level next to success and message. There is no cursor position. To read the screen, use capture-pane.

session-info

Print the session's state.

tuios session-info [--json]

{
  "success": true,
  "message": "command executed",
  "session_name": "work",
  "session_id": "04623592-051c-49d5-9a29-69a2e2ccdb33",
  "display_name": "",
  "accent": "",
  "mode": "unknown",
  "current_workspace": 1,
  "num_workspaces": 9,
  "workspace_names": {},
  "workspace_order": null,
  "window_count": 3,
  "tiling_mode": "floating",
  "layout_mode": "unknown",
  "master_ratio": 0.5,
  "width": 80,
  "height": 24,
  "tui_attached": false
}

• tiling_mode is only tiling or floating. The layout name, such as bsp, is layout_mode, which is unknown when none is set.
• mode is always unknown. Do not use it.
• The theme and other options are not here. Read them with get-config.

list-verbs Added in v0.8.0

List the control protocol's verbs, with parameters, examples, error codes and the protocol version.

tuios list-verbs                 # every verb
tuios list-verbs capture-pane    # one verb
tuios list-verbs --json

These are kebab-case protocol verbs. They are a different set from the PascalCase run-command verbs. See Control Protocol.

call Added in v0.9.3

Send one verb to the daemon and print its reply as JSON.

tuios call <verb> [params]

params is a JSON object, or - to read it from standard input. Omit it for a verb that takes none. The reply is the daemon's result object as it is.

Use it from a program that can start a process but cannot write to the socket, such as a Tern plugin. The daemon checks the call as it checks any other call. A pane keeps its grants, and the verbs only the person may call stay refused from a pane. tuios list-verbs lists every verb.

call refuses the verbs that hold the connection open after their reply: subscribe (use tuios subscribe), stream-pane, open-file-stream, open-pane, pane-calls, link-peer and open-host-connection.

The call waits 30 seconds. If the verb has a timeout param, the call waits for that time in milliseconds and 10 seconds more. --timeout sets the wait.

• --pretty: indent the JSON.
• --json: print bad input and transport errors as JSON too, with the code invalid_input or transport.
• --timeout <duration>: how long to wait for the reply.

Exit status:

tuios call list-sessions                          # every session, as the daemon reports it
tuios call list-windows '{"session":"work"}'      # a verb with params
echo '{"session":"work"}' | tuios call list-windows -

run-command

Run one tape command in a session, or any keybinding action by its name. Tape commands use PascalCase names. Actions use the snake_case names that tuios keybinds list prints.

tuios run-command <command> [args...] [flags]

• --list: print every command.
• --json: print the result as JSON.

Some commands need an attached client, such as SetDockbarPosition, every action and Press. On a detached session they fail with a message saying so.

--json merges the command's result into the top level:

{ "success": true, "message": "command executed", "window_id": "459a7fc9-a1fd-4770-86ac-0bc60b9598b9", "name": "dev2" }

On failure the object is {"success": false, "message": "..."} and the exit code is 1. Check .success, not the message text.

tuios run-command --json NewWindow dev | jq -r .window_id
tuios run-command EnableTiling
tuios run-command -s work SwitchWorkspace 2

In scripts, prefer EnableTiling over ToggleTiling, so running the script twice gives the same result.

Configuration

config

tuios config path     # print the config file path
tuios config edit     # open it in $EDITOR
tuios config reset    # overwrite it with the defaults

tuios config apply    # apply config.toml to the running daemon now
tuios config browse   # search the options and set one, in an explorer

tuios config files              # list the files the config is read from, in merge order
tuios config origin [key]       # show which file sets each key
tuios config prune [--dry-run]  # remove the keys of config.toml that have their default value

config edit uses $EDITOR, then $VISUAL, then the first of vim, vi, nano and emacs it finds. config reset asks first. It writes the first-start config.toml again: comments, [startup] and no other setting. It keeps the include list and lists the other files that still apply.

config files lists the included files, the config.d files and config.toml, from lowest to highest precedence. It marks a read-only file. config origin names the file that sets each key, and the earlier files that set it too. Give a key to show that key and the keys under it. Both take --json.

config prune removes the keys of config.toml that have their default value. It lists the keys that another file sets, and asks before it changes the file. --dry-run changes nothing. --yes skips the question, and a run with no terminal needs it. The [startup] keys, the comments and the include list stay. See Split the Config.

config apply applies changes to config.toml that give panes or other machines more. The daemon applies a change that gives less at once. A change that gives more waits for config apply or a daemon restart. This covers [agents.permissions], [hosts] and link policies. Run config apply from a terminal outside TUIOS. It is refused from inside a pane. It prints each change that it applied. See Changes that wait.

set-config

Change an option in a running session. With a client attached, the client applies the value and writes it to config.toml. With no client attached, the daemon keeps the value for the session. The next client that attaches applies it and writes it to config.toml. The command prints Set PATH = VALUE. With no client attached, it also says on stderr that the value is not applied yet.

tuios set-config <path> <value>

tuios set-config appearance.border_style thick
tuios set-config appearance.sidebar.enabled true
tuios set-config daemon.log_level messages

A path is the option's dotted name, such as screenshot.format. An [appearance] option also answers to its bare name, so border_style works. An unknown path or value is refused, and the error lists what is accepted. Use list-options to find paths.

set-config cannot change [keybindings], [hooks], [hosts], [tailscale], [agents] or the [dock] lists. Edit the file for those.

get-config Added in v0.8.0

Read an option from a running session.

tuios get-config border_style
tuios get-config appearance.sidebar.position --json

An option with no session override reads as the value in config.toml, or as its default when no config file sets it. --json adds source (session, config or default) and default. Added in v0.10.0 A call over a host link does not read the file. On Omarchy with no theme set, appearance.theme reads omarchy.

list-options Added in v0.8.0

List every path set-config accepts, with type, default, accepted values and a description.

tuios list-options                        # everything
tuios list-options --section sidebar      # one group
tuios list-options appearance.sidebar.    # a path prefix
tuios list-options --search "pane bg"     # fuzzy search, best match first
tuios list-options --json | jq -r '.options[].path'

--search ranks every option by its path, its value and its description, the same search the settings page runs.

A session override is shown next to the default. The default of startup.daemon and startup.tiled is the one that applies on this machine: false when your config file has no [startup] table. Each JSON row has path, type, section, description and default, plus accepted, min, max, deprecated and session_value when they apply.

list-themes Added in v0.8.0

List themes, or show one theme's colours and their contrast against its background.

tuios list-themes --filter catppuccin
tuios list-themes catppuccin_mocha
tuios list-themes --json | jq -r .active

It reads the themes directory again on every call, so a new theme file shows up at once. Added in v0.10.0 On a machine with Omarchy, it also names the Omarchy theme it found, and says whether TUIOS follows it. Each installed Omarchy theme is in the list as omarchy/NAME.

import-theme Added in v0.8.0

Convert a kitty, Ghostty, Alacritty or WezTerm colour scheme into a TUIOS theme file.

tuios import-theme ~/.config/kitty/current-theme.conf
tuios import-theme ~/gruvbox.toml --name gruvbox
tuios set-config appearance.theme gruvbox

The format is detected from the content. Colours the scheme does not set use the xterm defaults. --name sets the theme id. The theme can be selected at once.

list-glyphs Added in v0.8.0

List glyph sets, or show what one set draws, role by role.

tuios list-glyphs
tuios list-glyphs heavy
tuios list-glyphs mine --json | jq -r '.problems[]?'

config browse [-s <session>] opens the options you can set in an explorer. Each option shows its type, default, current value and source. These are the values that list-options --json and get-config --json print. Press Enter on an option to set it. The explorer sets it the same way as set-config, with the same refusals and errors. It needs a running daemon.

See Glyph sets.

keybinds

Inspect and change keybindings. Aliases: keys, kb.

doctor and explain take --json and --guest <program>. Each finding in doctor has an evidence tier: certain (TUIOS routing), observed (read from a pane) or reference (a list of common program defaults).

unbind and free write the action as an empty list, so the default does not come back at the next load. free cannot take the leader key, which you move with keybindings.leader_key, or the few keys the input path reads directly. It says so instead of reporting success.

tuios keybinds explain alt+left
tuios keybinds free alt+left
tuios keybinds unbind close_window w

keybinds browse shows the rows of keybinds list --json. A search on the command line, such as tuios keybinds browse spotlight, starts the explorer with that search. See Explorers for the keys.

See Keybindings.

Dock and hooks

list-dock-components Added in v0.8.0

List the dock's components in draw order: side, source (builtin or custom), refresh mode, current text, and what the command last did. Needs an attached client.

tuios list-dock-components
tuios list-dock-components --json | jq '.components[] | select(.source=="custom")'

A component whose command fails is hidden from the dock. This command shows its exit code and error.

refresh-dock Added in v0.8.0

Run a dock component again now, whatever its refresh mode. With no name, run every component. It also clears a component that gave up after repeated failures.

tuios refresh-dock agents

Call it from a hook to update a cell when something changes:

[hooks]
after-agent-state = "tuios refresh-dock agents"

list-hooks Added in v0.8.0

List every hook in your config and what it last did: run count, last exit code, last run time and last error.

tuios list-hooks
tuios list-hooks --event after-agent-state
tuios list-hooks --json | jq '.hooks[] | select(.last_error != "")'

Zero runs means the event never happened. Check the event name. The SIDE column says which process runs the hook. Client-side hooks are listed only while a client is attached. See Hooks.

Agents

Panes running a coding agent can find each other, report state and exchange messages.

With [agents] enabled = false, the agent commands fail with the error code agents_disabled. See Turn off agent features.

list-agents Added in v0.8.0

List the panes identified as agents: state, harness, how it was detected, unread mail, and whether each is ready for a question.

tuios list-agents [flags]

• --all: list every window, not only agents.
• --all-sessions: list the agents of every session on this machine.
• --all-hosts: also list agents on every machine in the [hosts] table.
• --host <name>: list one machine. local means this one.
• --select <selector>: only the panes a selector matches, in every session unless -s is given. Over every session, the answer carries a confirm token for --select on send-agent-message and ask-agent.
• --json: print JSON.

tuios list-agents --select 'harness:codex state:idle,done'
tuios list-agents --json | jq -r '.agents[] | select(.state=="needs_input") | .window_id'

The states are needs_input, errored, done, idle, working and unknown. The JSON also carries needs_you, queued (messages waiting in the pane's queue), completion_seq, finished_unread, the agent's meta, identity and confidence (how TUIOS recognised the harness), evidence_age_ms, and subagents, the number of subagents the agent has at work. With --json, each row also has subagent_list: each subagent with its description, state, tool and how it ended. Added in v0.9.3 See Subagents. The ID and NAME columns work with -w. --session cannot be combined with --all-hosts or --host.

get-agent-state and set-agent-state

Read or report a pane's agent state.

tuios get-agent-state -w build --json
tuios set-agent-state working
tuios set-agent-state needs_input -w build -m "awaiting approval"
tuios set-agent-state none                  # clear it

Without -w, a report from a pane is about that pane. From outside every pane, it is about the focused pane. A pane reports only for its own window: a report about another pane needs the respond grant. This holds for set-agent-state, set-agent-meta, set-agent-session, report-agent-activity, ask-human and request-approval. A hook that tuios runs outside every pane reports for no pane. See Agent state from another pane.

set-agent-state takes none, working, needs_input, idle, done, errored or unknown, and these flags:

• -m, --message <text>: a short note shown with the state.
• --source <source>: report (default), osc, screen or stall.
• --harness <id>: the harness the state is about, such as claude-code.
• --kind <kind>: what a needs_input state waits for, approval or question. The Inbox groups it by this.
• --if-state <states>: apply only when the pane is in one of these states.
• --agent-session-id <id>: the harness's conversation id, stored for a later resume.

Sources are ranked in that order, highest first. A source cannot overwrite a state set by a higher-ranked source. A refused report prints why on stderr and changes nothing. The harness integrations report for you.

get-agent-state --json carries identity, confidence and evidence_age_ms: the milliseconds since the last evidence about the state arrived, or null for a pane that never had a state. It also carries subagents, the number of subagents the pane's agent has at work. See Agents.

set-agent-meta and set-agent-session

set-agent-meta records short facts about the agent in a pane, such as its model or how full its context is. The rail draws them on the agent's row. They never change the state.

tuios set-agent-meta -w "$TUIOS_PANE_ID" --source statusline --ttl 60s model=opus context=42%
tuios set-agent-meta summary=               # remove one key
tuios set-agent-meta --source statusline --clear

Keys are lower-case letters, digits, _ and -, and values are cut to 80 characters. --ttl drops the keys after that long. The metadata clears when the agent leaves the pane. tuios writes the keys now, prompt and subagents from the harness hooks. set-agent-meta refuses them, and --clear does not remove them.

set-agent-session <id> --harness <id> stores a harness's conversation id on a pane without changing its state, so the conversation can be resumed later.

start-agent Added in v0.8.0

Start an agent in a new pane, and return once it shows it is at its prompt.

tuios start-agent <agent> [-- args...] [flags]

• --name <name>: the pane's name, which list-agents shows and -w takes.
• --prompt <text>: a first prompt, typed once the agent is ready.
• -s, --session <name>: the session to open the pane in, created if it does not exist. HOST:SESSION starts it on another machine.
• --cwd <dir> or --repo <dir>: where it starts. Default: the focused pane's directory.
• --grants <list>: what the agent may do through TUIOS.
• --protocol acp|codex: run the agent headless over the Agent Client Protocol or the Codex app-server. The pane shows the conversation as a transcript you type into.
• --env, --focus, --workspace <n>, --ready-timeout <ms> (default 120000), --clone, --json.

tuios start-agent claude --name reviewer
tuios ask-agent -w reviewer 'review the diff on this branch'
tuios start-agent --protocol acp 'opencode acp' --name helper --prompt 'Summarise the TODOs.'

An agent that stops on a question of its own, such as whether to trust the folder, is not ready: the command says what it waits on and exits non-zero, and the pane is kept for you to answer.

send-agent-message Added in v0.8.0

Leave a message in another pane's inbox, or post a notice to the whole session. It does not type into the pane.

tuios send-agent-message <text> [flags]

• -w, --window <target>: the recipient. Omit it to post a session-wide notice.
• --from <id>: the sending window, normally "$TUIOS_PANE_ID".
• --subject <text>: a one-line summary, up to 120 characters.
• --attach <path>: an absolute path to a file. Repeat up to 8 times.
• --reply-to <id>: answer a message. The reply joins its thread.
• --select <selector>: send one message to every agent pane a selector matches, in every session. It lists the panes and sends nothing until you say yes, pass --yes, or pass --confirm with the token list-agents --select printed.
• --json: print JSON.

tuios send-agent-message -w build --from "$TUIOS_PANE_ID" 'rebased onto main, please retest'
tuios send-agent-message -w build --from "$TUIOS_PANE_ID" --reply-to 12 'retested, still green'

tuios tells the recipient that mail waits: the Claude Code and Codex hooks add one line to its context during a turn, and an agent at rest gets one line typed into its pane after 5 seconds. See How an agent hears about its mail. Messages are kept in memory: they are lost when the daemon stops, and the oldest are dropped when the queue is full.

read-agent-messages Added in v0.8.0

Read messages.

tuios read-agent-messages -w "$TUIOS_PANE_ID" --unread
tuios read-agent-messages --limit 50
tuios read-agent-messages --thread 12

• -w, --window <target>: read this pane's inbox and mark what it returns as read.
• --unread: only unread messages.
• --notices: include session-wide notices in an inbox read.
• --peek: do not mark anything read. A peek of your own inbox (-w "$TUIOS_PANE_ID") marks unread messages seen. Added in v0.9.3
• --thread <id>: one conversation. Any message ID in the thread works.
• --limit <n>: at most this many, newest last. Default 20.

Without -w, it reads every message and marks nothing. The last line says the state after the call, such as 1 message, marked read. The header of a message that its recipient peeked says seen, and --json has seen_at and read_at. See Unread, seen and read.

ask-agent Added in v0.8.0

Wait until an agent is not busy, type a question into its pane, wait for it to finish, and print what the pane showed.

tuios ask-agent -w review --from "$TUIOS_PANE_ID" 'does the retry path look right to you?'

• --from <id>: the asking window. Without it there is no loop detection.
• --ready-timeout <ms>: how long to wait for the target to stop working. Default 30000.
• --settle <ms>: for a pane that reports no state, silence that counts as done. Default 2000.
• --timeout <ms>: how long to wait in all, for the turn and for the answer. Default 300000.
• --lines <n>: cap the reply. Default 200.
• --force: send without waiting for the target to be ready.
• --stall-timeout <ms>: how long after Enter the target has to show it took the question. Default 5000. Past it the call fails with prompt_stalled.
• --allow-blocked: type at a target on needs_input. The text answers its prompt, so read the prompt first.
• --select <selector>, --yes, --confirm <token>: ask every agent pane a selector matches, at most 16, after confirmation.

Asks of one agent take turns, first come first served. A second ask waits for its turn, up to --timeout, and does not fail with not_ready. The JSON reply carries queued_behind and waited_turn_ms. An ask whose caller stops while it waits types nothing.

It refuses to type at an agent on needs_input (agent_blocked), since the question would answer its prompt, and it refuses an ask that closes a loop with one already in flight, so two agents cannot deadlock on each other.

ask-human Added in v0.8.0

Ask the person a question with fixed answers, wait for them to pick one, and print it.

answer=$(tuios ask-human 'Deploy to staging?' -o yes -o no) && echo "$answer"
tuios ask-human 'Which region?' -o us -o eu --no-wait
tuios ask-human --request-id 9f86d081884c7d65

• -o, --option <answer>: an answer, 1 to 9 of them.
• --timeout <ms>: how long to wait. Default 120000, at most an hour.
• --no-wait: ask and return at once. The answer arrives as mail.
• --request-id <id>: come back for a question already asked.

It exits 0 with the answer, 2 when there is no answer yet (the question stays, and the answer is mailed to the asking pane later), and 1 when the question ended without one. Only a person at an attached client can answer.

While a call from inside a pane waits, that pane shows needs_input with the question as its note. When the call returns, the pane shows its earlier state again. The question is one line of at most 160 bytes. For a longer question, the error tells you to send the details with tuios send-agent-message -w human first. See Questions an agent asks you.

Diagnosing detection

tuios explain-agent-detect -w build          # what the process detector saw
tuios explain-agent-screen --harness codex   # what a harness's screen rules make of the pane

explain-agent-screen --lines <n> reads that many lines from the bottom.

stash Added in v0.8.0

Copy a file into the session's store, so another agent can read it after you delete yours.

path=$(tuios stash put /tmp/flame.png)
tuios send-agent-message -w review --attach "$path" 'the hot path is in decode'
tuios stash list
tuios stash get -s build:api <stored-path> flame.png

• stash put <file>: the path must be absolute and readable by the daemon's user. Files are stored by content, so the same bytes return the same path. The limits are 16 MB per file and 256 MB per session. When a session is full, the oldest files that no message points at are removed.
• stash list: list stored files, oldest first. USED marks files a message still points at.
• stash get <stored-path> [file]: copy a file from a session on another machine. Up to 8 MB. On this machine, open the stored path directly.

Stored files last until the session is killed or the daemon stops.

Inbox and review

These commands read and act on the Inbox, the queue and the review. Acts that are yours alone, such as dismissing or snoozing an item, are in the TUI, not here.

list-attention Added in v0.8.0

List the Inbox: approvals and questions agents are blocked on, mail to you, errored agents, conversations to resume, and finished turns nobody has looked at, in every session and on every linked host.

tuios list-attention
tuios list-attention --kind approval --kind question
tuios list-attention --host build
tuios list-attention --select 'harness:codex group:fan/add-retry'
tuios list-attention --json --kind approval | jq -r '.items[0].window'

• --kind <kind>: only these kinds: approval, plan, ask, question, mail, errored, resume, finished, outbox.
• --host <name>, -s, --session <name>: only this machine or session.
• --select <selector>: only the items a selector matches.
• --snoozed: also list the items you snoozed, with when each opens again.

tuios subscribe --types attention streams every change.

peek-prompt and respond

Read the prompt an agent is blocked on, and answer it, without attaching.

tuios peek-prompt -w review
tuios respond -w review --prompt-id 75f8b9fadb5b5dfc approve
tuios respond -w review choose 2
tuios peek-prompt -w buildbox:api:review --json

respond takes approve, approve_always, deny, choose <n> or text <answer>, whichever the prompt offers. Pass the --prompt-id that peek-prompt printed, so an answer never lands on a prompt you have not read. The daemon reads the prompt again first and refuses with prompt_changed if it moved on. --timeout <ms> (default 5000) is how long it waits for the pane to move on.

Answering a prompt is acting as you. respond works from a shell outside every pane only when [daemon] respond_from_shell = true is set in the config file. A program in a pane is refused with not_human, unless the pane holds the respond grant.

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. After a daemon restart they come back with every holder let go. See The task board.

tuios task add [-p PROMPT] [--stage STAGE] TITLE...
tuios task ls [--stage STAGE] [--open] [--all-sessions]
tuios task get ID
tuios task claim ID | --next [-w WINDOW]
tuios task done ID
tuios task stage ID STAGE
tuios task block ID REASON... | --clear
tuios task release ID
tuios task rm ID

• The stages are todo, plan, doing, verify, review, shipped and done. claim moves a card in todo or plan to doing. done moves it to done and lets it go.
• -s names the session. The default is this pane's session, else the most recently active.
• -p takes at most 16 KiB. - reads it from standard input.
• claim --next takes the oldest open card. A card that a pane holds, a blocked card, and a card that a fan of another session works on are skipped. With nothing to take, it fails with no_task. A card another pane holds fails with task_held.
• From inside a pane, a change needs the task grant. A pane claims only for itself and changes only the card it holds, unless it holds admin. rm from a pane needs admin.

tuios fan --task ID and tuios start-agent --task ID connect a card to the new work. fan stamps the card with the fan. start-agent claims the card for the new pane.

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 for a second, one message per rest, and never over a prompt it is waiting on.

tuios queue -w build 'make the backoff jitter configurable'
tuios queue ls
tuios queue ls -w build
tuios queue rm q3
tuios queue rm --all -w build

A message the agent shows no sign of taking is marked stalled, is never typed again, and opens a question in the Inbox. The question closes, and the message leaves the queue, when the pane shows within ten minutes that it took the message after all. A pane holds at most [agents.queue] max messages (8 by default), each at most 16 KiB. A reply from the Inbox with a long paste can carry more, as a file that the daemon writes when it types the reply. See Large pastes. The queue lives in the daemon's memory. queue ls shows each entry's id, its state (waiting, delivering or stalled), who queued it, its age and the pane. Put -- before text that starts with ls or rm.

review Added in v0.8.0

Show what the agent in a pane changed, leave notes on its lines, and send the notes to it as one message.

tuios review [SESSION] [flags]
tuios review note FILE:LINE TEXT... [flags]
tuios review notes [--clear]
tuios review send [--id <id>] [--now]

• -w, --window <target>: the pane. Default: the focused pane.
• --base <ref>: diff against this ref instead of the worktree's base.
• --uncommitted: only what is not committed.
• --against <session>: diff against another attempt of the same fan.
• --stat: only the changed files and their counts.
• --path <path>: only this path. Repeatable.
• --context <n>: lines of context, 0 to 20. Default 3.

review note puts a note on a line of the new side, or on a removed line with --side old, or on a whole hunk with --hunk '<header>'. --edit <id> replaces a note's text and --remove <id> drops it. review send sends the unsent notes through the queue, typed when the agent is at rest. --now sends only if the agent is at rest now.

tuios review api-fan-retry-2 --stat
tuios review note -s api-fan-retry-2 api/retry.go:42 'log the attempt number here too'
tuios review send -s api-fan-retry-2

See Reviewing an agent's changes.

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.

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

Every subcommand takes -s, --session and -w, --window.

• list prints one row per checkpoint: its number, the turn, the agent state, the time, the commit and the label.
• diff N shows what turn N changed. Without N it shows the newest.
• restore N first saves the work tree as a safety checkpoint and prints its number. Restore that number to undo the restore. --force restores while the agent is working or waiting on a prompt.

tuios checkpoint list -w build
tuios checkpoint diff -w build 3 --stat
tuios checkpoint restore -w build 2

See Checkpoints.

agent-log Added in v0.8.0

Show what the agent in a pane has been doing: prompts, tool calls and how they ended, finished turns, the subagents it started and how each ended, and commands its shell ran, oldest first. It needs the Claude Code or Codex integration.

tuios agent-log -w build
tuios agent-log -w build --since 30m --recap
tuios agent-log -w build --json

• --recap: a summary instead: turns, files written, commands, the last test run, what the agent last said, and its state now.
• --since <duration>: only what happened in this long.
• --limit <n>: at most this many entries, the newest. Default 64, at most 256.

resume-agent Added in v0.8.0

Type a pane's resume command into its shell, such as claude --resume <id>, with the conversation id a hook recorded. It types only when the shell is at its prompt.

tuios resume-agent -w build
tuios resume-agent -w build --dry-run

daemon.resume_agents decides what a daemon restart does on its own. See Resuming after a restart.

Agent setup

integration Added in v0.8.0

Wire coding-agent harnesses' hooks to TUIOS agent state.

tuios integration install claude-code
tuios integration install --all
tuios integration install claude-code --mcp
tuios integration install claude-code --statusline --then '~/.claude/statusline.sh'
tuios integration status
tuios integration uninstall codex

• --all: every supported harness whose configuration directory exists.
• --mcp: also register tuios mcp, read-only, as an MCP server. --mcp-write registers it with the tools that type into panes.
• --statusline: also feed Claude Code's model, context use and cost to the rail. A status line of your own is never replaced: --then chains to it.
• --command <path>: the program the hooks run, when tuios is not on the harness's PATH.

See Agents for what each harness reports.

doctor Added in v0.8.0

tuios doctor agents     # per harness: on PATH, integration installed and current, what it reports
tuios doctor shell      # per pane: whether its shell sends OSC 133 marks, for run and --last-command

With a daemon running, tuios doctor agents ends with the agent panes whose integration is not installed, then the ones whose integration is out of date. For each harness it prints the command that fixes it, such as Update it with: tuios integration install claude-code. Panes on other machines are left out. If TUIOS cannot read which machine the panes of a session run on, it says it did not check that session.

In --json:

• panes_without_integration lists the panes with no integration and the panes whose integration is out of date. Each entry has an integration field, not installed or out of date.
• sessions_not_checked lists the sessions whose panes were not checked.
• Each harness has program (the program its hooks run), other_program (true for a current install made with --command) and unreadable (true when a file could not be read or parsed). tuios integration status --json has the same fields.

tuios keybinds doctor checks the keybindings.

pane-grants and set-pane-grants

pane-grants, run inside a pane, prints what that pane may do through TUIOS. set-pane-grants changes it.

tuios pane-grants
tuios set-pane-grants -w reviewer --grants read
tuios set-pane-grants -w supervisor --grants read,write,fan,respond
tuios set-pane-grants -w reviewer --reset

The grants are read, write, fan, respond, files and admin, or none. A pane may change only its own grants unless it holds admin, and never give more than it holds. See What a pane may do.

pane-grants also says when a change to config.toml waits for tuios config apply.

mcp Added in v0.8.0

Serve the TUIOS control surface as Model Context Protocol tools over stdin and stdout, for a harness to load.

tuios mcp
tuios mcp --write
claude mcp add tuios -- tuios mcp

By default it is read-only and reaches only the session of the pane it runs in, its fan group, and sessions a fan from it started. --write adds the tools that type into panes. --scope all reaches every session, for a harness that runs outside TUIOS. The daemon enforces the limits, not the server.

tmux-shim and tmux

tuios tmux-shim runs a command with a tmux that answers in this TUIOS session, so a tool that drives tmux, such as Claude Code agent teams, opens its panes here.

tuios tmux-shim -- env CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude
tuios tmux-shim --log-all

It is off until you run it, and changes nothing outside the command it starts. tuios tmux <args> answers one tmux command line the same way. --log <file> records the calls the shim cannot fully answer in another file than $XDG_STATE_HOME/tuios/tmux-shim.log. --log-all records every call. Not on Windows.

tuios tmux list-panes -F '#{pane_id} #{=20:pane_title}'

See tmux Shim for the commands and formats it answers, and for control mode.

Remote hosts

hosts Added in v0.8.0

List the machines in the [hosts] table and the state of each link.

tuios hosts [--json]
tuios hosts add <name> <addr> [flags]
tuios hosts remove <name>
tuios hosts test <name> [--start] [--dry-run] [--speed] [--json]
tuios hosts tailnet [--json]
tuios hosts sync [host...] [flags]

The daemon keeps one ssh link to each host. The table has the columns HOST, ADDRESS, STATUS, VERSION, PROTO, SESSIONS, LOAD and LAST OK. LOAD is the one-minute load on the machine's cores, such as 0.42 on 16 cores, then the round trip of the link. It reads - for a host that sends no load, and not known for a host that cannot read its load.

hosts add writes the host to the config file and tests the link. From a terminal outside TUIOS, the daemon opens it at once. From a pane, it waits for tuios config apply. Options:

• --command <path>: the tuios binary on the host. By default the link looks on the PATH, then the usual install paths, then a login shell.
• --connect-timeout <s>: seconds one dial may take. Default 10.
• --ssh-option <arg>: one extra ssh argument. Repeat for more. Only safe options are accepted. See Rules for ssh_options.
• --tailnet: take the address from the tailnet machine with that name.
• --repos-root <dir>: where the host keeps its checkouts, such as ~/src, for fan --host, worktree new --host and start-agent.

hosts remove (alias rm) removes the host and closes its link. hosts test dials once by itself, with no daemon, and prints what ssh said or where it looked for tuios. hosts tailnet lists the machines on your tailnet and which ones hosts add would offer.

tuios hosts add build gaurav@buildbox
tuios hosts add lab lab-01 --ssh-option -J --ssh-option bastion
tuios hosts test build

When the host is up and no daemon runs there, hosts test prints the command to run on the host, with the tuios binary that the link found. Add --start to run it from here:

tuios hosts test build --start            # start the daemon on build if it does not run
tuios hosts test build --start --dry-run  # show what --start does, and change nothing

--start runs start-server over the same ssh that the link uses, then dials again and prints the new state. It does nothing when a daemon runs. On a host with no tuios, it starts nothing: run tuios hosts sync <name> --start. With --json, the result is the host report with action (daemon started, would start daemon, none or start failed), before and start_command.

Add --speed to measure the link the daemon holds to the host, the way a copy uses it. It needs a running daemon and a link that is up. It takes the middle of five round trips of a small call. Then it sends 64 MiB of random bytes up and 64 MiB down on the bulk streams a copy uses. Random bytes do not compress, so the result is the speed of the link itself. With --json the result has host, bytes (each way), rtt_ms, up and down (bytes a second), up_ms and down_ms.

tuios hosts test build --speed
# build: round trip 12.4 ms, up 48.2 MiB/s, down 51.7 MiB/s (64.0 MiB each way, random bytes).

The daemon runs ssh with BatchMode on, so it never asks for a password or about a host key. Run ssh to the host once by hand to accept its key.

With a host configured:

• tuios ls --all-hosts and tuios list-agents --host build list it.
• tuios attach --host build api and tuios new --host build open sessions on it in this client, with your local theme, config and prefix. If the link drops, the client reconnects on its own for up to three minutes.
• tuios new-window --host build opens a pane in a local session whose process runs on the host.

hosts sync Added in v0.9.0

Install the TUIOS version of this machine on the hosts in the [hosts] table. With no names, sync does every host. Name hosts to sync only those.

tuios hosts sync --dry-run          # show the plan and change nothing
tuios hosts sync --dev              # install a build of this checkout on every host
tuios hosts sync build lab          # only these hosts
tuios hosts sync build --restart    # install, then restart the daemon on build
tuios hosts sync build --start      # install if needed, then start the daemon if it does not run
tuios hosts sync --restart --yes --json

First, sync reads each host over ssh: its system, the tuios on it, the version of that tuios, and its daemon. Then it installs where the version is different. It prints one row for each host: the system, the version before and after, the daemon, and what it did.

A release build gets the archive of its own release for each host system. It checks the archive against the published checksums, and sends the binary over ssh. The host needs no internet. Without a release, sync builds the checkout in the current folder, or asks for --src or --binary.

sync installs over the tuios that the host has, if you can write its folder. Otherwise it installs to ~/.local/bin/tuios, and warns if a login shell does not find it there. sync never uses sudo. It writes the binary to a temporary file, checks it, runs it once, and moves it into place.

With --start, sync starts the daemon on each host where it does not run, after the install. The row says daemon started, and daemon.started is true in --json. With --dry-run the row says would start daemon.

One host that fails does not stop the others. The command exits 1 when a host fails. TUIOS_SSH sets the ssh program that sync runs.

All ssh calls of one run to a host use one shared connection, through a private socket in $XDG_RUNTIME_DIR that sync removes at the end. When Tailscale SSH in check mode holds the login, one approval covers the run. On a terminal, sync lists the link to open for each host, and asks to wait up to 5 minutes. Without a terminal, or with --json, the host fails at once. Its row says needs approval, and in --json it has "error_kind": "tailscale_check" and approval_url. A login the tailnet policy refuses has "error_kind": "tailscale_policy". See Tailscale SSH check mode.

See the hosts table.

cp Added in v0.9.3

Copy files and folders between this machine and the hosts in tuios hosts, or between two hosts.

tuios cp [flags] SRC... DST

The daemon runs the copy. A closed terminal does not stop it. The copy goes on after a dropped link or a daemon restart. tuios cp starts the daemon when none runs. TUIOS checks every file with sha256 before it puts the file in place.

tuios cp ./build.tar build:                        # to the receive folder on build
tuios cp build:~/logs ./                           # a folder from build to here
tuios cp build:/var/log/app.log gpu:/tmp/          # from one host to another
tuios cp -m ./dist build:~/www/                    # move: remove the original after the check
tuios cp --contents ./site/ build:~/www/           # what is inside site, not site itself
tuios cp --json --conflict replace ./a.bin build:~/  # for a script
tuios cp --detach ./big.iso build:~/iso/           # start the copy and return

Paths

The word before the first colon is a host when it is the name of a host in [hosts], or local. A path that starts with /, . or ~ is always on this machine. A word before a colon that can be a host name, and is not one, is an error with exit code 2. The message suggests the nearest host name.

HOST: alone is the receive folder of the host. That is ~/Downloads/tuios, or the first folder of files_roots in the config on that host. A host lets this machine write only in its files_roots. A copy to build:~/ needs files_roots = ["~"] in the config on build. See Files over a link.

Files and folders

The rules are the rules of cp:

• A DST that is a folder, or that ends in /, gets each SRC inside it.
• A DST that does not exist, with one SRC, is the new name.
• Several SRCs need a DST that is a folder and exists.
• A folder copies with all that it holds. -r is accepted and changes nothing.
• --contents copies what is inside a SRC folder, not the folder.
• A folder copied into a folder that exists merges into it, file by file.

Links, named pipes, sockets and devices in a folder are not copied. The summary names them.

Files that are there

TUIOS never copies a file again when the same bytes (sha256) are already there. A second run of the same copy is a quick check. A file that is there and differs follows --conflict:

keep-both names a copy from another machine name (from HOST).ext, such as report (from build).pdf. A copy on one machine gets a number: report 2.pdf. Give one policy only. Two flags with different policies are an error.

ask shows each file, which one is newer, and how the sizes differ:

~/www/index.html is there on build. The new one is newer, and the new one is 1.20 KiB larger.
Replace it, keep both, or skip? [r/k/s, or R/K/S for all files]

An upper case letter gives the same answer for every file of the copy. Another key is not an answer, and the command asks again. Ctrl+C at the question cancels the copy. ask needs a terminal. Without one, the command stops with exit code 2.

What a copy keeps

A copy keeps the permission bits and the modification time of each file. It never keeps the owner. --no-perms gives each file the default permission bits. --no-times gives each file the time of the copy.

On a link the daemon compresses the bytes of a file that compresses well. --no-compress turns this off. --bwlimit sets the most bytes a second, such as 500K or 5M.

Flags

Output

On a terminal, tuios cp draws the progress on stderr: the copy, a bar, the rate and the time left. A folder copy also shows the file it copies now. Without a terminal it prints one line for each change of state, and at most one progress line each ten seconds. At the end it prints one line on stdout for each copy:

Copied 1,204 files, 38.2 MiB, to build:~/www/site (checked).

The lines after it name the files that were not copied, and why.

--detach prints the id of each copy on stdout and returns. Follow the copy with tuios transfers wait ID. A detached copy has nobody to answer a question, so its default --conflict is skip.

--json prints one JSON object on each line of stdout. The event field names the kind:

exit is the exit code of that copy. The command exits with the worst of them.

A host that goes away

When a host is not reachable, the copy waits for it in the daemon. It goes on from where it stopped when the host is back. --timeout 10m makes the command exit 5 when a host stays unreachable for ten minutes. The copy goes on waiting in the daemon, and the command says so. Add --cancel-on-timeout to cancel the copy too.

Ctrl+C

On a terminal, Ctrl+C asks a question:

Cancel the copy, or keep it running? [c/k]

k keeps the copy running in the daemon, and the command returns. Follow the copy with tuios transfers. c, or a second Ctrl+C, cancels the copy, and the command exits 130. Without a terminal, with --json, or on SIGTERM, the command cancels the copy at once.

In a pane

A copy started in a pane carries the name of the pane. The pane grants decide if the copy may start. admin may copy anything. files may copy only inside the folder of the pane, and under the home folders or to the receive folders of the hosts. See What a pane may do.

Exit codes

A file skipped by a --conflict policy that you gave does not give exit 3.

See Copy files between machines.

transfers Added in v0.9.3

List the copies that the daemon runs, and control them. tuios copies is the same command.

tuios transfers [--json]
tuios transfers pause ID... [--json]
tuios transfers resume ID... [--json]
tuios transfers cancel ID... [--json]
tuios transfers wait [ID...] [--json] [-q]
tuios transfers clear [ID...] [--json]

The list has the copies that tuios cp started and the copies that other clients started. A copy that ended stays in the list for 30 minutes, or until tuios transfers clear. In a pane that holds the files grant and not admin, the list has only the copies that the pane started. The other subcommands act only on those copies.

The states are queued, running, verifying, waiting (for a host that went away), paused, conflict (waits for an answer), done, failed and cancelled.

pause, resume and cancel exit 1 when one id fails. --json prints the new rows. clear --json prints {"cleared": N}.

wait takes --json and -q as tuios cp does, and prints the same events. Its exit code is the code tuios cp gives for the worst of the copies. An id that no copy has exits 1. A copy that waits for a host has not ended, so wait goes on waiting. wait cannot see the --conflict policy of a copy. A file that is there and differs always gives exit 3, as with the default policy of tuios cp.

tuios transfers
tuios transfers pause 3f9a1c2b7d00
tuios transfers wait 3f9a1c2b7d00 --json
tuios transfers clear

The same copies show in the Copies panel.

pair Added in v0.9.3

Show a QR code that adds this machine to a phone. The phone sends its ssh key, and you accept it. The key can only open a tuios link, with the policy of a new [hosts.DEVICE] table. See Phones.

tuios pair [--name DEVICE] [--machine NAME] [--allow list,mail,open,write,respond,files] [--timeout 5m]
           [--listen HOST:PORT] [--listen-all] [--accept-local] [--authorized-keys PATH]
           [--advertise-ssh HOST:PORT,...] [--advertise-pair HOST:PORT,...]
           [--ssh-port 22] [--host-key PATH] [--command PATH] [--yes] [--json]