Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

docs: add loop-swarm subsection to QUICKSTART (#424) (#431)

Muhammad Zeshan Malikc56129d60752
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index d02c04b..5ceeb30 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -305,6 +305,19 @@ git apply .loop-sandbox/patches/<patch-id>.patch
>
> **Safety note:** `loop-sandbox` provides worktree isolation, but process execution retains OS-level filesystem and network access — see [docs/safety.md](./safety.md). Always inspect patch files before running `git apply`.
+### Multi-agent consensus sandboxing (`loop-swarm`)
+
+For high-confidence L3 operations, `loop-swarm` ([tools/loop-swarm/README.md](../tools/loop-swarm/README.md)) runs an agent command multiple times sequentially across `N` (default: 3) isolated `loop-sandbox` worktrees. It hashes the resulting `.patch` files and verifies that a majority produced byte-identical changes before writing a consensus patch to `.loop-sandbox/patches/consensus.patch`.
+
+If an agent produces non-deterministic edits, `loop-swarm` acts as a consensus safety net by accepting only changes independently reproduced across runs.
+
+```bash
+# Run multi-agent consensus across 3 sequential sandboxes
+npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>
+```
+
+> **Limitations & Safety:** Runs are serialized sequentially to maintain safety guarantees on the manifest (~N× longer execution), shared stdio, and `SIGINT` signals exit the entire process. `loop-swarm` provides git worktree isolation rather than OS-level container isolation — see [docs/safety.md](./safety.md).
+
## Copy-paste cheat sheet
```bash
@@ -338,6 +351,9 @@ npx @cobusgreyling/loop-worktree cleanup --older-than 24h
# Ephemeral worktree isolation + patch capture
npx @cobusgreyling/loop-sandbox run -- <command>
npx @cobusgreyling/loop-sandbox review
+
+# Multi-agent consensus sandboxing across sequential sandboxes
+npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>
```
## Learn the why (optional, 10 minutes)
diff --git a/docs/safety.md b/docs/safety.md
index 06353dd..bbe5de9 100644
--- a/docs/safety.md
+++ b/docs/safety.md
@@ -106,4 +106,9 @@ For runtime enforcement, define constraints in `loop-constraints.md` at the proj
The `loop-constraints` skill reads this file at the start of every loop run and enforces
every rule. Template: [templates/loop-constraints.md](../templates/loop-constraints.md).
-Tool examples: [Grok](../examples/grok/constraints.md) · [Claude Code](../examples/claude-code/constraints.md) · [Codex](../examples/codex/constraints.md)
\ No newline at end of file
+Tool examples: [Grok](../examples/grok/constraints.md) · [Claude Code](../examples/claude-code/constraints.md) · [Codex](../examples/codex/constraints.md)
+
+## Worktree Isolation & Consensus Sandboxing
+
+- `loop-sandbox`: Ephemeral git worktree isolation for single agent runs. Captures changes as reviewable patch files before applying. See [tools/loop-sandbox/README.md](../tools/loop-sandbox/README.md).
+- `loop-swarm`: Multi-agent consensus sandboxing across sequential `loop-sandbox` runs. Requires byte-identical patch consensus across runs before accepting edits. See [tools/loop-swarm/README.md](../tools/loop-swarm/README.md) and [Quickstart](./QUICKSTART.md#multi-agent-consensus-sandboxing-loop-swarm).
\ No newline at end of file
diff --git a/tools/loop-swarm/README.md b/tools/loop-swarm/README.md
index a213028..ef433f7 100644
--- a/tools/loop-swarm/README.md
+++ b/tools/loop-swarm/README.md
@@ -15,6 +15,8 @@ If an agent produces non-deterministic results, `loop-swarm` acts as an L3 safet
npx @cobusgreyling/loop-swarm run --count 3 -- npx my-agent run --task "Refactor utils.ts"
```
+See [Quickstart](../../docs/QUICKSTART.md#multi-agent-consensus-sandboxing-loop-swarm) for workflow examples and command patterns.
+
## How it works
1. Spawns `N` (default: 3) instances of `loop-sandbox` sequentially (to prevent git worktree and signal handler races).