Swarm

From goal to coordinated work

1. In the composer, choose Swarm in the mode menu, then pick a Swarm preset such as Forge.
2. Describe the goal with concrete acceptance criteria.
3. The orchestrator inspects the project and proposes a plan: tasks, dependencies, and the files each task reads and writes. Review it, then choose Dispatch Swarm.
4. Follow the run in Swarm mission control while the orchestrator supervises the team.

Turn on Auto dispatch next to the mode menu if you want the first plan to start as soon as it validates; it is off by default. Without a preset, turn on Inherit skills & MCPs to give every swarm task the skills and MCP servers enabled in this session; otherwise tasks use the default ones. Supervision runs on the server and continues while every client is closed.

Follow the run

Choose Swarm in the header, or press Ctrl+Alt+W (Cmd+Option+W on a Mac), to open Swarm mission control. The board groups tasks into Running, Waiting, Needs attention, and Done. Search by task, file, or status, open any task's session, and read the Coordination feed for progress, questions, review results, and blockers. Each task also appears in the sidebar under the orchestrator session.

You can write in the orchestrator's chat at any time to steer the run or ask how it is going. A message does not replace the goal. If you ask for work beyond it, the orchestrator carries that work into a follow-up phase.

Good to know · Statuses are observations, not quality scores. Read the final report and the actual changes before you accept the result.

Keep responsibilities clear

Every task declares the files it reads and writes. Two tasks run at the same time only when neither writes files the other reads or writes; otherwise one waits. A folder covers everything inside it, and a task with no write declaration at all reserves the whole project. File locks still apply on top of these scopes.

Your other sessions in the same project take turns with swarm workers. While a worker runs, a prompt you send in another session of that project waits in its queue, and new worker turns wait while your session runs. Ordinary sessions still run side by side with each other.

Workers can ask the orchestrator a question; it shows in the task as Question for the orchestrator. Ask user is not available in swarm task sessions. Scope tasks around concrete files or responsibilities, and give dependent tasks the decisions they need instead of asking each worker to redesign the same interface.

Set limits

Swarm Defaults in Lab → Swarms apply to every swarm run in every project. Leave a field empty to use its default:

• Max total tasks (24): everything a run creates, including planned tasks, live spawns, and repairs. A preset's own Max Tasks overrides it.
• Max follow-up tasks (12): an extra reserve for live spawns and repairs beyond Max total tasks.
• Max chained phases (3): follow-up swarms the orchestrator may start on its own after a verified completion.
• Max turns per task (12): turns a worker may take before the supervisor is asked to check on it. It never cancels the task.

When a run reaches a limit, it pauses with all progress kept. The plan card then offers the next step, such as Raise task limit, Allow one more follow-up round, or Allow another verification cycle. Each reviewer in a preset also has Max Corrections for repair rounds. Provider usage still depends on the models, prompts, and tools you choose.

How a run finishes

A run is complete only after a separate verification checks the current result against the original goal and acceptance criteria. Only a verified completion can start a follow-up phase. If verification fails three times for the same checklist, the run pauses for you.

Good to know · Verifiers and reviewers are agents with tools that are told not to edit. That instruction is not a sandbox, and model judgments still need yours.

Start with Forge

Forge is a built-in, editable preset with an orchestrator and four saved agents: Builder, Integrator, Tester, and Reviewer. A focused change gets one builder and one reviewer. Larger work gets separate builder tasks, each with its own review, plus an integration task when the parts must work together.

When reliability matters, the Tester tries to break the reviewed result with realistic, boundary, invalid-input, and failure cases, fixes the bugs it confirms, and reruns every check. Its work is reviewed too. Forge allows 12 planned tasks plus a six-task follow-up reserve, and two correction rounds per review. These are ceilings, not a target team size.

Configure the orchestrator in Lab → Swarms → Forge and the four agents in Lab → Agents. Use capable models for building and testing and a strong model for review. A duplicated preset still points at the same saved agents, so duplicate the agents too if you want a separately configured team.

Good to know · Forge is a starting point, not a guarantee. Koyd does not publish a success rate for it. Check the result against your own criteria.

Handle interruptions

Read the task's error and the Coordination feed before retrying. Koyd keeps its queues and recovery information on the server, but an interrupted action may already have changed a file or an external system. When a batch of orchestrator actions was interrupted, the run pauses with Review interrupted actions. Inspect what happened, then acknowledge it. The old batch is not retried; only new work runs.

If a run's startup was interrupted partway, review any sessions it created, then use Stop incomplete startup and dispatch a new plan. Terminate plan ends a run.

Swarm or workflow

In a swarm, the orchestrator decides the plan while it runs. In a workflow, you define the steps in advance and they run in the same order every time, for example plan, implement, test, and review. Use a workflow for a process you repeat. See Workflows.