---
name: termio
description: See and drive the sibling agent sessions running alongside you in this termio project via the `termio sessions` CLI — list and watch their status, spawn new agent or plain-terminal sessions, send a prompt or an answer into a session, and read an agent's reply from its transcript. Use when delegating work to another session, checking on or supervising what other sessions are doing, or starting a command the user should see in its own visible pane. Do not use merely because a task could run in parallel. Requires running inside termio (TERMIO_SESSION set).
---

# Driving sibling sessions (termio)

If `TERMIO_SESSION` is not set in your environment, you are not running inside
a termio-managed session — say so and stop instead of trying to drive sessions
you cannot see.

You are running inside termio alongside other agent sessions in this same
project. Coordinate with them through the `termio sessions` CLI. Every command
is scoped to this project automatically; add `--json` for machine-readable
output. The installed CLI is the authority on syntax: where this text and
`termio sessions --help` disagree, trust the CLI. Sessions are addressed by
the link `list` prints: `termio://session/<uuid>` (a bare id or unique
id-prefix works too).

- `termio sessions list` — siblings in this project, with status (working /
  idle / needs-you / done)
- `termio sessions watch` — block and stream one line per sibling status
  change (`done` / `needs-you` by default) until you interrupt it — the push
  alternative to polling `list`. `--state working,idle,done,needs-you` widens
  it, and `--state stalled` adds the runaway signal: a sibling still
  `working` that has made no repo or transcript progress for 20+ minutes
  (long builds streaming output don't trip it). A stalled event says why in
  `evidence`, fires once, and re-arms when progress resumes. It opens with
  one snapshot line per sibling's current status
  (`"snapshot":true` in `--json`; `--no-snapshot` skips), and in `--json`
  writes `{"heartbeat":true}` after 30s of silence so a dead stream is
  detectable. Exits 0 on your Ctrl-C, 2 if termio itself went away.
- `termio sessions spawn "<prompt>"` — start a NEW agent session on the
  prompt (`--agent codex` picks the agent; default: your own kind). Replies
  immediately with the new session's link — use it for every follow-up;
  the prompt itself is typed in once the agent finishes booting.
- `termio sessions run "<command>"` — start a NEW plain terminal session
  typing that shell command (a dev server, a test run) into a visible pane —
  no LLM. Use it instead of your own background shell when the user should
  be able to see and take over the process.
- `termio sessions send <link> "<text>"` — type text into that existing
  sibling and submit it with a real Return keypress. Send a prompt to drive
  it, or a menu choice (`"1"`, `"yes"`) to answer a permission prompt.
- `termio sessions read <link> [--lines N]` — the session's current
  screen. The result channel for `run` sessions (a plain command has no
  transcript; its screen is the result) — for agent replies keep using the
  transcript, not the screen.
- `--wait [--timeout <ms>]` on `send`, `spawn`, or `run` — block until that turn
  settles and reply with the final `status`, the `transcript` path, and the
  `cursor`..`cursor_end` line range holding the response — one call instead
  of send-then-poll. A sibling that stops to ask you something short-circuits
  the wait: the reply is `status:"needs-you"` with the on-screen question in
  `prompt` — answer it with another `send`. Exit codes: 0 settled, 1 error
  (`prompt_stalled` = the input showed no effect within 5s; `session_closed`
  / `agent_gone` = the target vanished mid-wait), 3 timed out (session still
  running — re-arm or read its transcript).
- `termio sessions close <link> …` — close session tabs;
  `termio sessions focus <link>` — bring one to the front in the app

### Targeting discipline

- Copy links verbatim from `list` or a `send` reply; never guess or
  construct one.
- One request, one target. Never send the same prompt to several siblings,
  and never run multiple `send` commands in parallel — delegate to ONE
  session.
- Unsure which sibling the user means? Ask them, or start a fresh session
  with `spawn` — don't broadcast.

### Reading a sibling's response

Don't scrape the terminal. `spawn`/`send` returns the sibling's **transcript**
— the agent's own structured Q&A log (Claude Code: a JSONL file) — plus a
**cursor** (its line count at send time). To read the reply:

1. `spawn`/`send` and note `transcript` + `cursor` from the output. (A just-
   started session has no transcript yet; it appears in `list --json` once the
   agent reports it — read that file from the start.)
2. Poll `termio sessions list` until that session's status is `done` (or
   `needs-you` if it's blocked waiting on input — then `send` its answer).
3. Read the transcript file from line `cursor` onward; the `assistant` entries
   after it are the reply. (Each line is a JSON object with a `type`/`role`.)

Workflow: send → wait for `done` via `list` → read the transcript tail. Prefer
this over assuming a sibling is finished — or collapse steps 1–2 into one call
with `send --wait`, whose reply carries the final status and the exact
`cursor`..`cursor_end` range to read. Supervising several at once? Block on
`termio sessions watch` instead of polling — it prints the link the moment any
sibling turns `done` or `needs-you`, so you act on the transition, not a spin
loop; its `--json` `needs-you` events carry the question in `prompt`, and `done`
events carry `transcript` + `cursor_end`, so you can act straight from the event.