How Swarm thinks

After reading this page you'll know what happens between "you ask for something" and "a pull request appears", and why a bee never wanders off indefinitely. The contract underneath all of it: No human writes code. A human always reviews.

The lifecycle

Every run follows the same path, whatever started it:

trigger → validation → classification → GitHub auth → runner → three-phase execution → PR (or failure report)

1. Trigger

A run starts from a Slack @mention, a Jira ticket moving to the "AI" status, a comment on a Jira issue or a GitHub PR/issue, a new Semgrep finding ticket, the dashboard's "Run a bee" button, the CLI, a schedule, or a generic webhook. See triggering from Slack for the most common path.

2. Validation

The trigger checks the request before anything expensive happens. Webhooks must carry a valid HMAC signature or they get a 401. Duplicate deliveries of the same event are dropped. If you named a bee and no repo could be resolved, you get an immediate error reply instead of a doomed run. (Swarm agent runs don't require a repo: the agent resolves one from the Space's GitHub sources, or asks you which project you mean.)

3. Classification

Swarm looks at one thing: did you name a bee? If you named a recipe that exists in the catalog (tinfoil-bee, a11y-bee, ...), that bee runs. If you named nothing, or a bee that doesn't exist, the request falls through to the swarm agent, the general-purpose default. This is deliberate (ADR 0055): the swarm agent is the primary way Swarm answers requests, and named bees are shortcuts for well-shaped, repeatable jobs. A typo in a bee name gets you the swarm agent, not a rejection.

4. GitHub auth

Swarm mints a short-lived installation token via the GitHub App (preferred) or falls back to a PAT. The token is injected at launch, expires within an hour, and is never baked into the image, so the bee only holds credentials for the duration of the run.

5. Runner

The run launches in an isolated container: docker run locally, an ECS Fargate task in production. Fresh clone, clean temp directory, no shared state between runs. Bees have submission authority, never merge authority.

Three phases, with budgets

Inside the container, every recipe structures the work into phases, each with a hard cap on actions (tool calls). The canonical shape, using cleaner-bee as the example:

• Phase 1, SCAN (max 15 actions): understand the codebase and find the problems. Some recipes call this INVESTIGATE.
• Phase 2, FIX (max 25 actions; some recipes allow 30): branch off, fix the high-confidence findings. Anything needing a design conversation gets reported, not attempted.
• Phase 3, SHIP (must complete): lint → test → commit → push → open the PR. This phase is non-negotiable.

Some recipes vary the shape (tinfoil-bee adds a Phase 0 triage, max 8 actions, that can end the run early with a verified false-positive verdict), but the pattern holds. A hard backstop caps the whole run regardless of phase.

Why phases and budgets? Bounded, reviewable work. Without a cap, an agent can explore forever and ship nothing. The budgets force a bee to converge: a shipped PR with 5 fixes and a good report beats 20 fixes that never get pushed. Small, finished, reviewable output is the product.

The ending is always explicit

A run never trails off silently. It ends in one of:

• A pull request: the normal outcome, assigned to a human for review.
• A verdict without a PR: e.g. FALSE_POSITIVE, NO_PR_OPENED, or a BLOCKED_* reason, posted back to Jira and the dashboard.
• A pause: the bee asks you a clarifying question in-thread and waits.
• A failure report: the captured error, posted where you triggered from, with a link to the run and its logs.

For the full flow diagram and the machinery behind each step, see the architecture page.