pty experimental

pty

pty runs a program inside a persistent terminal session. You can detach, walk away and come back later: from the same machine, over SSH, or from another machine over fabric. The program never notices you left.

Experimental. pty runs every day on our own machines, but there are no prebuilt binaries yet, so you build it from source. Details may still change.

Why it exists#

Long-running and interactive programs, like dev servers, builds, REPLs and AI agents, shouldn't die with the terminal that started them. People and programs should both be able to watch and drive them: a script should be able to read the screen, wait for a prompt and type a command.

What a session is#

A session is one small daemon, one program, one emulated screen.

• The daemon owns the program through a real pseudo-terminal.
• It feeds the program's output into a headless terminal emulator built on libghostty, the terminal core extracted from Ghostty. So it always knows exactly what's on the screen.
• It survives every client disconnecting, and one session failing never takes down another.

That's why coming back shows you the real current screen, not a replay of a log.

Sessions only#

pty is closer to abduco or dtach than to tmux. It keeps sessions alive and nothing else: no panes, no windows, no layouts. Your terminal already does splits, and on a phone you don't want them.

A quick look#

pty run -d --name api -- node server.js   # start it in the background
pty list                                  # what's running
pty peek --plain api                      # read the screen
pty attach api                            # use it; Ctrl+\ detaches
pty kill api                              # stop it

Where state lives#

Everything durable is plain files in one directory, $PTY_ROOT: a socket, a pid file, a metadata file and an event log for each session. Other tools can read session state straight from those files. Point PTY_ROOT somewhere else to keep a separate registry, for example in tests.

Each session has a stable id for scripts, an optional display name for people, and tags: key/value pairs that tools use to find their own sessions, and that the lifecycle turns into behavior.