Adaptive Swarm

Adaptive Swarm is an execution mode for a Project. Instead of one agent working through a task list, a PM agent assembles a team and writes a plan. It then coordinates worker agents that build in parallel, each in its own git worktree, while QA and E2E agents review the integrated result. You stay in control through approval gates and can steer at any point.

See it first

The Swarm Project overview on snippbot.com has a visual tour: screenshots of each stage, the run-flow diagram, and the two engines and collaboration modes side by side. This guide is the hands-on reference.

Open Beta

Adaptive Swarm is enabled by default in the current Open Beta. To turn it off for a daemon, set SNIPPBOT_SWARM_ENABLED=0: its routes return 404, and scheduled starts are refused. The UI hides the feature when it is built with VITE_SWARM_ENABLED=false. Collaboration modes (below) are also on by default. Set SNIPPBOT_SWARM_COLLAB_ENABLED=0 to make every run isolated.

When to use it

Use a swarm when a goal is big enough to split into interdependent pieces that benefit from parallel work and independent review: a multi-file feature, a migration, or a build-then-test-then-harden effort. For a single focused task, a normal Project or a Loop is simpler.

The kickoff wizard

On the Projects page, Adaptive Swarm opens a five-step wizard (/projects/new/swarm). Reopening a swarm project returns you to the furthest step it reached. You can click back to any step you have already visited.

Expand

Define: Involvement, repository and budget.

1. Define
   • Name and goal: what should exist when the project is done.
   • Project folder (optional): if the folder is already a git repo, the swarm works on it directly.
   • Deadlines & milestones (optional): the PM plans around them (see Timeline and Canvas).
   • Adaptive Swarm setup:
     • Involvement (below).
     • Repository: a new private GitHub repo, local git, or no repo. If the folder’s origin is on GitHub, the GitHub option becomes GitHub PRs on that existing repo.
     • Budget: agents at once, token budget, per-agent tokens, max duration. The per-agent field suggests a cap learned from past runs.
2. Team
   • Pick the PM (required). Workers are optional, because the PM can add them later.
   • Use PM proposal has the PM propose the smallest team that covers the work: one owner per workstream, a reason for each pick, and any contract specialists it needs to hire. Hires marked required are hired automatically.
   • A seat counter warns you past five seats (PM + workers + contract hires). It only warns; it never caps the team.
   • Also on this step:
     • QA and E2E team sizes.
     • A model per stage: Planning, Build, QA review, E2E testing.
     • The collaboration mode.
     • Gate overrides (below).
3. Brainstorm
   • Shape the idea with the PM and the seated team in a live chat. Paste screenshots or attach files as you would in normal chat.
   • Questions agents ask appear as forms in the chat.
   • The side pane’s Agents tab shows who has spoken, why each member is seated, and what they own.
   • If the room’s members don’t match the team, a banner offers Match the team.
4. Plan
   • Choose a plan detail level (low, balanced or high) and Generate plan. If the brainstorm still has unanswered questions, you’re asked to answer them first, or to choose Plan anyway.
   • The plan streams in live: Drafting the team charter → Writing the plan → Auditing the plan. The audit may ask a few design questions, and your answers are folded back into the plan. You can also skip the audit.
   • The rest of the step is described in The plan step.
5. Run
   • Review the summary (Involvement, Repository, Team, Budget) and press Approve plan & start building. That approves the plan gate, and the build starts.
   • The Run step stays your hub for the project: it shows the run’s status and lists every past run. See Run controls.

Expand

Team: per-stage models, collaboration mode and gate overrides.

The plan step

Expand

The plan as a document, with its phases in the table of contents.

Team charter. The PM drafts a charter for the team. For each member it gives a role, up to four responsibilities, and the reason they are on the team. It also flags members it suggests dropping, roles that overlap, and gaps it proposes to fill with a hire. Remove or keep members, or send Ask the PM to revise with a note. The charter is approved together with the plan.

Four views: Document · Flow · Timeline · Canvas.

• Document is the plan to sign off, section by section: an overview, stat tiles, review checkpoints, and a work breakdown. Group it By milestone (milestone → phase) or By owner. Copy as JSON gives you the machine form.
• Flow shows the same tasks as a dependency graph, grouped by phase.
• Timeline and Canvas appear once a run exists. See Timeline and Canvas.

How work is ordered. The plan is split into work phases, and every task belongs to one. A task’s dependencies decide when it can start. Among tasks that are ready, earlier phases go first. Milestones are review checkpoints that can span phases; the PM names which ones pause the run for your review.

Change the plan before you approve it:

• Edit a task’s title, owner, phase, milestone, or what it runs after. You can also + Add task or Drop task. Every edit is checked: the owner and phase must exist, dependencies must be valid, and nothing may form a cycle.
• Drag a task onto another phase or milestone to move it.
• ↻ Regenerate re-plans from the brainstorm as it stands now, with an optional note about what should change. When the brainstorm has moved on since the plan was drafted, a banner says so and offers Regenerate from brainstorm.
• Talk to the PM: ask for changes in plain words. The PM replies with a set of proposed edits, each checked against the plan. Nothing changes until you press Apply N changes, and the set applies as a whole or not at all. Asking to remove a team member makes the PM reassign that member’s tasks first; asking to add someone makes it give them work. On narrow windows the chat opens as a drawer.

Edits are only possible until the plan gate is approved. After approval, you steer the run from the console instead.

The run lifecycle

A run moves through phases: assembly → planning → build → QA → E2E → done.

Build.

• Up to five workers run at once, each in its own worktree. Finished work is squash-merged into the run’s integration branch task by task. A merge conflict goes back to the task’s owner.
• Named milestones pause for your review when they are fully built and other work remains.
• Before QA, a smoke check runs the project’s build, type-check or test collection (whichever applies). A missing toolchain is skipped. A failure becomes a repair task for the PM.

QA.

• Read-only reviewers audit the integrated work in parallel partitions.
• Critical and high findings block. Each one goes back to the owning task, and the fix ⇄ audit loop repeats.
• The default cycle limit is three for QA and three for E2E.

E2E.

• Testers exercise the project with a real browser and screen recording. They save their evidence with the run.
• If a run resumes, partitions that already passed on unchanged code are reused instead of re-tested.

Stage labels. The console, the Run step and /swarm status name the run’s stage, not only its phase. A fix loop runs in the build phase, so a run fixing QA findings reads QA fixes · cycle 1 · 17 findings (9 blocking) · fixes 2 of 5 done, not “build”. The stages are Planning, Building, QA review, QA fixes, E2E tests, E2E fixes and Done. Task counts leave dropped tasks out of the total and list them separately (41 of 46 done · 9 dropped). A dropped task is shown greyed out, not as a failure.

Escalations. If QA or E2E gets stuck (it hits its cycle limit or stops making progress), the run raises an escalation with three choices:

• Accept as-is.
• Change approach. You can attach guidance that steers the redo; this resets the cycle count.
• Drop task.

A QA/E2E escalation always waits for your decision, at every Involvement level. Deciding it resumes the run. A stalled build offers Retry, Deliver partial or Abort run.

Involvement levels and gates

Involvement sets how much the swarm checks in with you. Each checkpoint is a gate in one of three modes:

• require: you decide.
• notify: it proceeds, and you can veto it within a grace window (five minutes by default).
• skip: no gate.

The wizard defaults to Balanced.

Gate	Strict	Balanced	Autonomous	Full
Team assembly	require	require	require	notify
Plan approval	require	require	require	notify
Phase transition (QA → E2E)	require	require	skip	skip
Per-task gate	require	skip	skip	skip
Milestone checkpoint	require	require	require	notify
QA findings	require	skip	skip	skip
E2E sign-off (final)	require	require	require	notify
Design decisions	require	high-impact only¹	skip	skip
Repo operations	require	require	require	notify

¹ High-impact means decisions about schema, spend, security, or anything public-facing.

How gates behave:

• Gates that need you never time out. A reminder is re-sent every six hours, and time spent waiting on you is not charged to the duration rail.
• Team, plan and milestone gates pause the run while they wait, and deciding them resumes it.
• Headless runs (scheduled runs with no conversation) treat every gate as Full.
• Danger floor. A set of high-consequence tools always asks a human, even at Full: GitHub, database queries, device commands, and messaging channels.

Gate overrides. On the Team step you can override any gate kind for this swarm. For example, keep Plan approval on require at Autonomous, or set Team assembly to skip.

Collaboration modes

Collaboration mode decides whether agents work heads-down or talk to each other during a run. It’s set per run and safe to change between runs:

• Isolated (default): a coordinator hands tasks to isolated workers, with no cross-talk and a deterministic roll-up. Fastest and cheapest.
• On-demand: the PM pulls. It asks specific agents for input when it needs their expertise and organizes the answers.
• Collaborative: an open floor. Any agent chimes in when relevant and stays quiet when not, and low-signal replies are muted. Agents draw on their identity and memory, while the PM organizes every voice. Non-isolated runs get a shared room and peer DMs, shown in the console feed.

Contract agents

When the team lacks expertise that a task needs, the PM can hire a contract specialist. It is a lightweight agent with its own persona and skills and no workspace, and it exists only for the run. Contract hires you accept on the Team step bind the plan: that work must go to a contract agent with exactly that name, and the plan sign-off reports any seat left unstaffed. A run can hire up to eight specialists by default. Afterward, you can promote a useful one to a permanent, workspace-backed agent from the console’s Team tab.

The execution console

Open execution console (or /projects/<id>/execution) puts the run on one screen.

Expand

Stage rail and controls across the top, the Console on the left, the plan on the right.

Header.

• A stage rail (Plan — Build — QA — E2E — Done) that names the current stage.
• Task progress, budget tokens, and a Live / Not driven / Reconnecting… status.
• The run controls.
• The ⋯ menu: Usage and metrics, Repository, Run details, New run… and Restart….

Console (left).

• Gate cards that need you.
• Tabs for each phase (Assembly, Planning, Build, QA, E2E), with a Needs you chip that jumps to waiting gates.
• Agent filter chips, and a search of the room history.
• The steering box. Your message goes to the PM, which applies it on its next turn. You can attach files (specs, screenshots, reference data) the same way you would in chat.
• A pulse line that says what the team is doing right now. Long feeds fold repeated updates.
• The minimize button folds the Console to a thin rail, so the right-hand tabs get the full width.

Tabs (right).

• Plan: Document | Board | Flow. Each task’s ⋯ menu pre-fills a steering message: Ask PM to re-run…, Ask PM to audit…, Ask PM for execution details…, Comment….
• Team: Members | Org chart. Members shows the integration branch, the final merge or PR target, View integration diff, enlisted agents, and contract agents.
• Findings: QA and E2E findings by severity.
• Files: draft files and final outputs, with preview and download.
• Timeline: Timeline | Canvas (below).

Timeline and Canvas

The Timeline view puts the plan on a calendar. It shows real dates for finished work, a forecast for the rest, your deadlines and milestones, and how late a row runs past a deadline.

Canvas has the PM generate a board with three parts:

• the timeline;
• a map of the app’s screens;
• each screen as it is now, next to a mockup of what it will be next.

Generating the canvas is charged to the run’s budget.

Deadlines you confirm (including those entered in Define) go into the PM’s prompts. The console shows a pinned notice when the forecast slips past one. The notice is advisory only and never stops the run.

See Project Timeline & Canvas for the details.

Run controls

Expand

The Run step: status, controls, and every run of this swarm.

• Pause / Resume: pause the run (work already in flight drains first), then pick up where it left off.
• Stop: graceful. Tasks in flight finish first, and the header says Stopping… until they do.
• Stop now: cancels tasks in flight and returns them to To-do.
• Continue: resumes a paused or stopped run in place. If the run’s worktree folders were deleted, Continue rebuilds them from the run’s branches. You can raise the budget when you continue.
• Restart…: deletes this run’s worktrees and swarm/<run>/* branches, then starts a fresh run. A preview lists exactly what will be deleted and what will be kept. It never touches the project’s own files, branches or remote.
• + New run: starts another run of the same swarm. A project has only one live run at a time.

Buttons that can’t act right now are disabled, and their tooltip gives the reason.

Git cadence

Repo mode controls how work lands:

• No repo: the deliverable stays in the shared workspace; there is no git.
• Local git (the default): each worker builds in its own worktree. Worktrees are kept beside your repo at <repo>.swarm-worktrees/<run>/<agent>, never inside it. Finished work is squash-merged into swarm/<run>/integration, and you can review the diff in the app.
• GitHub PRs: the same cadence, with real PRs on a new private repo or on your existing repo. A token is read from SNIPPBOT_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN or config.toml. Failing those, the swarm uses your gh CLI login.

How the final land works.

• After your sign-off, the integration branch is squashed in a scratch worktree, and your base branch is fast-forwarded to the result. In GitHub mode, the final PR is squash-merged instead.
• The swarm never merges into or resets your own checkout. If uncommitted changes in your checkout would be overwritten, it refuses before doing anything.
• If the base can’t be moved, the commit waits on swarm/<run>/land, and the run pauses with instructions.

Budget rails and cost

Expand

Usage and metrics: live meters, cap suggestions, and spend by phase.

A run is bounded by:

• agents at once (at most 5);
• a token budget for the whole run;
• a per-agent token cap;
• a max duration;
• QA and E2E cycle limits.

When a run hits a rail, it pauses (so you can resume it) rather than failing.

Budget tokens. Caps count budget tokens. Cached re-reads count at a tenth; fresh input, cache writes and output count in full.

Usage and metrics. Open it from the ⋯ menu. It shows:

• live meters and a burn rate;
• the per-agent limit, with a suggested limit learned from past runs (and a note when many agents hit their cap);
• Budget tokens by phase: assembly, planning, build, QA, E2E, collaboration and design.

Provider usage limits. A provider usage limit is never a task failure. Agents move to the provider’s backup near the limit, and a task cut off by the limit goes back to To-do. If the backup is near its limit too, the run pauses until the earliest reset and then resumes by itself.

Resuming and cleanup

If the daemon restarts mid-run, the swarm reconciles interrupted runs on startup:

• Runs with a valid checkpoint are paused, so you can resume them from where they stopped.
• Runs that can’t resume cleanly (no checkpoint, or their worktrees are gone) are failed.

Startup cleanup only removes the folders of runs that no longer exist. It never removes a stopped or finished run’s worktrees.

Let an agent operate it

One of your agents can run a swarm for you with the swarm_manage tool (and read its state with swarm_status). In its chat, ask it to take over a swarm.

• What it handles on its own: run operations, retries, normal design calls, phase and task gates, routine brainstorm answers, and budget increases of up to 50%.
• What needs your confirmation: the team, the plan, milestones, QA/E2E sign-off, bigger spend, scope changes, restarts, and lowering Involvement. For these, it sends you a question card. The action runs only after you answer approve yourself.
• What wakes it: gates, stops, questions and budget warnings.

Chat commands and scheduled runs

• In chat, /swarm status | list | start <name> | stop | pause | resume | templates manages swarms. At Strict or Balanced, start refuses while brainstorm questions are unanswered, unless you add --anyway.
• A scheduled job with the swarm delivery method starts a run headless (see Schedule a job). Headless runs treat every gate as Full.

Related

• Swarm Project overview: the visual tour, with screenshots of each stage, the run-flow diagram, and the collaboration modes.
• Projects & Tasks: the container a swarm runs inside.
• Project Timeline & Canvas: the plan on a calendar, and the generated design canvas.
• Use Sub-Agents: the building block that workers use.
• Run a Loop: single-agent goal-seeking, the swarm’s simpler cousin.