Sessions
A session is one program’s terminal: the program (your shell, Claude Code, a dev server), its pseudo-terminal (ConPTY on Windows), and a full copy of the terminal’s state in libghostty: the screen, the scrollback, the modes, even half-received escape sequences.
Each session is its own process. A small background service starts sessions and finds them again; windows, alto attach and other computers are clients that attach to them.
Alto’s words
Section titled “Alto’s words”| Word | What it is |
|---|---|
| device, machine | a computer running Alto: yours, or one paired with |
| service | the background process on each device that starts sessions and finds them again |
| session | one terminal and its program, kept alive by the service. Addressed as 3 here, or studio:3 from anywhere |
| window, tab, pane | the app’s: a window has tabs, a tab is split into panes, and each pane shows a session. The window remembers the layout; the service doesn’t need to know about it |
| client, viewer | anything showing a session: the app, alto attach in any terminal, a phone |
| work pane | a session linked to an agent’s, where it runs commands you can see |
A session is a single terminal, not a group of them, which is why alto run, capture, send and studio:3 each name exactly one. Grouping lives in the app’s tabs.
Why it outlives the window
Section titled “Why it outlives the window”Because the window doesn’t own anything. Quit the app, update it, or let it crash, and every session carries on. Open it again and the window remembers its tabs, their splits, which pane had focus, each pane’s profile and which tab was in front, and attaches to them all again.
A crash in one session takes down that session, not the others. The service holds nothing it can’t rebuild from small records on disk, so it can restart or be replaced without touching a running session.
The background service
Section titled “The background service”The service starts at login, so sessions are there before you open the app: a LaunchAgent on macOS, a systemd user unit on Linux, a Run key on Windows. The app sets this up; without the app:
alto service enable # start the service at loginalto service status # is it running now, and does it start at loginSeveral clients, one session
Section titled “Several clients, one session”Any client can show a session and, as the rules allow, type: each joins as an observer (watching), a peer (typing too) or a moderator (also pausing agents and ending it), the most it may unless alto attach --mode asks for less. The session’s size follows whoever typed last; the others draw it at that size with a note, Sized for another window, and Resize to fit takes it back. alto attach asks whether to fit, resize or just watch, or takes --fit or --watch.
Ended sessions
Section titled “Ended sessions”A session that was killed or stopped (the computer restarting), rather than its program exiting, saved its screen as it went. Its pane shows that last screen, scrollback included, and takes no typing; scrolling, selecting, copying and finding still work.
Its note says This session has ended, when its screen was saved, and offers one button: Resume Claude, Run vim again, New shell. Enter does the same. It starts the command again in the folder it was last in, in the same place in the tab; an agent picks up its own conversation if its hooks are installed.
Closing an ended tab forgets its save. A program that exits on its own leaves nothing behind, and its pane closes.
alto capture ID prints an ended session’s screen and scrollback, as it last saved them.