Tuios

Driving tuios from a pane

tuios is a terminal window manager with a daemon. Sessions hold windows, each window owns one pane, and windows are grouped into numbered workspaces. The tuios command talks to the daemon over a unix socket, so everything here works from inside a pane, from a plain shell and from a script.

This is the core of the skill: the loop almost every agent uses. It is printed by tuios --skill and ships inside the binary, so it always describes the tuios you are running. The rest is in topics, listed at the end. Print one with tuios --skill <topic>, or everything with tuios --skill all.

Am I inside tuios

[ "$TUIOS_ENV" = "1" ] || echo "not in a tuios pane"

A daemon-managed pane has these set:

TUIOS_ENV=1
TUIOS_PANE_ID=98db8226-1829-468e-89a8-41a2baa0ddab
TUIOS_WINDOW_ID=98db8226-1829-468e-89a8-41a2baa0ddab
TUIOS_SESSION=work
TUIOS_SOCKET=/run/user/1000/tuios/tuios.sock
TUIOS_HOST=laptop
TUIOS_PANE_TOKEN=3f9a...
TUIOS_PANE_GRANTS=admin

TUIOS_PANE_ID is your own window, and TUIOS_WINDOW_ID is the same uuid. Pass it to -w whenever you mean yourself rather than whatever is focused. It is also your address when another agent wants to reach you. The CLI presents TUIOS_PANE_TOKEN where the daemon needs it; never pass it by hand.

TUIOS_SOCKET names the daemon that runs your pane. Setting it does not send a command to another daemon: XDG_RUNTIME_DIR chooses the daemon, and a command refuses when TUIOS_SOCKET names a socket where nothing listens. For a throwaway daemon of your own, set XDG_RUNTIME_DIR and XDG_STATE_HOME to fresh directories.

TMUX and TMUX_PANE are not set in a tuios pane, even when tuios runs inside tmux, so do not drive panes with tmux here: use the tuios verbs. A tool that only knows tmux can run under the shim (tuios --skill tmux).

A pane restored after a daemon restart has TUIOS_RESTORED=1: it is a new shell in the old place. A pane whose process runs on another machine has TUIOS_PANE_HOSTED=1 and no TUIOS_ENV (tuios --skill hosts). A standalone tuios has no daemon and no socket, so guard on TUIOS_ENV and degrade quietly when it is unset.

What your pane may do

tuios pane-grants

Pane 98db8226 in session work holds admin (the default of [agents.permissions], mode open).

Mode open is the default, and there a pane holds admin. Under mode strict a pane holds read, write and fan unless the person set other grants. The grants are read, write, fan, respond and admin. A call your grants do not cover fails with forbidden, does nothing, and names the grant it needed. That is the person's decision about your pane: do the work inside what you hold, or ask the person. Do not look for another verb or process that does the same thing, and do not try to raise your own grants. tuios --skill grants has the whole model.

Addressing things

Sessions are addressed by name with -s. Omit it and the most recently active session is used, which is a guess when several are live. Inside a pane, pass -s "$TUIOS_SESSION".

Windows are addressed with -w, which takes, in order: the full uuid, the index list-windows prints (all digits), the exact window name (a name you gave, before a program's title), or a unique id prefix. A name wins over a prefix, so a pane called db is never mistaken for a pane whose id starts with db. An ambiguous name or prefix is an error, never a guess. The index shifts when an earlier window closes, so a script holds the id or the name.

A pane running an agent is a window like any other and is addressed the same way. HOST:SESSION and HOST:SESSION:WINDOW reach another machine (tuios --skill hosts).

Seeing and reading

tuios ls
tuios list-clients
tuios list-windows -s work
tuios list-agents -s work
tuios capture-pane -s work -w build --scrollback --lines 40

The listing commands take --json when you want to parse rather than read. capture-pane without --scrollback is the visible screen, which ends in the blank rows below the cursor. --lines counts from the last line with content. Leave --ansi off when you match text.

Drive other windows: open, address, send keys, check

Open a window per job with a name, run the program with send-text, wait for it to draw, then send keys to it by name and read the screen back:

tuios new-window -s "$TUIOS_SESSION" docs --cwd ~/dev/docs --no-focus
tuios send-text -s "$TUIOS_SESSION" -w docs 'glow -t README.md
'
tuios wait-for window-idle -s "$TUIOS_SESSION" -w docs --idle 1000
tuios send-keys -s "$TUIOS_SESSION" -w docs Down --repeat 5
tuios send-keys -s "$TUIOS_SESSION" -w docs PageDown
tuios capture-pane -s "$TUIOS_SESSION" -w docs

• Always pass -w. With -w, keys go to that window's program whatever the person has focused. Without it they go to the person's client as if the person pressed them, which is the focused window (often your own) or the window manager.
• new-window prints 3a42ab8f docs: the short id and the name. Either one is a -w target. --print-id prints only the full id, for id=$(tuios new-window ... --print-id). A name you give beats any window's title; two windows with one name are an error that lists both.
• Key names: Up Down Left Right PageUp PageDown Home End Enter Escape Tab Space Backspace, one character (q, /), and ctrl+c. Case does not matter, and arrow-up, KEY_UP and PgDn work too. --repeat N sends the whole sequence N times. The full table is in tuios --skill panes. A misspelled key is refused and nothing is sent.
• send-keys prints where the keys went (sent 5 keys to window docs (3a42ab8f)); capture-pane shows what the program did with them. When you know a word the program will draw, wait-for window-output --pattern WORD is surer than window-idle. Capture a full-screen program without --lines: its screen is already bounded, and --lines counts up from the last row with content, so it cuts off the top.

send-keys is not for typing text. It splits its argument on spaces and commas, so send-keys 'echo hello' types echohello. Text, and the Enter that runs it (a trailing newline), goes through send-text.

Text sent to a pane running an agent is read as if a person typed it. To talk to an agent use ask-agent (below), which waits until the agent is not mid-turn. Never type at an agent that is on needs_input: your text answers its prompt, which can approve what it asked for.

Running work and waiting for it

Open a pane for the work, named, without taking the person's focus:

tuios new-window -s work tests --cwd /src/api --no-focus

When the pane's shell marks its commands (OSC 133; tuios doctor shell says which do), run types a line, waits for it to finish, prints its output and exits with its status:

tuios run -s work -w tests --timeout 600000 -- go test ./...

Do not capture in a loop with a sleep. The daemon blocks for you:

tuios wait-for window-output -s work -w build --pattern 'ok\s+github' --timeout 120000
tuios wait-for window-idle   -s work -w build --idle 2000
tuios wait-for window-exit   -s work -w build --timeout 600000
tuios wait-for agent-state   -s work -w review --until idle,done,needs_input --timeout 600000
tuios wait-for agent-message -s work -w "$TUIOS_PANE_ID" --timeout 600000

--timeout is milliseconds and defaults to 30000. window-output matches the whole scrollback, including the echo of the command you typed and the output of earlier runs, so use a fresh marker the pane assembles. tuios --skill panes has that recipe, popups, layouts and the rest of pane handling.

Reporting your own state

The person sees which pane needs them from the state each pane reports, and other agents read it to decide whether you can be asked something. From inside a pane always name yourself and your harness:

tuios set-agent-state working -s "$TUIOS_SESSION" -w "$TUIOS_PANE_ID" --harness claude-code -m "running the test suite"
tuios set-agent-state needs_input -s "$TUIOS_SESSION" -w "$TUIOS_PANE_ID" --kind approval -m "approve Bash: make deploy"
tuios set-agent-state done -s "$TUIOS_SESSION" -w "$TUIOS_PANE_ID"

The states are none, working, needs_input, idle, done, errored and unknown. A needs_input report becomes a row in the person's Inbox with your message as its summary, so make the message the question. Report working as soon as you are unblocked. Most harnesses can report on their own once wired:

tuios integration install claude-code    # or codex, gemini-cli, opencode, --all
tuios doctor agents

A script or a tool without a harness can report with OSC 7501, the Program Status Protocol, through tuios status. It needs no session or pane id, and it works in other terminals that read the protocol too:

tuios status working --app build --msg 'Compiling' --progress 40
tuios status blocked --kind permission --app deploy --msg 'Approve deploy to production?'
tuios status done --app build --msg 'Built 12 crates'

tuios --skill state has the hook wiring, OSC 7501, metadata, detection and resume.