# Automations
## Overview [#overview]
Automations run an agent session against a project on a schedule, like a cron job, but the output is a live workspace you (or a teammate) can open, review, and continue interactively.
Typical uses:
* **Standups**: a nightly summary of PRs, issues, and activity
* **Release notes**: generate a draft from merged commits
* **Audits**: scan for security issues or deprecated APIs each morning
* **Dependency sweeps**: check for outdated packages weekly
The list shows 7-day health stats (Active, Created, Failed), groups enabled automations by soonest run under **Up next**, and splits into **Mine** and **Team** tabs. Team automations are read-only; only the owner can edit, pause, run, or delete one.
## Requirements [#requirements]
* **A Pro plan**: Automations are a [Pro feature](https://superset.sh/pricing). Creating, running, and resuming an automation needs a Pro or Enterprise subscription on the organization, from the app, the CLI, or the SDK alike. An organization that downgrades keeps its automations and can still edit, pause, or delete them, but they stop firing until it upgrades again.
* **A project, or session mode**: automations usually run against a v2 project linked to a GitHub repo. Pick **No project** and each run creates a [session workspace](/workspaces#sessions) instead.
* **A target device**: The run fires on the device you pick when creating the automation.
## Create an Automation [#create-an-automation]
Click **Automations → New automation** and fill in:
* **Title**: how the automation appears in the list
* **Prompt**: the instructions the agent will receive at dispatch time. Supports markdown, `@file/path` mentions (scoped to the selected project), `:emoji:` shortcodes, and `/` slash commands.
* **Device**: which host runs the session. Defaults to this device.
* **Project**: the v2 project the session runs against, or **No project** for a session per run.
* **Schedule**: pick a preset or enter a custom RRule. Times use your timezone at creation.
* **Agent**: Claude, Codex, Amp, or anything else you've set up under **Settings → Agents**.
## Triggers and Schedules [#triggers-and-schedules]
On the automation's detail page, schedules live in a **Triggers** list; each row shows its cadence and next run inline. **Add Trigger** adds another schedule: one automation can fire on several cadences, and every automation needs at least one trigger. Hover a row to remove it. Edits are drafts until you press **Save triggers** (or **Discard**).
Schedules are stored as [RFC 5545 RRules](https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.5). The picker has presets for common cadences (Hourly, Daily, Weekdays, Weekly); use **Custom** for anything else. Custom rules are validated inline: invalid rules, rules with no upcoming runs, and one-shot rules (`COUNT`/`UNTIL`) are rejected before saving.
Examples:
* `FREQ=DAILY;BYHOUR=9;BYMINUTE=0`: every day at 9:00 AM
* `FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0`: weekdays at 9:00 AM
* `FREQ=WEEKLY;BYDAY=FR;BYHOUR=17;BYMINUTE=0`: every Friday at 5:00 PM
## Runs [#runs]
Each time an automation fires, a **run** is recorded. Runs show up on the automation detail page's **Run History** tab with a status:
* **created**: the workspace was created on the target device (a run's success state)
* **creating**: the handoff is in flight
* **failed**: the device was offline at fire time or the handoff broke. The error shows inline under the run, selectable for copying
The schedule advances to the next occurrence either way.
When a run dispatches in "new workspace" mode, a fresh workspace is created from the project's repo for that run (or a fresh session workspace when the automation has no project). Open it from the run row to see the agent's work.
## Pause, Run Now, Delete [#pause-run-now-delete]
From the automation's detail page (**Settings** tab):
* **Pause**: flip the Active switch. Runs are kept, and each schedule row on a paused automation still shows when it *would* next run, so schedule edits are previewable.
* **Run now**: dispatches immediately. The run appears under **Run History** within seconds.
* **Delete**: in the ⋯ overflow menu; removes the automation and its run history.
## Retry Failed Runs [#retry-failed-runs]
On the **Mine** tab, **Retry all** appears in the header when any of your automations' latest run failed, and re-dispatches all of them. The **Failed** stat card filters to failing automations. Hover a row you own for **Run now** to re-dispatch one.
## Limits [#limits]
* **At-least-once delivery**: Automations may dispatch more than once in rare cases (e.g. dispatcher retries). Design prompts that are safe to re-run.
* **No agent-outcome tracking**: a successful run means its workspace was created; the detail page doesn't show whether the agent's work succeeded. Open the workspace to see what happened.
* **Offline hosts fail the run**: if the target device is offline at fire time, the run records as failed and the next occurrence is scheduled normally. Use **Retry all** once the device is back.
* **One prompt per automation**: Each automation has one prompt (though it can have several schedule triggers). To run multiple prompts on a schedule, create multiple automations.
## CLI [#cli]
```bash
superset automations list
superset automations create --name "Nightly audit" --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" --project --prompt-file prompt.md --agent claude
# Omit --project and --workspace for session mode (a session workspace per run)
superset automations create --name "Scratch triage" --rrule "FREQ=DAILY;BYHOUR=8;BYMINUTE=0" --prompt "…"
# Each run's workspace carries the automation's tags and groups into the matching
# sidebar folders. Default tag: "automation" — runs collect in an "automation"
# folder per project. --tag (repeatable) files them elsewhere; clearing the tags
# in the editor opts out of grouping.
superset automations create --name "Nightly audit" --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" --project --prompt "…" --tag audits
superset automations update --session # switch an existing automation to session mode
superset automations get
superset automations run
superset automations pause
superset automations resume
superset automations delete
```