Agents and their state
Which coding agents st follows, how they report, the states a pane can be in, and what the apps do with them.
st looks at every pane on the machine's tmux server and recognises the
coding agents running there. For each one it keeps a state, and the apps
show it.
The terminal itself is shared
Whatever is running at the prompt — an agent, a build, a log — is what you carry on from your phone. There is nothing to connect up: what is shared is the shell, not the thing inside it.
whatever you type
your shell · tmux, psmux or zellij · your machine
Supported agents
| Agent | How st follows it |
|---|---|
| Claude Code | hooks, and the screen |
| Codex | hooks and its notify program, and the screen |
| Gemini CLI | hooks (st 0.3.71 or later), and the screen |
| opencode, Pi | hooks (a plugin or extension st writes), and the screen |
| Kimi Code, Qwen Code | hooks, and the screen |
| GitHub Copilot CLI, Aider, goose | found, but no hooks for them yet |
Hooks are installed once per machine:
st hooks install
st hooks status # every agent found, and whether its hooks are inst offers this the first time it runs; the apps can do it too. Without
hooks st still reads the screen and gets most states right; with them,
turns, permission requests and subagents are exact. What the hooks send, and
what they never send, is in Agent hooks.
States
| State | Meaning |
|---|---|
| working | A turn is running. Also while the agent has stopped but subagents it started are still at it. |
| waiting | It is blocked on you: a permission prompt, a question, a plan to approve. |
| done | The last turn finished, and nothing has been typed since. |
| error | The last turn ended in an error. |
| idle | The agent is open but has not started a turn, or you have looked at it since it finished. |
| unknown | Not an agent st knows, or one it cannot read without hooks. |
When st can read what a waiting agent asks, the state carries the
question and its options. That is what lets a phone answer it.
A session takes the most urgent state of its panes, and a machine the most urgent of its sessions, in the order waiting, error, working, done, idle.
Screens that show states
- Next to each window and session, in the desktop app, the web terminal
and the phone apps' window lists: a state dot, and
?on a window whose agent waits for you. - Notifications on your phone, when the machine is signed in: an agent that asks (with the options as buttons), a turn that finished or failed. Short turns, under 30 seconds by default, do not notify, and nor does a session you are already looking at on that device. Quiet hours and per-machine switches are in the apps' settings.
- One Live Activity (iPhone) or Live Update (Android) for the whole account, with a row per machine. It carries names, states, counts and times, never what is in the terminal.
- Widgets on the iPhone and Android, with the same names and states.
The details are on each app's page: iPhone, Android, Desktop app.
Subagents and teams
A Claude Code subagent runs inside its agent, in no pane of its own; st
sees it through the hooks and lists it under its agent, with its type, the
short description it was given, and whether it is running or done. A Claude
Code agent team puts each teammate in its own pane: each is an agent of its
own, listed under its lead. Watch it work
shows both.
Workers started by another agent are ordinary agents in their own windows, with the same states. Orchestration is about them.
Chat
A pane running Claude Code or Codex can be read as a conversation instead
of a screen: your messages, the agent's answers, each tool it used folded
into one line. Terminal | Chat switches between them in the desktop app,
the web terminal and the phone apps. st reads the transcript the agent
writes on the machine and serves it on the machine's own address; it does
not go to the control plane. Typing in the chat puts the text into the
agent's own input box, never over a question it is showing. st 0.3.57 or
later.
Usage and past sessions
st usage and the apps show how much of their plan's 5-hour and weekly
limits Claude Code and Codex have used, and when each resets; the phone gets
a notification at 80 % and 95 %. st history and the apps' History list
past Claude Code and Codex sessions, and resume one in a new window. See
AI usage and past sessions.