How to Use

Command Reference & Gameplay Guide

- - - - - - - - - - - - - - - - - - - - -

All Commands

Command	Description
`swarm init`	Initialise Swarm in your project
`swarm setup-ci`	Configure CI triggers for your platform
`swarm process <N>`	Process issue #N through the full pipeline
`swarm review <N>`	Review PR #N through the review pipeline
`swarm worktrees`	Open worktree dashboard in browser
`swarm worktrees list`	Show worktrees as a terminal table
`swarm worktrees clean`	Remove stale worktrees interactively
`swarm help`	Show help message

swarm process

The main event. Takes a GitHub issue number and runs it through the full agent pipeline: scope, dev, review, and rework.

swarm process 42

What Happens

Fetches the issue from GitHub
Labels the issue IN-FLIGHT
Scope agent analyses the codebase and produces a plan
Dev agent creates a worktree, implements the plan, opens a PR
Review agent checks the diff against coding paradigms
If REWORK: rework agent fixes issues, then re-review
On PASS: labels issue FOR-ASSESSMENT, posts summary comment

Options

Flag	Description
`--max-rework N`	Max review/rework cycles (default: 3)
`--dry`	Show what would happen without running agents

Example Output

$ swarm process 13

Swarm Process - Issue #13

Repository: p4u1d34n0/Dromos

Max rework cycles: 3

Fetching issue #13...

Title: UploadedFile uses blocking I/O

Agent: agent-a1b2c3d4

--- Stage 1: Scope ----------------

Running scope agent...

Scope complete.

--- Stage 2: Dev ------------------

Creating worktree...

Running dev agent...

PR #15 created.

--- Stage 3: Review (cycle 1/3) ---

Running review agent...

Verdict: PASS

Issue #13 processed successfully.

PR #15 is ready for assessment.

swarm review

Review an existing pull request without running the full pipeline. Useful for PRs created manually or by other tools.

swarm review 15

Options

Flag	Description
`--max-rework N`	Max rework cycles (default: 3)
`--review-only`	Post review findings without reworking
`--dry`	Preview without running agents

swarm worktrees

Manage the git worktrees that agents create. See what's active, what's stale, and clean up after completed runs.

Dashboard

swarm worktrees

Opens an HTML dashboard in your browser showing all agent worktrees with status, disk usage, PR links, and staleness indicators.

Terminal List

swarm worktrees list

Swarm Worktrees (2 active, 1 stale)

======================================

STATUS AGENT BRANCH

active agent-aeb010 swarm/13-upload...

active agent-f3b291 swarm/7-rate-li...

stale agent-331abc swarm/1-envload...

Cleanup

swarm worktrees clean          # Interactive
swarm worktrees clean --dry    # Preview only
swarm worktrees clean --all    # Remove everything

JSON Output

swarm worktrees list --json    # Pipe to jq, scripts, etc.

Staleness Rules

A worktree is marked stale if any of these are true:

Its branch is merged into main
Its remote branch has been deleted
No commits in 7+ days and no open PR

Status	Meaning
active	Open PR or commits within 3 days
aging	3+ days old, or no PR but recent activity
stale	Meets any staleness criteria above

CI Triggers

In production, you don't run swarm process manually. CI does it for you. When an issue is assigned, labelled, or @mentioned, the CI workflow fires swarm process automatically.

Supported platforms:

GitHub Actions — native event triggers
GitLab CI — webhook relay to pipeline triggers
Bitbucket Pipelines — webhook relay to custom pipelines