# Swarm

> Swarm is an open-source, local-first multi-agent coding engine and daemon (`swarmd`) built for autonomous development, deterministic task execution, and worktree-isolated multi-agent collaboration.

Swarm operates as a local background daemon (`swarmd`) communicating over private loopback Unix/HTTP sockets (`127.0.0.1:5555`) with interactive terminal (TUI) and desktop clients. It is designed from the ground up for software engineering workloads that require rigorous safety, reproducible tool use, and concurrent multi-agent coordination without risk of workspace corruption.

## Core Architectural Invariants

- **Git Worktree Session Isolation**: Every agent session and execution runs in an isolated 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.
- **Embedded Pebble LSM Key-Value Engine**: Headless `swarmd` embeds CockroachDB's high-performance Pebble KV engine directly in the Go binary. Zero external database dependencies (no PostgreSQL, Redis, or SQLite lock contention). Pebble powers sub-millisecond local state storage, event journals, and session persistence.
- **Deterministic Task Program DAGs**: Multi-stage dependency graphs coordinate specialized agent roles separated by strict integration barriers. Specialized agents include:
  - `auto` / `plan`: Primary orchestration and goal decomposition.
  - `coder`: Autonomous code authoring and test authoring in isolated worktrees (deliberately restricted from raw shell/bash execution to prevent accidental host mutation).
  - `finder`: High-speed, read-only codebase discovery and semantic mapping.
  - `designer`: UI/UX layout and artifact design (HTML, Canvas, SVG, Tailwind).
  - `router`: Task brief hydration and model routing.
  - `compact`: Semantic context-window compaction.
- **Tool Permission Boundaries**: Fine-grained tool governance with explicit human approval gates for filesystem mutation, command execution, and remote cloud infrastructure.

## Documentation Index

### Getting Started & Overview
- [Overview](https://swarmagent.dev/docs): High-level introduction to Swarm, the daemon architecture, and client options.
- [Why Swarm](https://swarmagent.dev/why-swarm): Architectural comparison with single-agent IDE extensions, detailing Git worktree isolation, Pebble KV, and multi-agent coordination.
- [5-Minute Guide](https://swarmagent.dev/docs/5-minute-guide): Accelerated hands-on walkthrough to run your first task in Swarm.
- [Quickstart & Installation](https://swarmagent.dev/docs/quickstart): Installing `swarm` and `swarmd`, connecting clients, and completing local onboarding.
- [Host Your Swarm](https://swarmagent.dev/docs/host-your-swarm): Guidelines for deploying headless `swarmd` on dedicated Linux servers or cloud VMs.

### Multi-Agent Swarming & Task Programs
- [Swarming Effectively](https://swarmagent.dev/docs/swarming): Core concepts for directing concurrent and staged agent swarms.
- [Task Programs](https://swarmagent.dev/docs/swarming/task-programs): Authoring deterministic multi-agent DAGs with sequential stages, dependency barriers, and specialized roles.
- [Iteration Swarms](https://swarmagent.dev/docs/swarming/iteration-swarms): Parallel exploration waves for rapid design alternatives, benchmark trials, and algorithmic options.
- [Artifacts V3](https://swarmagent.dev/docs/swarming/artifacts): Native document, code, and UI artifact creation, revision tracking, and workspace materialization.
- [Images & Visual Media](https://swarmagent.dev/docs/swarming/images): Generative image creation, asset remixing, and multimodal verification.
- [Video Studio & Audio](https://swarmagent.dev/docs/swarming/media): Multi-clip timeline editing, HTML animation conversion, and soundtrack ingestion.

### Runtime, Access & Isolation
- [Agent Profiles & Roles](https://swarmagent.dev/docs/agents): Configuring primary agents and subagents (`auto`, `coder`, `finder`, `designer`, `router`).
- [Environments & Testbenches](https://swarmagent.dev/docs/environments): Ephemeral container and remote testbench leases for autonomous verification.
- [Model Context Protocol (MCP)](https://swarmagent.dev/docs/mcp): Integrating external tool servers, resources, and custom prompts via MCP.
- [Workers & Recurring Automation](https://swarmagent.dev/docs/workers): Worker V2 cron and interval scheduling for recurring codebase reviews and background audits.
- [Permissions & Security](https://swarmagent.dev/docs/permissions): Granular approval policies, execution categories, and critical operation prompts.
- [Swarm Security Architecture](https://swarmagent.dev/docs/swarm-security): Security invariants, secret privacy boundaries, and defense-in-depth isolation.
- [Authentication & Remote Access](https://swarmagent.dev/docs/auth): Private token authentication and loopback broker configuration.

### Workspace & Storage
- [Workspaces](https://swarmagent.dev/docs/workspaces): Multi-workspace cataloging, workspace maps, and root path boundaries.
- [Worktrees](https://swarmagent.dev/docs/worktrees): Git worktree lifecycle management, promotion, lineage recall, and conflict resolution.
- [Memory](https://swarmagent.dev/docs/memory): Account-level durable memory entries, operational rules, and project context.
- [Themes](https://swarmagent.dev/docs/themes): Theme customization and palettes for Desktop and Web interfaces.
- [Configuration Reference](https://swarmagent.dev/docs/configuration): Full specification for `swarm.conf`, CLI flags, and environment variables.

### Catalogs & Resources
- [AI Model Catalog](https://swarmagent.dev/models): Directory of 734+ supported AI models across providers with context limits, pricing, and specs.
- [0-to-1 Dedicated Machine Setup Guide](https://swarmagent.dev/resources/guides/zero-to-one-machine-setup): Complete engineering playbook for provisioning, hardening, and operating a dedicated Linux host for Swarm, embedded Pebble KV storage, cloud IMDS null-routing, and private loopback tunneling.
- [Secure Production AI Agent Setup](https://swarmagent.dev/resources/guides/secure-ai-agent-setup): Practical guide to isolating autonomous AI agents, ambient authority minimization, package supply chain controls, and PR promotion pipelines.
- [Benchmarks & Performance](https://swarmagent.dev/resources/benchmarks): Swarm task routing, planning accuracy, and token economics benchmarks.
- [Full Technical Reference](https://swarmagent.dev/llms-full.txt): Complete, consolidated documentation manual for single-context AI ingestion.