/tuios
Drive tuios from inside one of its panes. Find out where you are running, read and write other panes, run work and wait on it instead of polling, report your own state so the person sees it, and talk to the other agents and the person safely. `tuios --skill <topic>` prints the
$ npx -y skills add Gaurav-Gosain/tuios --skill tuios --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/tuios
Context preview
The summary Claude sees to decide when to auto-load this skill.
Drive tuios from inside one of its panes. Find out where you are running, read and write other panes, run work and wait on it instead of polling, report your own state so the person sees it, and talk to the other agents and the person safely. `tuios --skill <topic>` prints the
SKILL.md
tuios.SKILL.mdname: tuios
description: "Drive tuios from inside one of its panes. Find out where you are running, read and write other panes, run work and wait on it instead of polling, report your own state so the person sees it, and talk to the other agents and the person safely. `tuios --skill <topic>` prints the rest: fleets of agents, turn checkpoints, shipping a worktree, the Inbox and approvals, push notifications, mail, other machines, clients, events, MCP, the tmux shim, herdr's command line, pane grants, configuration, agent features off, errors and recipes."
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
Read more
name: tuios description: "Drive tuios from inside one of its panes. Find out where you are running, read and write other panes, run work and wait on it instead of polling, report your own state so the person sees it, and talk to the other agents and the person safely. `tuios --skill <topic>` prints the rest: fleets of agents, turn checkpoints, shipping a worktree, the Inbox and approvals, push notifications, mail, other machines, clients, events, MCP, the tmux shim, herdr's command line, pane grants, configuration, agent features off, errors and recipes."
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
A terminal window manager that knows what your agents are doing. Tiling panes, workspaces, sessions that survive restarts, and one Inbox for every coding agent.