ConceptsWorkflows

Workflows run without you

A workflow is a worker that runs on its own: on a schedule, or whenever your app, a webhook or CI tells it to. Each run is a normal job, kept with its result and its cost.

Two ways a workflow starts

On a schedule

Cron with a timezone (“0 8 * * *, Europe/Berlin”), or every N seconds, at least 60. Runs in one project folder.

On a trigger

Your app, a webhook or CI calls Swarm with a token that can only start that one worker, and passes what happened.

Schedule or trigger08:00 · webhook · CI
Your workerits standing instructions
Runon its own branch
Result keptreport, diff, cost
Signalok or failed

A run is an ordinary job: own branch, result.

Schedules

You say the time in words; your AI writes the schedule. A few translations:

Every morning at 80 8 * * *

Weekdays at 18:3030 18 * * 1-5

Mondays at 90 9 * * 1

First of the month0 6 1 * *

Every 15 minutesevery 900 seconds

Say this to your AI

Every morning at 8, check the site for broken links and slow pages. Only tell me if something's wrong.

swarm_deploy_worker
swarm_schedule_job

Scheduled: site-checker, daily at 08:00 Europe/Berlin. I'll set up an alert for failed runs too.

Triggers from your app

For “whenever X happens”, your app tells Swarm. Your AI makes the worker and mints a trigger token that can start that worker and nothing else; your app keeps it on the server and calls:

webhook.ts

import { SwarmClient } from '@swarm-agent/sdk';

// A token that can only trigger this one worker (your AI mints it).
const swarm = new SwarmClient({ baseUrl: process.env.SWARM_API_URL, token: process.env.SWARM_TRIGGER_TOKEN });

// In your webhook handler: start a run with what just happened.
const run = await swarm.workers.trigger({
  worker_id: process.env.INVOICE_WORKER_ID,
  payload: { invoice_url: event.url, customer: event.customer },
  idempotency_key: event.id, // the same event never runs twice
});

Good triggers: a new invoice or form submission, a failed CI build, a deploy, an alert from your monitoring, a customer email.

After a job ends: automations

An automation is what Swarm does when a job in a folder ends: ordered steps, each one of your own scripts on the machine, a job for another worker (a reviewer, say), or sending the job back into its own session with feedback, up to the number of rounds you allow. Scope it to every job in the folder, one worker, one job or one schedule; run it when a job succeeds, fails or always. Without one, a job just ends with its branch and your AI merges it.

Say this to your AI

After every coder job here, have a reviewer check it and send it back if it isn't right. Two rounds at most.

swarm_set_automation

Set: when a coder job succeeds in this folder, a reviewer checks it; if the review fails, the job gets the notes back (at most 2 rounds).

Every run is kept

site-checkerschedule · today 08:00no problems · $0.06

site-checkerschedule · Wed 08:002 broken links · $0.07

invoice-readertrigger · Wed 14:12booked INV-2291 · $0.03

Each run has its status, what started it (the schedule or the trigger, with its payload), the result and the cost. Ask “what ran this week?” and your AI lists them; failed runs raise a signal, which is where alerts come in.

Workflows people build

Morning site check

Broken links, slow pages, console errors, before customers notice.

Invoice reader

A new invoice arrives, a worker reads it and books it.

Fix failed builds

CI fails, a coder opens a fix on its own branch.

Weekly content

A banner and a post for this week's sale, every Monday.

For your AI

swarm_schedule_job (cron with a timezone, or every N seconds, at least 60), swarm_set_automation (steps when a job ends) and swarm_list_runs; triggers with the SDK's workers.trigger and a token from workers.mintTriggerToken. Details: ai/tools.md and ai/sdk.md.