hty wait

Block your script until a session reaches a specific condition — text appears on screen, a regex matches, the display stops changing, or the process exits. This eliminates fragile sleep calls and removes race conditions.

The <session> argument accepts a session name, a full UUID, or a unique UUID prefix. If only one session is running, you can omit it.

Reference

hty wait [SESSION] --text "..." | --regex "..." | --idle MS | --exit [--timeout MS] [--json]

Block until the session matches a condition. Exactly one mode flag is
required. Exit 0 on match, 3 on timeout.

Modes:
  --text STRING    Wait until the rendered screen contains STRING.
  --regex PATTERN  Wait until the rendered screen matches PATTERN
                   (POSIX extended regex).
  --idle MS        Wait until the screen has been unchanged for MS
                   milliseconds.
  --exit           Wait until the child process exits.

  --timeout MS     Max time to wait in milliseconds (default 10000).
  --json           Emit a structured {matched, elapsed_ms, ...} object
                   describing the match (or the timeout) to stdout.

Examples

# Wait for a specific string to appear
hty wait my-session --text "Press any key" --timeout 5000
 
# Wait for a regex match
hty wait my-session --regex "error|Error|ERROR" --timeout 3000
 
# Wait until the screen has been stable for 500ms
hty wait my-session --idle 500 --timeout 10000
 
# Wait for the process to exit
hty wait my-session --exit --timeout 30000

Exit codes