6. Agents#
In this chapter you run a coding agent in a hosted session and steer it from the desk, the couch, or the train.
Why a hosted session#
Coding agents such as Claude Code, Codex, or Pi run for a long time. In a hosted session (chapter 3), the agent keeps running when you close the laptop. You can open the same session on the tablet, check its progress, and answer its questions.
Start the agent in a hosted session as you would in any terminal:
claude # or codex, pi, ...
The overview (chapter 4) shows every agent's screen live. A card with new output or a bell carries a marker, so you see which agent waits for you.
See what each agent is doing#
Agents can tell the terminal whether they are working, waiting for you, done, or failed, with the program status protocol (OSC 7501). mpmux shows it on the session's card in the overview:
| Card says | Colour | Meaning |
|---|---|---|
| Working 40%: … | blue | The agent is running; the text is what it reports. |
| Approve: …, Question: …, Login: …, Needs you: … | amber | It waits for you. |
| Done: … | green | It finished; the mark goes once you have looked at the pane. |
| Failed: … | red | It stopped with an error; also until you look. |
| Bell, New output | coral | No status report, but something happened. |
pi reports its status out of the box; mpmux answers the protocol's support query, so nothing needs to be set up. Other programs can report too, see getting started for agents. Working and waiting marks end when the shell prompt comes back or the program exits.
Progress bars#
When a program reports progress, a thin bar runs along the top of its pane, as in Ghostty: blue with the percentage, a sliding segment when the program does not know how far it is, yellow while paused, red after an error. Programs report progress with the ConEmu sequence OSC 9;4 (systemd, winget, and other tools send it) or with a progress value in OSC 7501. The bar goes away when the program removes it, at the next shell prompt, or when the program exits.
mpmux does not guess progress from text such as "56% done": only the program knows what its numbers mean.
Watch and steer a run#
With the run monitor, the sidebar shows what the agent is doing: its plan as a checklist (done, running, waiting for you, failed), what it does now, and how far it is. Before a risky command, such as a push, a deletion or a deploy, it asks in a dialog; answer Allow or Deny from the desk or the phone, and add a note if it should do something else. Pause holds the agent before its next step, Stop ends the run.
The run panel stays out of the way: a new run does not open it. A small dot at the right of the top bar shows how the run goes: it breathes while the agent works, glows amber while the run is paused, and is dim when it is your turn. Tap or click it to open the panel on at most half the screen (at the bottom of a phone held upright), and again to close it. Closed, it stays closed until you open it again. The dot is where the top bar shows: on a phone or tablet the line with the connection, on a desktop the tab bar once you have two tabs. With one tab on a desktop, open the dock (the command palette's Toggle Message Sidebar) and pick the run in its menu (☰).
The run monitor is a panel of its own beside the todos sidebar: the dock menu (☰) switches between them, and Split Panel shows both at once, the run below the todos (or below the Viewer). Drag the bar between the halves to share the room.
For Claude Code, install the hooks once (contrib/claude/README.md). For Pi,
link the mpmux-run-monitor extension and skill (contrib/pi/README.md).
Other agents use mpmux-cli run-monitor with the instructions in
contrib/skills/mpmux-run-monitor/SKILL.md. The agent may work in a tab you
are not looking at; its run and its questions still reach you.
The prompt pie#
Typing long prompts on glass is slow. The pie menu has a Prompts entry (down left) with ready-made prompts. Choose one and mpmux types it into the active pane and presses Enter.
| Entry | Sends |
|---|---|
| Plan | write a concise plan for the current task |
| Continue | continue with current task |
| Test | run focused validation for current changes |
| Review | review current changes and point out risks |
| Commit | commit the completed work |
| Summarize | summarize current state and next steps |
| Compact | /compact keep current task and next steps in mind |
| Answer | /answer |
Compact and Answer are slash commands. They work in agents that know them.
For a free prompt, use voice input (chapter 5) or the keyboard.
The todos sidebar#
The agent can keep its plan as todos in your project, shown in a sidebar where you pick the next piece and send the agent to it. Chapter 12 shows how.
Give the agent the controls#
An agent inside mpmux can open panes, run commands in them, read their
screen, and tell you about results. Getting started for
agents lists the commands and has a snippet for your
AGENTS.md or CLAUDE.md. It also shows how to set up Claude Code and pi so
that each turn is marked in the scrollback.
Let the agent show you its results#
An agent can put a chart, a table, a report or a page in the Viewer beside
the terminal instead of describing it (mpmux-cli media show, chapter 7),
or an interactive canvas it wrote (chapter 11). In a hosted session these
reach your tablet too. The media skill tells the agent when to;
mpmux-cli agents install installs it into Claude Code and Pi with mpmux's
other agent integrations (chapter 12).
Tips#
- Run each agent in its own tab. The overview search matches the title the agent sets and the text on its screen, so you find it by its task.
- Use Terminal → Interrupt in the pie menu (up left) to stop an agent at once. It sends Ctrl+C.
Next#
Chapter 7 shows how to move files, show images in the terminal, and use the Viewer.