# Alto

> Alto is the modern terminal for humans and coding agents: the terminal layer that lets you, and them, work seamlessly across one machine or a whole fleet. Sessions outlive the window, every tab shows what needs you, and Tailscale secure access is built in.

Alto is the modern terminal for humans and coding agents: the terminal layer that lets
both work seamlessly and securely across fleets of machines. Three things: a better terminal
for people and agents alike; a way to run sessions across
every server in a company or homelab (setup with one command, trust by Tailscale tag, one
queue of what needs you across devices); and secure remote access from anywhere, with
Tailscale built in (nothing listens on the LAN or internet; devices prove their identity).

Alto is a terminal emulator built on libghostty, for macOS, Linux and Windows, written in
Rust with GPUI. Every tab's session is its own background process, owned by a small server, so
programs (Claude Code, Codex, builds, dev servers) keep running when the window closes, the app
updates or crashes. Sessions save their screen as they go and come back after a reboot with a
Run again button that resumes agent conversations. Each tab shows an agent state: working, needs
you, done or idle, from terminal signals and from hooks for Claude Code and Codex. Other
computers reach sessions over Tailscale only. A work pane lets an agent run commands in a
terminal the person can see, with `alto run` returning only the output and exit status.

Status: early. Built: the terminal, persistent sessions, reboot recovery, agent status,
remote devices, work panes, MCP. Planned: phone apps (Phase 6), agents coordinating agents
(Phase 7), automatic updates and packages (Phase 8), fleet groups, placement, rules, single
sign-on and audit log (Phase 9). A Homebrew formula is coming soon;
until then it is built from source.

## Docs
- Docs home: https://www.altoterm.com/docs/
- Install: https://www.altoterm.com/docs/start/install/
- Working beside an agent: https://www.altoterm.com/docs/agents/work-pane/
- MCP server: https://www.altoterm.com/docs/agents/mcp/
- Remote access with Tailscale: https://www.altoterm.com/docs/devices/remote-access/
- Running a fleet: https://www.altoterm.com/docs/devices/fleet/
- Servers and containers: https://www.altoterm.com/docs/devices/servers/
- CLI reference: https://www.altoterm.com/docs/reference/cli/
- MCP tool reference: https://www.altoterm.com/docs/reference/mcp/
- Comparison with other approaches: https://www.altoterm.com/why/

## CLI commands (alto 0.0.1)
- alto open: Open a session in an Alto window, in a new tab if one is open, in this folder or DIR. Runs your login shell unless a program is given after `--`. What plain `alto` does where there's a screen
- alto new: Start a session and print its id. Runs your login shell unless a program is given after `--`
- alto ls: List running sessions, and what each is doing [alias: list]
- alto waiting: Sessions waiting for you (a permission prompt, a question, a bell), here and on every other device you reach, newest first
- alto reload: Move the server and running sessions onto the build installed now, after an update (nothing is downloaded). Sessions move in place, their programs still running: idle ones at once, working ones once idle. Those that can't (on Windows, ones started before they could) are listed as needing a restart, which --restart does
- alto status: Show what a session's program is doing, or say it (for an agent's hooks): idle, working, needs-you or done. Without --session, the session this runs in
- alto hooks: Set up agents to report their state to Alto: Claude Code, Codex
- alto attach: Show a session in this terminal. Ctrl-\ detaches
- alto send: Type text into a session, then keys by name. With no id, the work pane linked to this session (`alto work`)
- alto run: Run a command in a session's shell, where it shows, and print only its output, leaving with its exit status
- alto wait: Wait until a session's program reaches a state, or shows some text. Exits 0 then (printing what it found), 124 after --timeout, 125 if the session ends. With no id, the work pane linked to this session
- alto capture: Print a session's screen and scrollback as plain text (an ended session's, as it last saved them). With no id, the work pane linked to this session
- alto kill: End a session's program, or forget an ended session. --all ends every session here, asking first
- alto restart: Start over: end every session here (asking first), restart the server on the build installed now, and have open windows drop their tabs for one new one. `reload` is the one that keeps programs running
- alto pause: Stop agents typing into a session (`run`, `send` from an agent are refused there) until `alto resume`. You can still type. With no id, the work pane linked to this session
- alto resume: Let agents type into a session again
- alto work: The work panes linked to this session: where an agent running in it runs its commands (`alto run -- COMMAND`), beside it where you see them, here or on another device (`--on`). With nothing after it, lists them
- alto mcp: Serve the session commands to an agent over MCP, on standard input and output: `claude mcp add alto -- alto mcp`. Its tools run commands in your work pane (or a session it's told to use), as `alto run` does
- alto server: The background process that keeps sessions (started for you): whether it's running, or start, stop or run it here
- alto keep-awake: Show or set how long sessions keep the computer awake after they last print: `off`, `on` (1m), `always` (while any session runs), or any time: `30` (minutes), `90s`, `45 mins`, `2h`, `1h30m`. Applies to running sessions at once
- alto fonts: Fonts Alto can download: list them, or install one
- alto remote-access: Whether your other devices may reach these sessions, over Tailscale only: `on` (the default) or `off`. Leave out to see it, with Tailscale's state and your devices that run Alto
- alto pair: Pair with another person's device (your own, on the same Tailscale account, need no pairing). With nothing after it, shows a pairing string to type on the other device; with that string, pairs
- alto devices: Your other devices: those you reach (`--on NAME`), and those that reach this one. Forget, block or let one back in
- alto setup: Make this device reachable from your others, with nobody here (a server, an image, cloud-init): turns remote access on, trusts what `--trust` names, installs the login service (on Linux, running with nobody logged in), and says how others reach it. Safe to run again
- alto service: Start the server at login, without the app

## MCP tools (alto mcp)
- run: Run a shell command in a terminal the person can see (their work pane, by default), typed at its prompt, and get back only the command's output and exit status as JSON: {output, exit, truncated, took, timed_out}. Refused, saying why, if something else is running there or someone has typed at the prompt.
- wait: Wait until the terminal's program reaches a state (idle, working, needs-you, done; or prompt: the shell back at its prompt), or prints text matching a regular expression. Default: until the prompt.
- read_screen: What the terminal shows now, as text, with where the cursor is: for full-screen programs (an editor, less, top). With `last`, the last lines of its scrollback instead.
- send_keys: Type into the terminal: text, then keys by name (Enter, Escape, Tab, Up, PageDown, F5, q; with C-, M- or S- before it: C-c, M-x, S-Tab). For answering a program; for shell commands, use run.
- work: The work panes linked to this conversation: terminals beside it, here or on other devices, where the other tools act by default.
- list_sessions: The sessions on this device, or on another (`device`), with what each is doing.
- use: Act on this session (on `device`, if given) from now on in this conversation, instead of the work pane; or start one there with new: true. With nothing, back to the work pane.

## Links
- Source: https://github.com/sanford/alto