# Swarm: Complete Technical Reference Manual & Architectural Specification

> The authoritative, monolithic technical documentation and architectural reference for Swarm, an open-source, local-first multi-agent coding engine and daemon (`swarmd`).
> Designed for complete context-window ingestion by AI models, LLM crawlers, Claude Projects, Cursor rules, and developer tooling.
> Canonical URL: https://swarmagent.dev/llms-full.txt
> Specification Standard: llmstxt.org

---

## Table of Contents

1. [Executive Overview & System Architecture](#1-executive-overview--system-architecture)
2. [Core Invariants & Security Boundaries](#2-core-invariants--security-boundaries)
3. [Daemon Architecture (`swarmd`) & Pebble KV Storage](#3-daemon-architecture-swarmd--pebble-kv-storage)
4. [CLI Command Reference (`swarm`, `swarmd`, `swarmctl`)](#4-cli-command-reference-swarm-swarmd-swarmctl)
5. [Interactive Terminal UI (TUI) & Slash Commands](#5-interactive-terminal-ui-tui--slash-commands)
6. [System Agent Roles & Least-Privilege Model](#6-system-agent-roles--least-privilege-model)
7. [Deterministic Task Program DAGs & Iteration Swarms](#7-deterministic-task-program-dags--iteration-swarms)
8. [Workspaces & Git Worktree Isolation Lifecycle](#8-workspaces--git-worktree-isolation-lifecycle)
9. [Environments, Leases & Remote Testbenches](#9-environments-leases--remote-testbenches)
10. [Account Memory & Operational Preferences](#10-account-memory--operational-preferences)
11. [Configuration Reference (`swarm.conf`)](#11-configuration-reference-swarmconf)
12. [Five-Minute Onboarding & Quickstart Guide](#12-five-minute-onboarding--quickstart-guide)
13. [Complete Documentation Index](#13-complete-documentation-index)

---

## 1. Executive Overview & System Architecture

Swarm is an autonomous, local-first multi-agent coding engine designed for complex, production-grade software engineering. Unlike single-agent IDE extensions or unstructured ReAct agent loops that mutate a developer's primary checkout directly, Swarm separates orchestration, execution, and verification into isolated processes bound by strict dependency barriers.

### Architectural Diagram

```
┌────────────────────────────────────────────────────────────────────────┐
│                        User Interfaces (Clients)                       │
│                                                                        │
│   Terminal UI (TUI)             Desktop App (Web / Electron)           │
│   `swarm`                       Interactive Artifacts, Video Studio    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                         Loopback HTTP / WebSocket
                         (127.0.0.1:5555 / 127.0.0.1:5556)
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                      Headless Daemon (`swarmd`)                        │
│                                                                        │
│  ┌─────────────────────────┐        ┌───────────────────────────────┐  │
│  │   Orchestration Engine  │        │       Embedded Pebble KV      │  │
│  │   Plan & Auto Modes     │        │       (CockroachDB LSM)       │  │
│  │   DAG Task Programs     │        │  Sessions, Plans, Memory, WAL │  │
│  └────────────┬────────────┘        └───────────────┬───────────────┘  │
│               │                                     │                  │
│               ▼                                     ▼                  │
│  ┌─────────────────────────┐        ┌───────────────────────────────┐  │
│  │   Subagent Delegation   │        │     Git Worktree Manager      │  │
│  │   Coder, Finder,        │◄───────┤     Isolated per-session      │  │
│  │   Designer, Router      │        │     ephemeral worktrees       │  │
│  └─────────────────────────┘        └───────────────────────────────┘  │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                      Execution & Test Runtime                          │
│                                                                        │
│   Isolated Worktree Checkouts      Unified Test Environments           │
│   (.swarm/worktrees/<session-id>)  (Docker Containers, Remote SSH)     │
└────────────────────────────────────────────────────────────────────────┘
```

### Architectural Tiers:
- **Headless Daemon (`swarmd`)**: Written in Go. Owns all agent state, session journals, tool execution, process lifecycle, Git worktrees, and provider API communication. Binds to `127.0.0.1:5555` over private HTTP/WebSocket APIs.
- **Terminal UI (`swarm`)**: An interactive terminal client providing real-time streaming agent transcripts, tool approval prompts, plan inspection, and slash commands.
- **Desktop Application (Web/Electron)**: Provides visual session navigation, Artifact V3 rendering (documents, HTML/CSS/Canvas UI prototypes), Video Studio, and workspace management.

---

## 2. Core Invariants & Security Boundaries

Swarm enforces five non-negotiable architectural invariants:

1. **Git Worktree Isolation**: Every coding agent session runs in its own dedicated Git worktree branch (`.swarm/worktrees/<session-id>/<worktree-name>`). Sibling agents never race against each other, overwrite shared files, or contaminate the host checkout during compilation or testing.
2. **Zero External Database Dependency**: `swarmd` embeds CockroachDB's Pebble LSM key-value engine directly into the Go binary. No PostgreSQL, Redis, or SQLite database is required to run headless or local daemons.
3. **Deterministic DAG Task Programs**: Multi-agent delegation uses typed, validated directed acyclic graphs (DAGs) separated by strict integration barriers.
4. **Least-Privilege System Agents**: Specialized subagents start with less authority than the primary orchestrator. `Coder` subagents author code and tests in isolated worktrees but cannot execute raw shell/bash commands; `Finder` is strictly read-only; `Designer` cannot run Git or Bash.
5. **Human Approval Gates**: Consequential actions (file mutations outside worktrees, cloud infrastructure changes, external network calls, destructive commands) halt for explicit user approval unless bypass is configured.

### Tool Impact Categories:
Every tool execution declares an effect category enforced by the permission engine:
- `read`: Observes state without side-effects (e.g., file reads, search, directory listings, status checks). Auto-approved under normal operation.
- `write`: Creates new files, allocations, or starts processes. Requires user approval unless permission bypass is active.
- `update`: In-place modifications to existing files or configurations without removal.
- `delete`: Removes state, kills processes, or truncates files. **Always critical**; unconditionally requires explicit approval.

---

## 3. Daemon Architecture (`swarmd`) & Pebble KV Storage

The Swarm daemon (`swarmd`) is the single source of truth for all runtime state, executing autonomously on the developer's workstation or a dedicated server.

### Embedded Pebble LSM Engine
Instead of requiring external databases like PostgreSQL or Redis, `swarmd` embeds CockroachDB's Pebble key-value store directly:
- **Sub-millisecond latency**: Direct in-memory LSM-tree lookups with memory-mapped SSTables on local NVMe/SSD storage.
- **Crash Resilience**: Full Write-Ahead Logging (WAL) ensures atomic commits and zero data corruption across abrupt reboots or process termination.
- **Zero Configuration**: Compiles statically into the Go binary; requires zero external network ports or background services.

### Pebble Key Namespaces:
- `sessions/`: Session journal logs, attempt metadata, and event histories.
- `plans/`: Authoritative structured `SessionPlanDocument` records, execution graphs, and checkpoint statuses.
- `workspaces/`: Workspace catalog definitions, allowed roots, and linked directory boundaries.
- `memory/`: Durable account-level memory records, rules, and operational guidelines.
- `environments/`: Container and SSH test environment configurations, leases, and receipts.
- `agent-settings/`: Model configurations, reasoning/thinking levels, and per-role provider mappings.

---

## 4. CLI Command Reference (`swarm`, `swarmd`, `swarmctl`)

### `swarm` (Primary Launcher & CLI)
The `swarm` binary is the primary entrypoint for developers.

```bash
# Launch interactive Terminal UI (TUI) in current directory
swarm

# Launch TUI on the development lane
swarm dev

# Launch Swarm Desktop application
swarm open
# or
swarm --desktop

# Start daemon as a system background service
swarm start

# Stop the background daemon service
swarm stop

# Restart the daemon service
swarm restart

# Inspect daemon health, listen address, and active sessions
swarm status

# Print lane, listen address, data directory, and port file information
swarm info

# Set active model via CLI
swarm ctl model set --provider google --model gemini-3.8-flash

# Run a prompt in a session via CLI
swarm session run --id <session-id> --prompt "Audit this codebase for race conditions"

# Install daemon service and system launchers
swarm install [--service] [--yes]

# Uninstall daemon service and clean system state
swarm uninstall [--purge] [--yes]

# Update Swarm binaries to latest release
swarm update apply
# or update dev lane from local source
swarm update dev
```

### `swarmd` (Daemon Process Flags)
Direct execution flags for running the daemon headless:

```bash
swarmd [flags]
```

- `-listen <host:port>`: HTTP and WebSocket listen address (default: `127.0.0.1:5555`). Loopback binding is enforced for local security.
- `-desktop-port <port>`: Port for Desktop web assets (default: `5556`, `0` disables desktop listener).
- `-bypass-permissions`: Bypass normal tool permission prompts (note: `exit_plan_mode` still requires approval).
- `-data-dir <path>`: Root directory for runtime state (default: `~/.local/share/swarm` or `/var/lib/swarmd`).
- `-db-path <path>`: Explicit path to Pebble database files.
- `-lock-path <path>`: Path to daemon process lock file.
- `-cwd <path>`: Default working directory binding for workspace operations.

### `swarmctl` (Administrative Daemon Control)
Direct Unix socket or loopback control utility for headless automation and scripting:

```bash
swarmctl health
swarmctl model get
swarmctl model set --provider google --model gemini-3.8-flash
swarmctl session list
swarmctl workspace resolve
```

---

## 5. Interactive Terminal UI (TUI) & Slash Commands

When running `swarm`, an interactive Bubble Tea terminal user interface opens. Operators can type prompts or invoke slash commands:

### Slash Commands:
- `/models`: Interactive model selector. Search and switch between verified models from Google, Anthropic, OpenAI/Codex, and Fireworks.
- `/agent`: Switch active agent profile (`auto`, `plan`, `coder`, `finder`, `designer`).
- `/workspace`: Inspect or link workspace root directories.
- `/worktrees`: View active Git worktrees, inspect diffs, or prune stale session checkouts.
- `/permissions`: Review active permission levels, toggle bypass, or view recent audit log.
- `/theme`: Open interactive theme selector for TUI styling.
- `/compact`: Trigger semantic context-window compaction to free up tokens while preserving plan state.
- `/clear`: Clear terminal viewport scrollback.
- `/exit`: Exit the terminal client (daemon continues running in background).

---

## 6. System Agent Roles & Least-Privilege Model

Swarm rejects the "one unconstrained agent does everything" model. Subagents operate with pre-compiled, code-owned privileges:

| Agent Profile | Execution Mode | Permitted Tool Surface | Prohibited Tools & Safety Constraints |
| :--- | :--- | :--- | :--- |
| **`auto` / `plan`** | Orchestrator | Full workspace tools (`read`, `write`, `edit`), `plan_manage`, `task`, `bash`. | Cannot bypass user approval gates without configured flags; delegates heavy work. |
| **`coder`** | Subagent (Worktree) | File read, write, edit, Git commit, Git status, search, find. | **Cannot use Bash or shell execution**; strictly worktree-bound; cannot touch primary checkout. |
| **`finder`** | Subagent (Read-Only) | `search` (FFF content/symbol), `find` (paths), `list`, `read`. | **Strictly read-only**; cannot write, edit files, or execute shell commands. |
| **`designer`** | Subagent (Artifacts) | `manage_artifact` (Artifact V3), `read`, `search`. | **Cannot use Bash or Git**; produces native visual artifacts (HTML/CSS/Canvas). |
| **`router`** | Pipeline Engine | Prompt hydration, schema parsing. | No filesystem or command execution capabilities. |
| **`compact`** | Memory Engine | Context-window semantic compaction. | Read-only context inspection; no mutation tools. |

### Why Coder Has No Bash Access:
By deliberate architectural design, Coder agents cannot run shell commands. They author code, write comprehensive unit tests, and commit them to their isolated worktree. The parent orchestrator reviews the committed diff and executes the test runner in an authorized environment. This eliminates unvetted command execution and accidental machine compromise.

---

## 7. Deterministic Task Program DAGs & Iteration Swarms

Swarm supports two distinct multi-agent execution paradigms:

### 1. Deterministic Task Programs (Structured DAGs)
For multi-subsystem engineering tasks, the parent orchestrator compiles a typed DAG where jobs run across stages separated by integration barriers:

```json
{
  "action": "start",
  "prompt": "Implement user authentication subsystem",
  "program": {
    "id": "auth-pipeline",
    "stages": [
      {
        "id": "discovery",
        "dependency_evidence": "Inspect existing token models and routes"
      },
      {
        "id": "implementation",
        "depends_on": ["discovery"],
        "dependency_evidence": "Discovery audit complete and schemas defined"
      }
    ],
    "jobs": [
      {
        "id": "audit-routes",
        "stage_id": "discovery",
        "agent_type": "finder",
        "title": "Audit Auth Routes",
        "meta_prompt": "Locate and document all unauthenticated endpoints in pkg/api",
        "deliverable": "Endpoint audit report",
        "acceptance_criteria": ["All endpoints mapped"]
      },
      {
        "id": "impl-tokens",
        "stage_id": "implementation",
        "depends_on": ["audit-routes"],
        "agent_type": "coder",
        "title": "Implement JWT Validator",
        "meta_prompt": "Implement token validation with unit tests",
        "owned_scope": ["pkg/auth/**"],
        "deliverable": "Committed token validator and unit tests",
        "acceptance_criteria": ["JWT validator unit tests pass"]
      }
    ]
  }
}
```

- **Integration Barrier**: Stage 2 never executes until all jobs in Stage 1 pass parent review and their deliverables are accepted.
- **Scope Isolation**: Concurrent Coders in the same stage must declare non-overlapping `owned_scope` paths to prevent merge collisions.

### 2. Iteration Swarms (Parallel Exploration)
For exploring design variations or algorithmic alternatives:
- Supports `image` swarms, `video` swarms, `designer` managed UI swarms, `coder` trial swarms, and `idea` swarms.
- Orchestrator provides a shared brief, count (1–50), and iteration controls:
  - `change`: The dimensions to vary across workers.
  - `preserve`: Core invariants every worker must retain.
  - `exclude`: Anti-patterns every worker must avoid.

---

## 8. Workspaces & Git Worktree Isolation Lifecycle

### Worktree Lifecycle:
1. **Admission & Worktree Creation**:
   When an agent session starts, Swarm creates an isolated Git worktree:
   ```bash
   git worktree add -b agent/<session-id> .swarm/worktrees/<session-id>/task-branch HEAD
   ```
2. **Autonomous Execution**:
   The agent reads, writes, and commits code inside its isolated directory. The developer's primary working tree remains completely untouched.
3. **Parent Verification**:
   The parent agent reviews the committed branch diff and runs test suites inside the worktree checkout.
4. **Promotion & Integration**:
   Once verified, the worktree branch is merged cleanly into the project's target branch (`main` or `dev`) using:
   ```json
   {"action": "promote", "source_session_id": "<session-id>", "target_branch": "dev"}
   ```
5. **Teardown**:
   The temporary worktree is pruned and disk space is reclaimed.

---

## 9. Environments, Leases & Remote Testbenches

Swarm provides a unified environment management system (`manage_environments`) for containerized or remote testing:

### Core Concepts:
- **Environment Definitions**: JSON specifications declaring Docker container images, resource limits, and health checks.
- **Deployments & Leases**: Leases are acquired with finite time-to-live (`ttl_millis`) and an explicit idempotency key. When a lease expires, resources are automatically destroyed.
- **Command Execution (`exec`)**: Commands execute non-blockingly, returning operation receipts. Output stdout/stderr is strictly capped to prevent buffer exhaustion.
- **Host Connections**: Managed via `manage_connections` supporting local Docker sockets and SSH remote hosts.

---

## 10. Account Memory & Operational Preferences

The `manage_memory` system stores persistent, cross-session guidelines in Pebble KV without storing credentials:

### Memory Entry Kinds:
- `rule`: Hard behavioral constraints authored by the developer (e.g. "Always run tests in Docker", "Commit directly to dev branch in feature work").
- `operational_context`: Facts about project architecture, testbench locations, or service account names.
- `preference`: Developer coding preferences (e.g. "Prefer TypeScript strict mode", "Use Tailwind CSS v4").
- `learned`: Operational procedures derived by the agent during past successful troubleshooting runs.

> ⚠️ **Strict Privacy Rule**: Memory stores credential locations and references only. Secret values, API keys, or raw tokens are never written to memory.

---

## 11. Configuration Reference (`swarm.conf`)

Configuration is loaded from `/etc/swarmd/swarm.conf` (system-wide) or `~/.config/swarm/swarm.conf` (user-specific):

```ini
# Network Binding
host = "127.0.0.1"
port = 5555
desktop_port = 5556

# Storage & Paths
data_dir = "~/.local/share/swarm"
worktree_dir = "~/.local/share/swarm/worktrees"

# Security & Safety Policies
bypass_permissions = false
retain_tool_output_history = true
long_session_diagnostics = false

# Default Model Provider Preferences
default_provider = "google"
default_model = "gemini-3.8-flash"
default_thinking = "low"
```

---

## 12. Five-Minute Onboarding & Quickstart Guide

### Step 1: Install Swarm
```bash
curl -fsSL https://swarmagent.dev/install | bash
```
The installer downloads the verified binary, initializes the local Pebble KV store, and configures the `swarm` command.

### Step 2: Configure Your Model Provider
Add your model provider API key to your environment:
```bash
export GEMINI_API_KEY="your-api-key"
# or export ANTHROPIC_API_KEY="..."
# or export OPENAI_API_KEY="..."
```

### Step 3: Launch Your First Coding Session
Navigate to any Git repository and run:
```bash
cd ~/my-project
swarm
```
Type a prompt:
```text
Refactor pkg/api to use structured logging with slog and add unit tests.
```
Swarm will create an isolated Git worktree, execute the plan, run tests, and propose a clean commit for promotion into your active branch.

---

## 13. Complete Documentation Index

For exhaustive, page-by-page technical guides, visit the canonical online documentation:

- [https://swarmagent.dev/docs/quickstart](https://swarmagent.dev/docs/quickstart) — 5-minute setup and provider key configuration
- [https://swarmagent.dev/docs/why-swarm](https://swarmagent.dev/docs/why-swarm) — In-depth architectural comparison with traditional agent loops
- [https://swarmagent.dev/docs/agents](https://swarmagent.dev/docs/agents) — Full specification of `auto`, `plan`, `coder`, `finder`, and `designer` roles
- [https://swarmagent.dev/docs/worktrees](https://swarmagent.dev/docs/worktrees) — Git worktree isolation mechanics, race-condition elimination, and branch promotion
- [https://swarmagent.dev/docs/workspaces](https://swarmagent.dev/docs/workspaces) — Workspace mapping, multi-repository boundary configuration, and path controls
- [https://swarmagent.dev/docs/environments](https://swarmagent.dev/docs/environments) — Isolated test containers, Docker/SSH execution, and TTL-based lease management
- [https://swarmagent.dev/docs/memory](https://swarmagent.dev/docs/memory) — Persistent account memory, operational context, rules, and privacy boundaries
- [https://swarmagent.dev/docs/workers](https://swarmagent.dev/docs/workers) — Worker V2 recurring automations, cron schedules, and background worker plans
- [https://swarmagent.dev/docs/permissions](https://swarmagent.dev/docs/permissions) — Effect categories (`read`, `write`, `update`, `delete`), approval gates, and safety checks
- [https://swarmagent.dev/docs/swarm-security](https://swarmagent.dev/docs/swarm-security) — Security model, private loopback binding, and least-privilege constraints
- [https://swarmagent.dev/docs/configuration](https://swarmagent.dev/docs/configuration) — Complete `swarm.conf` schema, environment variables, and startup options
- [https://swarmagent.dev/docs/mcp](https://swarmagent.dev/docs/mcp) — Model Context Protocol server configuration and tool integration
- [https://swarmagent.dev/docs/themes](https://swarmagent.dev/docs/themes) — Built-in and custom theme authoring for Terminal UI and Desktop
- [https://swarmagent.dev/docs/auth](https://swarmagent.dev/docs/auth) — Private socket token authentication and loopback verification
- [https://swarmagent.dev/docs/host-your-swarm](https://swarmagent.dev/docs/host-your-swarm) — Self-hosting guide for dedicated servers and headless cloud environments
- [https://swarmagent.dev/docs/swarming/task-programs](https://swarmagent.dev/docs/swarming/task-programs) — Deterministic multi-agent DAGs and dependency barriers
- [https://swarmagent.dev/docs/swarming/iteration-swarms](https://swarmagent.dev/docs/swarming/iteration-swarms) — Parallel exploration swarms for code, design, and ideas
- [https://swarmagent.dev/docs/swarming/artifacts](https://swarmagent.dev/docs/swarming/artifacts) — Artifact V3 document authoring and UI prototypes
- [https://swarmagent.dev/docs/swarming/media](https://swarmagent.dev/docs/swarming/media) — Video Studio timeline composition, soundtrack ingestion, and media rendering
- [https://swarmagent.dev/resources/guides/zero-to-one-machine-setup](https://swarmagent.dev/resources/guides/zero-to-one-machine-setup) — 0-to-1 dedicated machine setup: bare-metal/VM sizing, OS hardening, Pebble KV, and loopback SSH tunneling
- [https://swarmagent.dev/resources/guides/secure-ai-agent-setup](https://swarmagent.dev/resources/guides/secure-ai-agent-setup) — Production security playbook: ambient credentials, package manager supply chain, and PR gates
- [https://swarmagent.dev/resources/benchmarks](https://swarmagent.dev/resources/benchmarks) — Agent routing, cold-start latency, and task completion benchmarks