# Timer MCP tools

Timer tools schedule future user turns for Solo agent processes. When a timer fires, Solo types its `body` verbatim into the delivery agent's terminal and submits it, so it arrives as a fresh user turn. Turn on **Timers** in **Settings > Agents > Timers** to expose these tools.

## Tools

- `timer_set` — Schedule a durable timer that fires after `delay_ms`. Set `loop: true` to repeat at the same interval, or `repeat_every_ms` for an explicit repeat interval; omit both for a one-shot timer.
- `timer_fire_when_idle_any` — Schedule a one-shot timer that watches one or more Solo terminals or agents and fires when any watched non-idle process enters [Solo runtime idle state](../agents/idle-detection.md), or when `max_wait_ms` elapses. If any watched process is already idle, no pending timer is created; the response status is `already_satisfied` and includes `already_idle`. When all watched processes are busy and a timer is created, the response includes `waiting_on`.
- `timer_fire_when_idle_all` — Schedule a one-shot timer that fires when all watched processes are idle, or when `max_wait_ms` elapses. Already-idle processes count as satisfied; if all are already idle, no pending timer is created and the response status is `already_satisfied`.
- `timer_cancel` — Cancel one pending timer.
- `timer_pause` — Pause one pending timer owned by the current actor.
- `timer_resume` — Resume one paused timer owned by the current actor.
- `timer_list` — List scheduled timers owned by the current actor in the project, along with recent delivery outcomes (`input_deliveries` and `durable_deliveries`) and `delivery_capacity`. Solo holds at most 256 pending or attempted timer deliveries across the app; at that limit, timers stay scheduled until space frees up, and `timer_cancel` on a listed pending or attempted timer frees it.

## Delivery

Every timer delivers to exactly one Solo agent process. Omit `delivery_process_id` to deliver to the session's own identified Solo agent, or pass it to deliver to a different Solo agent. On idle timers, watching and delivery are separate: the `processes` list is only the watch list, and `delivery_process_id` chooses who wakes up. Do not re-identify the session to change delivery.

Timer bodies go through the same automated input queue as `send_input` messages, so the same rules apply: deliveries to one agent arrive in order, wait while you've typed in that terminal recently or while the program [reports that it is blocked](../terminal/program-status.md), and arrive as a bracketed paste when the agent supports it. See [How agent messages are delivered](./process.md#how-agent-messages-are-delivered).

- A timer that fires while its target is restarting, or waiting to auto-restart after a crash, is delivered once to the new run.
- A timer that fires at a stopped or exited process is marked undelivered and isn't retried.
- A partial or uncertain delivery is never replayed into the running process or its replacement.
- Repeating timers whose target process was deleted are cancelled.
- Fired and cancelled timers older than seven days are pruned automatically.

Because `body` arrives verbatim as a fresh user turn, write it as a self-contained instruction: include process IDs, scratchpad IDs, and the next action, and prefer plain prose over raw XML-like tags or code-block-heavy payloads.

Each `processes` entry on idle timers may be a raw Solo process ID, a process name, or an object with `process_id`/`process_name`.

## Notes

Timers require an owning actor. Solo-launched agents are normally identified automatically; external actors can create timers only by passing an explicit `delivery_process_id`. See [Agent and terminal tools](./agent-terminal.md) for session identity.

Use idle-triggered timers for worker quiet periods. For service startup readiness, prefer `wait_for_bound_port` from [Services tools](/docs/mcp-tools/services).

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/mcp-tools/timers