orchestrating-a-vps-agent-swarm
Skill0 starsChanged 6 months agoMITView on GitHub
Guidance for managing a multi-agent swarm on this template's VPS environment. Use when coordinating multiple autonomous agents (Claude Code, Codex, Gemini) across parallel beads, handling double-claim collisions via Agent Mail, and using beads for global task state. Covers per-agent autonomy toggles (YOLO vs review-gated), multi-model layered review, the human framing gate, and the canonical CLI surface (`bd`, `bv`, `am`, `proj`, `ntm`).
In this repository24 other files it gives its agents.
- AGENTS.mdAGENTS.md
- architectureSkill
- before-after-evidenceSkill
- chrome-devtools-deepSkill
- ci-optimizationSkill
- configurationSkill
- continuous-deliverySkill
- dependenciesSkill
- developer-experienceSkill
- documentationSkill
- drySkill
- environmentsSkill
- error-handlingSkill
- loggingSkill
- observability-queriesSkill
- playwright-debugSkill
- principles-and-patternsSkill
- purpose-and-scopeSkill
- running-experimentsSkill
- securitySkill
- software-complexitySkill
- testingSkill
- typesSkill
- versioningSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 57
Lesson: If an agent is solving the wrong problem perfectly, the human must correct the frame before the next execution wave begins.
- Distinctive: line 70
Pattern: Every significant Agent Mail finding should point to a bead ID.
- Very specific: line 136
When bv --robot-next hands you a bead another agent has already claimed (visible in Agent Mail threads):
- Very specific: line 141
Look up active Agent Mail threads referencing the bead ID: am status --agent <NAME> then am thread <ID> on any relevant subject lines.
- Very specific: line 144
If the other agent has substantive work in the tree, stand down.
- Distinctive: line 149
If the other agent appears wedged (no Agent Mail activity, no recent file edits), surface that to the human framing gate via an Agent Mail …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Orchestrating a VPS agent swarm
Overview
A VPS agent swarm is multiple specialized models running in shared or isolated workspaces on the same VPS. Success depends on: clear framing, asynchronous coordination via Agent Mail and beads, and a layered review stack across models with different defect lenses.
This template's VPS layout is documented in ~/CLAUDE.md. The phase
model (ideation, task breakdown, swarm implementation, review, deploy)
is at https://agent-flywheel.com/workflow. This skill covers phase 3
(swarm implementation) in operational detail.
Core lessons and patterns
1. Per-agent autonomy toggles (the YOLO switch)
Autonomy is a scheduling resource, not a binary state.
- YOLO mode. Speed and execution on low-risk tasks (scaffolding,
bulk refactors, doc edits). Launch with the host CLI's bypass flag:
Claude Code
--permission-mode bypassPermissions, Codex--dangerously-bypass-approvals, Gemini--yolo. - Review-gated mode. High-stakes architectural choices where each tool call should be audited. Drop the bypass flag; let prompts interrupt.
- Rule. Launch each agent with the autonomy level tailored to its bead, not a session default.
2. Multi-model layered review
Different models catch different defect classes.
- Author (Claude). High-level reasoning, complex spec generation, multi-file refactors.
- Skeptical reviewer (Codex). Implementation consistency, boundary-condition checks, line-level correctness.
- Consistency reviewer (Gemini). Cross-specification alignment, architectural split-brain detection, doc drift.
- Outcome. A "passed" feature from one model should be cross-verified by another with a different lens before close.
3. The human framing gate
Models are excellent at local correctness but weaker at strategic pivots.
- Pattern. Human intervention is most valuable at the beginning (framing the product, choosing the bead set) and middle (re-scoping based on research findings or an unexpected adversarial finding).
- Lesson. If an agent is solving the wrong problem perfectly, the human must correct the frame before the next execution wave begins. The swarm cannot rescope itself.
4. Coordination: beads + Agent Mail
Structured state plus asynchronous communication.
- beads. The global DAG. Provides stable IDs for claims,
completions, and dependencies. The
.beads/directory is committed to the project repo. - Agent Mail. The rationale bus. Carries handoffs, merge negotiations, reservation announcements, and review findings.
- Pattern. Every significant Agent Mail finding should point to a bead ID. Every bead claim should be preceded by an Agent Mail broadcast on the relevant thread when the work touches files multiple beads care about.
CLI surface (the template's actual tools)
# beads (per-project tracker; cwd-scoped)
bd create "..." -t task -d "..." # new bead
bd update <id> --claim # claim (atomic)
bd close <id> --reason "..." # finalize (terminal-state)
bv # interactive TUI
bv --robot-next # pick next ready bead (JSON)
bv --robot-triage # full recommendation set
# Agent Mail (cross-agent comms)
am macros start-session ... # register an agent identity
am status --agent <NAME> # inbox + reservation overview
am file_reservations reserve <PROJECT> <AGENT> <PATHS>...
am mail send --from <AGENT> --to <AGENT> --subject ... --body ...
am thread <ID> # read a coordination thread
# Project navigation (numbered)
proj # list projects under /data/projects/
proj spawn <N> --cc=<K> # ntm spawn an agent swarm at project N
proj attach <N> # re-attach
proj path <N> # absolute path of project N
ntm spawn <org>--<repo> --cc=<N> # raw ntm form
# Sessions
systemctl --user status agent-mail # the mail service is requiredOperational checklist
- Pre-trust environments. Folder trust and MCP server
permissions must be granted before dispatching. Re-running
claude loginon the VPS is a known anti-pattern; ACFSservices-setupfrom the operator's Mac is the only path. - Register the agent. Run
am macros start-session --project <abs path> --program <cli> --model <id>on every fresh turn. Without an identity,am statuscannot inspect inbox or reservations. - Claim before you edit.
bd update <id> --claimis the authoritative claim. Two agents that both claim are a coordination bug; one of them must stand down via Agent Mail. - Reserve shared files. When a bead touches a file another
bead also touches (e.g.,
justfile,lefthook.yml,.github/workflows/*),am file_reservations reserveit before editing. Skipped reservations cause edit races; recovery costs more than the reservation. - Exact file ownership. Every bead's description should call
out a specific canonical file path. Name placeholders
(
<filename>) cause collisions. - Wedge detection. Watch for "busy" agents that have not
touched the filesystem or Agent Mail in N minutes. Use
am status --agent <NAME>to confirm a quiet agent is actually idle, not stuck. - Whole-template QA. After individual feature beads close,
run
just bootstrap && just test && just lintagainst a fresh clone (or a worktree) before declaring the swarm output green. Per-bead green does not imply assembled green.
Standard collision-recovery flow
When bv --robot-next hands you a bead another agent has already
claimed (visible in Agent Mail threads):
- Re-read the bead state:
bd show <id>. The status field is the shared source of truth. - Look up active Agent Mail threads referencing the bead ID:
am status --agent <NAME>thenam thread <ID>on any relevant subject lines. - If the other agent has substantive work in the tree, stand
down. Send an Agent Mail reply on the existing thread (or a fresh
one with a
bd-<id>-coordstyle alphanumeric thread-id) naming the files you edited and confirming you will not commit. Thenbv --robot-nextfor a fresh bead. - If the other agent appears wedged (no Agent Mail activity, no recent file edits), surface that to the human framing gate via an Agent Mail message rather than unilaterally taking the bead. The wedge is the framing-gate event, not the failed claim.
Anti-patterns
- Silent double-claim. Two agents both run
bd update <id> --claimwithout checking Agent Mail.--claimis atomic and idempotent for the same agent, but it does not stop a second agent from taking a bead the first is already working: the claim is not exclusive at the beads layer. Recovery: stand down via Agent Mail. - Unilateral retirement. Removing or deprecating shared infrastructure (a hook, a sensor adapter, an ADR) without an Agent Mail broadcast first. The operator's preservation rule applies; see ADR-0017's "both-vs-reduce" framing.
- Per-bead green declared as swarm green. Each bead's gate is per-file or per-slot. A swarm landing requires whole-template verification (see Operational checklist).
- Mail without a bead ID. Coordination messages that name files but not beads decay into untrackable rationale. Cross-link every thread to at least one bead.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

