The guide for agents

alto guide prints this page, from the alto that’s installed, so it always matches the build. Alto’s hook for Claude Code points an agent at it when a conversation starts in an Alto session, and the skill alto agents install puts in place points every agent at it.

Where you are

A terminal in Alto is a session. Sessions keep running when windows close, and other devices reach them over Tailscale. $ALTO_SESSION is your session’s id. A person may be watching your terminal in a window or on their phone, and can type into it too.

Finding sessions

alto ls                      # this machine's sessions, and what each is doing
alto ls --all                # every machine's: addresses like studio:3
alto ls --waiting            # the ones waiting for a person, everywhere
alto fleet                   # the same, as a view (for a person, not for you)

A session’s address is machine:id, and works wherever an id does: alto capture studio:3. --on MACHINE does the same for a whole command.

Reading and typing

alto capture studio:3 --last 40     # its screen and scrollback, as plain text
alto capture studio:3 --screen      # only the screen (for full-screen programs)
alto send -s studio:3 'make test' --key Enter
alto send -s studio:3 --key C-c     # keys by name: Enter, Escape, Tab, Up, C-c, M-x

Running a command and getting its result

alto run studio:3 -- cargo test         # typed at its prompt; prints only the output, exits with its status
alto run studio:3 --json -- make lint   # {output, exit, truncated, took, timed_out}
alto new --on studio -- npm run dev     # a new session there; prints its id

Waiting and following

alto wait studio:3 --until idle --timeout 10m         # idle, working, needs-you, done, or prompt
alto wait studio:3 --text 'listening on \d+' --timeout 60
alto events --all --json                              # what happens, everywhere, a JSON line each
alto events -s studio:3 --type needs-you,done

wait exits 0 when it happens, 124 after --timeout, 125 if the session ends.

Talking to another agent

Send it a message, and get its reply back as data:

alto call studio:3 message --args '{"text": "how is the migration going?"}' --wait --timeout 10m
alto call studio:3 message --args '{"text": "done yet?", "reply": "{\"type\":\"object\",\"properties\":{\"done\":{\"type\":\"boolean\"}},\"required\":[\"done\"]}"}' --wait --json

The message is typed at that agent’s prompt once it’s idle, one at a time, with who it’s from and how to reply. --wait prints the reply (its words, or the JSON with --json); 124 after --timeout, 125 if the session ends first. reply asks for a reply of that shape (an object, in the schema subset alto describe uses). Without --wait it prints the call’s id and returns.

A line at your own prompt like [alto] Message c1a2b3c4 from studio:2: … is a message for you. Answer it from your session:

alto reply c1a2b3c4 'about half done'          # words
alto reply c1a2b3c4 --json '{"done": false}'   # when it asked for a shape

A reply is refused when it isn’t the shape asked for (the error says what’s wrong), or comes from another session. An agent that doesn’t take messages (a shell, a build) still reads what’s typed: alto send -s ADDRESS 'text' --key Enter, then alto capture ADDRESS --last 40.

Your work pane

If the person gave you a work pane (a terminal beside yours), alto run -- COMMAND with no session runs there, where they can see it. alto work lists yours.

Report what you’re doing

Alto’s hooks report your state for you (working, needs you, done). If something else needs saying: alto report needs-you --why 'pick a database'.

The rules

• Typing into a session is refused while someone is typing there, while an agent there is asking a question, or while it’s paused for agents (alto pause). --force types anyway: use it only when you mean to answer that question.
• Where a rule says agents type only while someone watches, what you type waits until they’re there, then goes through; alto ls says so (“agents wait for a moderator”). Don’t type it again.
• alto kill ends a session’s program for good. Ask the person before ending sessions you didn’t start.
• Everything takes --json. alto --help and alto COMMAND --help say the rest.