Setup

Get your quarters ready

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

Prerequisites

Before you begin, make sure you have these installed:

Tool	Version	Purpose
`bash`	4.0+	Swarm is pure bash
`git`	2.20+	Worktrees, branches, commits
`gh`	2.0+	GitHub CLI for issues, PRs, labels
`claude`	latest	Claude Code CLI for agent execution
`python3`	3.6+	JSON handling and template rendering

Install Claude Code

npm install -g @anthropic-ai/claude-code

Install GitHub CLI

brew install gh
gh auth login

Installation

Step 1: Download & Install

Grab the latest release and run the installer. See the download page for more options.

curl -sL https://swarm.codenexis.com/releases/swarm-v0.1.0.tar.gz | tar xz
cd Swarm
./install.sh

Step 2: Initialise Your Project

Navigate to the project you want Swarm to work on, then run init. This sets up the agent prompts, coding paradigms, and configuration file inside your project.

cd ~/my-project
swarm init

This creates:

.swarm/prompts/ — agent prompt templates
.swarm/paradigms/ — coding standards files
swarm.json — project configuration

$ swarm init

Initializing Swarm...

Repository: your-org/your-project (github)

Created swarm.json

Set up CI triggers? (Y/n):

CI Trigger Setup

CI triggers let Swarm run automatically when issues are assigned or labelled. This is optional for local use but essential for production automation.

swarm setup-ci

The setup wizard will ask you to configure:

Setting	Default	Purpose
Assignee username	`swarm-bot`	Issues assigned to this user trigger Swarm
Trigger label	`swarm`	Issues with this label trigger Swarm
Mention keyword	`@swarm`	Comments containing this trigger Swarm
PR review triggers	Yes	Also trigger review agent on PR events

GitHub Actions

After running setup-ci, you'll need to configure these in your GitHub repository settings:

Repository Variables

Settings > Variables > Actions

SWARM_ASSIGNEE       = swarm-bot
SWARM_TRIGGER_LABEL  = swarm
SWARM_MENTION        = @swarm

Repository Secret

Settings > Secrets > Actions

ANTHROPIC_API_KEY = sk-ant-...

Commit the Workflow

git add .github/workflows/swarm.yml
git commit -m "Add Swarm CI workflow"
git push

Trigger It

Assign an issue to your swarm-bot user or add the swarm label to any issue.

Configuration

swarm.json

The main configuration file. Created by swarm init, updated by swarm setup-ci.

{
  "project": {
    "name": "my-project",
    "repo": "your-org/my-project"
  },
  "agents": {
    "scope":  ".swarm/prompts/scope-agent.md",
    "dev":    ".swarm/prompts/dev-agent.md",
    "review": ".swarm/prompts/review-agent.md",
    "rework": ".swarm/prompts/rework-agent.md"
  },
  "paradigms": [
    ".swarm/paradigms/php-standards.md"
  ],
  "triggers": {
    "platform": "github",
    "assignee": "swarm-bot",
    "label": "swarm",
    "mention": "@swarm",
    "pr_review": true
  }
}

Agent Prompts

Each agent has a markdown prompt file in .swarm/prompts/. These define the agent's role, process, output format, and rules. Customise them to match your workflow.

Coding Paradigms

Files in .swarm/paradigms/ are appended to the system prompt for dev, review, and rework agents. Add one file per language or concern:

.swarm/paradigms/
  php-standards.md
  typescript-standards.md
  security-rules.md

Quick Start

Local Test Run

Try processing an issue locally before setting up CI:

# Preview what would happen
swarm process 42 --dry

# Run it for real
swarm process 42

# Check the worktrees
swarm worktrees list

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

Get Swarm

Game Over? Never.