# Agent Status Tracking

> Every agent carries a live status you can read from anywhere in the app: Working (the agent is processing or editing, with an elapsed timer counting up), Done (it finished its turn; unread completions are highlighted), Needs input (it is blocked on a question or a permission, the most urgent state) and Idle (ready for a prompt).

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-10-01
- Web page: https://agentsroom.dev/docs/agent-status-tracking

## What it does

Every agent carries a live status you can read from anywhere in the app: **Working** (the agent is processing or editing, with an elapsed timer counting up), **Done** (it finished its turn; unread completions are highlighted), **Needs input** (it is blocked on a question or a permission, the most urgent state) and **Idle** (ready for a prompt). While an agent works, its card shows a short summary of what it is doing (editing a file, running tests). Projects aggregate their agents: the sidebar shows how many are working, done or waiting, so you can run a dozen agents across projects and always know who needs you first.

## Where to find it

- Agent cards and terminal headers inside a project: colored dot, timer and activity summary.
- Sidebar: per-project badges (**2 agents waiting for input**, **3 unread agents**) and, on hover, the last message of each agent.
- Agents rail: open agents grouped by what they need from you, **Needs you**, **To review**, **Working**, **Available**, **Done**, above **Inactive**; each section shows its count and folds (except **Needs you**). Three counters above the list (**Needs you**, **To review**, **Working**) filter it to that state, and **Mark all as seen** clears the **To review** pile. Each row reads « title » then « short role · last message »; an open agent with nothing to report says **Ready** and the title of its previous session.
- Title bar: the needs-input pill; Open Space and the Dynamic Island show the same states outside the project.
- Session info panel on an agent: **Status**, how long it has been in that state, exchanges, tool uses, tokens.

## How to use it

1. Glance at the dot: pulsing means working, red pulsing means it waits for you, green means done, none means idle.
2. Click a project badge or the needs-input pill to jump to the blocked agent and answer it.
3. Use the elapsed timer to spot a step that runs unusually long, and the activity summary to see what it is doing without opening the terminal.

## Settings

- `notificationSound` and `needsInputSound` (global, Settings > Notifications): sounds on the transitions to Done and Needs input.

## Agent tools (MCP)

- `agents_list_live`: list the agents currently running with their status.
- `agents_report_status`: an agent publishes its own progress or blocking question so the status is accurate even when its output is hard to parse.
- `agents_get`: details of one agent, status included.

## Providers

All providers. Status is detected from the terminal stream of each CLI (tool calls, file writes, prompts, completion) with per-provider rules; on a full-screen CLI the summary may be shorter. The "needs input" detection covers permission prompts and questions of every supported CLI.

## Mobile

Yes. The phone shows the same statuses and colors on agent rows and terminal screens, and the **Companion** tab mirrors the global state (Idle, Working, Needs input) with a history of Done and Needs input events.

## Limits

- The timer measures the current working step; it resets when the agent finishes or changes state.
- The activity summary depends on what the CLI prints; a silent tool call shows no summary.
- Statuses are per machine; another desktop's agents appear through [Remote Fleet](https://agentsroom.dev/docs/remote-fleet.md).

## Common questions

- **How is the status detected?** Each agent runs in a real terminal and AgentsRoom reads its output continuously for tool calls, questions and completion signals.
- **Several agents need input at once?** Each shows its own red dot; the project badge gives the count, and the needs-input pill lists them so you can answer in any order.
- **Why is an agent "Done" but highlighted?** You have not looked at it since it finished: the highlight is the unread marker.
- **Can I see status on my phone?** Yes, the mobile app syncs the same statuses over the encrypted relay.

## Related

- [Needs Input Inbox](https://agentsroom.dev/docs/needs-input-inbox.md): the list of agents waiting for you.
- [Agent Notifications](https://agentsroom.dev/docs/agent-notifications.md): alerts fired on Done and Needs input.
- [Dynamic Island](https://agentsroom.dev/docs/dynamic-island.md): the floating global state.
- [Open Space](https://agentsroom.dev/docs/open-space.md): every agent of every project on one screen, sorted by urgency.