# Scheduled Tasks

> A trigger is a prompt, an agent (or a whole team) and one question: what makes it run?

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-10-02
- Web page: https://agentsroom.dev/docs/scheduled-tasks

## What it does

A trigger is a prompt, an agent (or a whole team) and one question: what makes it run? Scheduled tasks answer with the clock (every N minutes, hourly, daily at one or several times, weekly, monthly), with your AI subscription's quota window (when the quota comes back, or at the tail of the window before it resets), or with nothing at all: an **On demand** trigger has no clock and no endpoint and runs only when you press its button, which is what a job you repeat but never on a rhythm looks like (build the app, cut a release). When it fires, AgentsRoom starts an agent in the project, hands it your prompt as its first message, notifies you, and archives the run so it can be read later from any machine of the account. No cron expression is ever typed.

## Where to find it

- Inside a project, agents panel: **Scheduled agent** ("Add an agent that runs on a schedule") opens the **Triggers** panel. The same panel holds webhook triggers.
- Inside a project, agents panel: **On-demand agent** ("Add an agent you start yourself, with its brief already written") opens the same panel straight on a new on-demand trigger.
- With no trigger yet, the empty panel shows five cards: **On a schedule**, **On your quota**, **On an event**, **When work ships** (since 2026-09-30, see [Webhook Triggers](https://agentsroom.dev/docs/webhook-triggers.md)), **On demand**; clicking one opens the editor preset on it.
- The list shows each trigger's next run (or its last one, for a webhook and an on-demand trigger), enable switch, **Run now**, **Run history**, and a filter (**All**, **Scheduled**, **Quota**, **Webhooks**, **On ship**, **On demand**), each carrying the icon of its kind. Filtering on a kind you have none of says which one is missing (**No scheduled agent yet**, **No quota agent yet**, **No webhook agent yet**, **No on-ship agent yet**, **No on-demand agent yet**) instead of a blank list. The Command Palette also searches triggers.

## How to use it

1. **New trigger**. Fill **Name** (may contain `{{date}}`, `{{time}}`, `{{datetime}}`, resolved at each run) and **Prompt**.
2. Under **Trigger**, pick **On demand** (nothing else to set: it waits for you), or **Scheduled** and a **Frequency** (Minutes, Hourly, Daily, Weekly, Monthly) with its time fields; on Daily and Weekly, **Add a time** fires the task at several times of day (up to six). Or pick **Quota**: **What fires it** = **When quota returns** or **Before reset**, then the **Quota window** (5-hour, Daily, Weekly, Monthly), **Run before reset** (30 min to 4 h) and **Minimum used** (Any usage, 50%, 80%, 90%).
3. Under "Who runs it", choose **One agent** (Role from the same catalogue as Add Agent, Provider, Model, Reasoning effort) or **A team** (the prompt goes to the team's first step).
4. **Advanced** carries what an unattended run needs: **Permission mode** (Inherited, Autonomous, Manual), account, **Browser access**, **Always memorize**, **Default skills**, **System prompt**, CLI options and environment variables. Empty means inherited.
5. **Machines**: **All machines** or chosen ones, so two computers with the project open do not both fire the same run.
6. Options: **Enabled**, **Notify when it starts**, **Close after inactivity** (with a delay), **Catch up if missed**, **Wake the machine** (Inherit, Wake, Do not wake). **Save**.

**Run now** fires immediately and opens the agent's tab. Right-clicking it (or long-pressing, or pressing the down arrow) offers the other machines of your account that hold this project, so a build can be fired on the machine that has the toolchain from the laptop you happen to be sitting at; the run is stamped and archived over there and shows up in the same history. The mobile app has the same button, and always asks which machine, since a phone runs nothing itself. In **Run history**, **Open** reopens a run still alive on this machine, **Read** opens the archived transcript of any past run, including runs from another machine. Only a run you reopened that way gets a terminal tab and comes back after a restart: a run working in the background does not, since its brief is delivered once, when it fires.

**History** (editor, existing trigger): every save that changes a trigger (name, prompt, schedule or webhook, agent or team, provider, model, options) keeps the previous configuration; runs and the last run date are not versions. The selected version is compared line by line with the draft (name, prompt, then one line per option), and **Restore this version** loads it in the editor as unsaved edits: save to keep it, the current state stays in the history.

## Settings

- `wakeForTriggers` (global, Settings > Terminal > Wake the machine for scheduled triggers; project override in Project settings; per-trigger override in the editor): arm the operating system's wake timer for the next run. Off by default. macOS and Linux need a one-time administrator authorization shown in the same place, revocable there.
- `autoLaunchAgentsAtStartup` (global, Settings > Terminal): allows runs missed while the app was closed to be caught up at launch; off means nothing starts until you ask.
- `keepAwakeWhileWorking` (global, Settings > Terminal): keeps the machine from sleeping while the run's agent works.

## Agent tools (MCP)

- `triggers_list`, `triggers_get`: read the project's triggers and their runs.
- `triggers_save`: create or update a trigger (schedule, quota, webhook or manual mode, agent or `teamId`).
- `triggers_delete`: remove one.
- `triggers_run`: fire a trigger now; returns the agent id, or the run id for a team.

## Providers

All providers: the run goes through the same launch path as a manual agent. The quota frequency depends on AgentsRoom being able to name an exact reset moment for the account: from a structured source (the Claude quota API, the Codex usage API or its last session snapshot, the Grok, Cursor, Kimi and OpenCode usage APIs, Antigravity's `agy /usage`) or from the reset sentence printed in the CLI's own usage panel, which is now read back into a date for **Kimi** and **Grok** too. When nothing can be resolved the editor says so and offers no window.

## Mobile

Present. The phone reaches the project's triggers from the workflow glyph in the project header, with the same list, the same four kinds and their icons, the same filters and named empty states, the same editor, history, machine scope and agent / team choice, using the same words. Two differences, both deliberate: **Run now** always asks **Run on which machine?** (and says "None of your machines is online right now." when none is), because a phone runs nothing itself; and a quota trigger shows **Waiting for a quota reading** until a desktop has read the provider's usage window. The editor has the same **Version history**; the version is loaded into the phone's editor and saved like any other edit.

## Limits

- Runs fire while AgentsRoom is open on an allowed machine. A missed run is caught up on the next launch unless **Catch up if missed** is off, in which case a slot missed by more than ten minutes is recorded as **Missed** on the task row.
- Wake timers: a laptop on battery may ignore them; keep it plugged in. A closed lid on power works. On Windows, wake timers must be allowed in the power plan.
- Quota precision is that of the usage scan (about 10 minutes through the Claude OAuth API, 30 through the usage terminal), so a quota run starts shortly after the boundary.
- Team runs started by a trigger share the project root (no worktree) and have no per-run transcript archive (their consoles are the record). **Close after inactivity** applies to them too since 1.184.0: the run closes once its consoles have been idle for the delay, even while their tabs are on screen (before, a team run whose consoles were visible never closed on its own). Without that option, a finished team run waits for **Finish run** (or `team_finalize_run`).
- **Close after inactivity** now survives a restart or a crash: a background run's console is not brought back on launch, so it can no longer escape the timer and stay open until you close it by hand.
- **Close after inactivity** judges a run on what its agent does. When the CLI draws a full-screen interface whose state AgentsRoom cannot read (Antigravity, Mistral Vibe, Copilot, or Claude Code in fullscreen mode without its hooks), the run counts as inactive once its terminal has printed nothing for the delay (since 1.199.0; before, such runs never closed on their own). A run you are looking at (shown in the project you have open, window in front, you at the keyboard) is never closed, and the delay starts again once you leave it; a run sitting in a tab you are not looking at is closed like any other, its transcript archived first.
- Every live run uses one of your plan's parallel agents. When they are all taken, a new run waits and starts by itself as soon as one is freed: **Close after inactivity** is what frees them on an unattended machine.
- The run history of a trigger keeps its five most recent runs on the machine; when an older one falls out, its console is closed with it. The transcript of any past run stays readable with **Read**.
- Times use the machine's local timezone.

## Common questions

- **Does it run when AgentsRoom is closed?** No. It is an in-app scheduler with catch-up, not a server-side cron. Turn on **Wake the machine** to have the computer wake for the run.
- **Will the agent get stuck on a permission prompt at 3 AM?** Not if the task's **Permission mode** is **Autonomous**; your manual agents on the same provider keep asking.
- **Can I run an agent when my Claude quota resets?** Yes, the **Quota** trigger with **When quota returns**.
- **Can I stop my scheduled agents when my quota is almost gone?** Yes, with a quota rule: **New rule** with the action **Block a launch** and **Which launches** set to **Scheduled agents** blocks scheduled launches of that provider once the threshold is reached (for example 99 %). A blocked trigger starts no agent and sends a notification instead. See [Quota Rules](https://agentsroom.dev/docs/quota-rules.md).
- **Does a trigger that runs a team respect quota rules?** Yes, since 2026-09-23. The run is judged on the provider and account of the team's first agent; if a rule blocks it, the run does not start (or stops with "Quota rule "X": run stopped"), and every agent of the run keeps the trigger's origin (scheduled or webhook) for the rule's **Which launches** scope.
- **Can a quota threshold start a trigger?** Yes: a quota rule with **Run a trigger** starts an existing trigger once per quota window.
- **Can a task run twice a day?** Yes, **Add a time** on a Daily or Weekly task.
- **Where are tasks stored?** Per project, synced to your account, with a local cache.
- **My trigger runs stay open although Close after inactivity is on. Why?** Before 1.199.0, a run on a full-screen CLI (Antigravity, for example) never closed on its own, and neither did a run sitting in a terminal tab, even one nobody looked at. Update the app: such a run now closes once it has done nothing for the delay. Only the run you are actually looking at stays open.
- **I changed the prompt of a scheduled agent and the results got worse. Can I go back?** Yes: open it, **History**, pick the earlier version, **Restore this version**, then save. The last 50 versions are kept, and a restore can itself be undone.

## Related

- [Webhook Triggers](https://agentsroom.dev/docs/webhook-triggers.md): the same panel, fired by an outside event.
- [Message Queue](https://agentsroom.dev/docs/message-queue.md): the one-shot version of quota timing.
- [Quota Rules](https://agentsroom.dev/docs/quota-rules.md): block, redirect or adapt trigger launches when a quota is high.
- [Keep the Machine Awake](https://agentsroom.dev/docs/keep-awake.md): what keeps the machine up while the run works.
- [Agent Teams](https://agentsroom.dev/docs/teams.md): point a trigger at a team.
- [Agent Notifications](https://agentsroom.dev/docs/agent-notifications.md): the start notification and mobile push.
- [Prompt References](https://agentsroom.dev/docs/prompt-references.md): point a trigger at a library prompt instead of pasting it.