Working beside an agent

You talk to an agent in one pane. It works in another, its work pane, where you watch its commands run and can type yourself. The conversation is still the agent’s own interface (Claude Code, Codex). Alto adds the work pane, the link between the two, and commands that give the agent each command’s output and exit status instead of a screen to read.

1. Give the agent a pane.

   In a Claude Code pane, Shell → Open Work Pane (⌘⇧K; Ctrl⇧K on Linux and Windows) splits it and starts a terminal beside it, on this computer or, if you have others, one you pick. Or split, then Shell → Give Pane to Agent to hand over a pane you already have and drive it together.

   From a shell in the agent’s session:

   alto work new              # start a work pane and link it
   alto work new --on studio  # on another computer
   alto work link 7           # link session 7 as the work pane

2. The agent hears about it.

   With Alto’s hooks installed, the next thing you say to Claude Code comes with a short note: it has a work pane, which you can see, and it runs commands there with alto run -- COMMAND. It’s told once, again if the pane changes, and when it’s gone.

3. It works where you watch.

   alto run -- cargo test

   Run from the agent’s session with no session named, this types the command at the work pane’s prompt and gives the agent back only that command’s output, and exits with its exit status. For full-screen programs and prompts:

   alto wait --until prompt    # until the shell is back at its prompt
   alto capture --screen       # what's on screen now
   alto send --key C-c         # press keys there

4. You stay in charge.

   Type in the work pane whenever you like: the agent’s input waits until you’ve stopped for two seconds, so it never lands in the middle of yours. What the agent types is marked typed by claude for a moment.

   Shell → Pause Agents Here (⌘⇧P), or alto pause, stops agents typing there until you resume (alto resume); they’re told “paused by you”. Closing or unlinking the work pane leaves the agent running.

Several work panes

A conversation can have several, on several computers:

alto work                         # list them
alto work new --as db --on studio # name one
alto run --in db -- psql -c '\dt' # pick it by name
alto work unlink db               # take the link away; the session keeps running

What run gives back

alto run waits for the shell’s prompt, types the command and Enter, and waits for the command to end, using the shell’s own marks. Alto adds shell integration to zsh, bash and fish with no setup, still reading your own startup files.

Exit	Means
the command’s own	it ran and ended
124	still running after --timeout (it carries on)
125	it couldn’t run it (something else running, or someone typed at the prompt)

--json prints {output, exit, truncated, took, timed_out}; --max-lines keeps only the last lines (default 2000).

Windows

PowerShell and cmd don’t have Alto’s shell integration yet, so on Windows only run --until-quiet TIME works: it takes what the shell prints until it’s been quiet that long, with no exit status.

Where the agent’s files are

The agent’s file tools still work where the agent runs, not in its work pane. For running and checking things on another computer that’s enough. To change code there, run the agent there (an Alto tab on that computer) and talk to it from here.

Prefer tools to shell commands? See The MCP server.