pty experimental

Attach and peek

Clients come and go; the session stays. There are three ways in: attach to use the program interactively, peek to read its screen, and send to type into it from a script.

Attach#

pty attach <name> connects your terminal to the session. The session sends its size, then one snapshot of the full screen, then live output in order, and at most one exit notice. A client that joins late sees exactly what's on the screen right now.

Press Ctrl+\ to detach. The program keeps running.

Peek#

pty peek reads the screen without attaching. It's read-only, so it's safe to point at anything.

pty peek --plain api                  # the screen as plain text
pty peek -f api                       # follow the output, read-only
pty peek --wait "Ready" -t 30 api     # wait until the text appears

--wait is the building block for scripts and agents: start something, wait until it says it's ready, then carry on. No sleeps, no guessing.

Send#

pty send types text and named keys into the session:

pty send api --seq "npm test" --seq key:return
pty send api --seq key:ctrl+c

With run, peek and send, a program can drive an interactive terminal the same way a person does.

Sharing one screen#

Many clients can attach at once. They share one screen, so they have to agree on its size:

• The size is the smallest of the clients that can type.
• Read-only viewers never shrink it. Peeking from a phone doesn't squeeze the session for everyone else.

Events#

Each session also keeps an event log: bells, title changes, desktop notifications, and events you publish yourself. Tools use it to notice that a program wants attention, without reading its screen.

pty events --recent api          # what happened lately
pty emit user.deploy.started     # publish your own, from inside a session