Skip to content

Swarm (worktree workers)

The swarm subcommand runs several workers in parallel, each in its own git worktree on its own branch. Because every worker gets an isolated checkout, they cannot step on each other’s files. The results come back as JSON.

Dispatch workers

Give the swarm a worker count and a command to run in each worktree:

wayland-core swarm --workers 4 --worker-command "wayland-core --force 'Fix the failing test in this crate'"

The worker command is argv-style: it is split on whitespace, the first token is the program (resolved against PATH), the rest are arguments. There is no shell interpretation, so quoting and pipes are not expanded.

Common flags

wayland-core swarm \
  --workers 4 \
  --worker-command "<cmd>" \
  --repo /path/to/repo \
  --base-branch main \
  --branch-prefix swarm/cli \
  --timeout 5m \
  --task "refactor-pass"

Flag	Meaning	Default
`--workers`	Number of parallel workers (minimum 1)	required
`--worker-command`	argv-style command run in each worktree	required unless `--brief`
`--repo`	Repository root the swarm operates on	current directory
`--base-branch`	Branch each worktree is created from	`main`
`--branch-prefix`	Prefix for each worker’s branch	`swarm/cli`
`--timeout`	Per-worker wall-clock limit (humantime, e.g. `30s`, `5m`)	`1h`
`--task`	Free-form telemetry label	`cli-swarm`

Use a brief file

Instead of individual flags, a TOML brief can describe the whole run. The brief overrides all the individual flags:

task = "refactor-pass"
base_branch = "main"
worker_branch_prefix = "swarm/cli"
worker_command = ["wayland-core", "--force", "Apply the lint fixes"]
timeout = "5m"
env = [["RUST_LOG", "info"]]

wayland-core swarm --workers 4 --brief swarm.toml

What you get back

Each worker runs on its own branch under the prefix you set. When the swarm finishes it prints the collected results as pretty JSON to stdout, then cleans up the worktrees. Review the branches to see what each worker produced.

Next