Spawn a program in a new detached, persistent session and return its id.

The session survives across tool calls (a localhost-only daemon owns the live PtySession). cmd is the command line to spawn, e.g. "python3" or "lazygit". cwd and env configure only the controlled child process. Returns {"ok", "sid"} on success. Use the returned sid for every other tool.

Server-side limits (violations return an error): at most 8 concurrent sessions by default (tunable via SMARTCLI_MAX_SESSIONS); sid must be 1-64 chars matching [A-Za-z0-9][A-Za-z0-9_.-]*; env keys must be valid identifiers and may not start with SMARTCLI_TUI_; cwd must be an existing directory; terminal size is capped at 1000 cols x 500 rows (100000 cells). Note: env values pass through the process command line briefly (visible in ps) — avoid secrets.

detect_child_exit (default false) makes this session's waits END when the child dies instead of sitting out the remaining timeout: a program that crashes on your first input costs one poll cycle instead of the whole ceiling. Off is exactly the previous behaviour. On, every wait tool also reports exited (true only when the wait ended that way), and wait_ready reports reason: "EXITED" alongside the usual MARKER/STABLE/TIMEOUT.

List active drive-tui sessions.

Returns {"ok", "sessions"}: each entry carries "sid", "port", "pid", "cmd", "cols", "rows", "cwd" and "started".

Read a semantic snapshot of the session's current screen.

Returns {"ok", "alive", "alt_screen", "text", "hash", "visual_hash"}: alt_screen is true while a full-screen program (vim, less, htop, ...) owns the screen — keys are commands to that program, not input to a shell, and text is its frame rather than scrollback. text is the rendered screen; json (the structured cell/cursor model) is included only when as_json=true. hash covers text content only — use it as the wait_change baseline; visual_hash also covers styling, selection and cursor state — use it as the wait_visual_change baseline. Don't mix the two. This is the 'perceive' step — always snapshot after acting rather than assuming an action landed.

Terminate a session and its daemon. Always close sessions when done.

Type literal text into the session (no Enter). Use for filling fields.

Type text followed by Enter — the common 'run this command' action.

Send key tokens, e.g. ["Down", "Down", "Enter"], ["C-c"], ["M-x"].

Named tokens: Enter, Return, Tab, BackTab, Space, Backspace, Delete, Escape, Esc, Up, Down, Right, Left, Home, End, PageUp, PageDown, Insert, F1-F12. Combos: "C-" or "^" (Ctrl — letters plus @, Space, [, , ]) and "M-" (Meta/Alt, ESC prefix). Any other token is not an error — it is typed as literal text.

Arrow keys adapt to the app's cursor-key mode (SS3 under DECCKM, CSI else), so menu navigation works in curses apps.

Block until pattern (a regex) appears on screen, then snapshot.

Returns {"ok", "matched", "alive", "exited", "text", "json"}. Timeout is not an error: the call returns ok=true with matched=false plus the final screen snapshot. exited is true only when the session was started with detect_child_exit AND the child died before the pattern appeared, in which case the wait returned at once instead of running to timeout_ms. Screen lines are right-padded with spaces — end-anchored patterns never match; use unanchored markers. This is the readiness sync — prefer it over a blind delay after send_line/send_keys.

Block until the screen content changes, then snapshot.

The precise "did my action land?" primitive: call it right after send_line/ send_keys to wait for ANY change from the baseline (default: the screen at call time; or pass a prior hash to change away from). Returns {"ok", "changed", "hash", "alive", "exited", "text", "json"} — hash is the new screen hash, reusable as the next baseline. Timeout is not an error: the call returns ok=true with changed=false plus the final screen snapshot. exited is true only on a detect_child_exit session whose child died first. Can't false-positive on text that was already on screen, unlike wait_regex.

Wait for text, selection styling, or cursor position to change.

Prefer this after arrow/navigation keys in full-screen TUIs. Pass a prior visual_hash, or omit it to use the current rendered state as the baseline. Timeout is not an error: the call returns ok=true with changed=false plus the final screen snapshot, with exited true only on a detect_child_exit session whose child died first.

Wait for ANY of patterns to appear on screen (pexpect expect([...]) style).

Race several possible outcomes at once — e.g. patterns=[">>> ", "Error", "Password:"] — and learn WHICH happened. Patterns are scanned in list order each poll, so the earliest in the list wins a same-poll tie (put the most specific first). Screen lines are right-padded with spaces — end-anchored patterns never match; use unanchored markers. Returns {"ok", "index", "matched", "alive", "exited", "text", "json"} where index is the 0-based position of the matched pattern. Timeout is not an error: the call returns ok=true with index=-1 and matched=false plus the final screen snapshot. On a detect_child_exit session whose child died first, index is -1, matched is false and exited is true — the wait returned at once rather than running to timeout_ms.

Wait for a regex marker OR for the screen to go quiet (stable), then snapshot. Use marker="" to wait purely for stability.

Returns a snapshot plus reason: "MARKER" (the regex appeared), "STABLE" (the screen went quiet), "TIMEOUT", or — only on a session started with detect_child_exit — "EXITED" (the child died; the wait returned at once rather than running to max_wait_ms). exited reports the same fact as a boolean on every wait tool. Timeout is not an error: the call still returns ok=true with the final screen snapshot. Screen lines are right-padded with spaces — end-anchored markers never match; use unanchored markers.

Check whether the session's child process is still running.

Resize the session's terminal to cols x rows.