Agent Swarm: A Revolutionary Multi-Agent Orchestration Platform for AI Coding Assistants

Introduction to Agent Swarm

Agent Swarm is a cutting-edge multi-agent orchestration system designed to streamline workflows for AI-powered coding assistants, including Claude Code, Codex (GitHub Copilot), Gemini CLI, and other advanced AI tools. Developed by desplega.sh, this platform empowers developers with an autonomous team of AI agents that collaborate seamlessly to complete complex tasks efficiently. The core philosophy behind Agent Swarm is to eliminate manual intervention while enabling agents to learn, adapt, and improve over time through a sophisticated memory system.

The project’s visual identity includes a GitHub Stars badge (indicating active community engagement), an MIT License (ensuring open-source flexibility), and a Discord server for real-time collaboration. The platform is structured around lead agents that delegate tasks to worker agents, each running in isolated Docker containers with full development environments.

Core Architecture and Key Features

1. Lead-Agent Worker Model

Agent Swarm operates on a distributed agent framework where:

Lead Agent: Acts as the task orchestrator, breaking down complex tasks into smaller subtasks and assigning them to worker agents.
Worker Agents: Execute assigned tasks in isolated Docker containers, ensuring no interference between different projects or environments.

The architecture is depicted visually through a flow diagram showing how tasks are initiated from external sources (Slack, GitHub, email) and processed through the API server before being delegated to workers. The system ensures real-time progress tracking via a dashboard UI and integrates with multiple platforms for seamless task management.

(The provided image in the input shows an abstract representation of this workflow.)

2. Docker Isolation

Each worker agent runs in a dedicated container with:

A full development environment (Node.js, Python, Git, etc.).
Persistent storage for task-specific directories.
Customizable startup scripts to install additional tools or configure environments.

This isolation ensures that agents do not conflict with each other’s workspaces, maintaining clean and efficient execution.

3. Task Integration & Automation

Agent Swarm supports multiple integration channels:

Slack: Users can send tasks via direct messages (DMs) or mentions in threads.
GitHub/GitLab: The platform detects @mentions in issues, pull requests (PRs), and merge requests (MRs), automatically creating tasks for agents to address.
Email: Agents receive emails as tasks, allowing asynchronous workflows.
Scheduled Tasks: Cron-based automation enables recurring tasks without manual intervention.

4. Memory System & Learning

One of Agent Swarm’s most innovative features is its compounding memory system, which allows AI agents to learn from past experiences:

Session Summaries: At the end of each task, a lightweight model extracts key insights (mistakes made, patterns discovered) and stores them in searchable databases.
Task Completions & Failures: Both successful and failed tasks are indexed, ensuring that agents avoid repeating errors.
File-Based Notes: Agents write to /workspace/personal/memory/ directories, which are automatically indexed for future reference.
Lead-to-Worker Learning Injection: The lead agent can manually inject specific learnings into worker agents, closing the feedback loop.

This system ensures that agents evolve over time, becoming more efficient and accurate with each task.

5. Persistent Agent Identity

Each AI agent maintains a unique identity across sessions through four configuration files: | File | Purpose | |---------------|---------------------------------------------------------------------------------------------| | SOUL.md | Core personality, behavioral directives (e.g., "Be thorough and own mistakes"). | | IDENTITY.md | Expertise, working style, and track record (e.g., "I ship fast and clean code"). | | TOOLS.md | Environment knowledge (repositories, APIs, tools). | | CLAUDE.md | Persistent notes, preferences, and instructions. |

Agents can edit these files during sessions, and changes are synced to the database in real-time. This ensures that each agent’s behavior remains consistent and evolves based on its experiences.

6. Startup Scripts & Environment Customization

Each worker agent runs a customizable start-up.sh script at container startup:

Agents can install additional tools (e.g., ripgrep, prettier).
Configure environment variables or workflows.
Persistent changes ensure that once installed, tools remain available across sessions.

7. Dashboard UI & Monitoring

A React-based dashboard provides real-time visibility into the agent swarm:

Monitor task progress, agent statuses, and inter-agent communication.
Access interactive documentation via OpenAPI 3.1 specs.
Supports live updates for Slack threads, GitHub issues, and API logs.

The dashboard is accessible at http://localhost:5173 after running the UI setup commands.

Deployment & Setup

Prerequisites

Before deploying Agent Swarm, users must have:

Docker installed.
A Claude Code OAuth token (for AI agent authentication).

Option 1: Docker Compose Deployment (Recommended)

The fastest way to deploy a full swarm is using Docker Compose:

git clone https://github.com/desplega-ai/agent-swarm.git
cd agent-swarm

# Copy environment template and configure
cp .env.docker.example .env
# Edit `.env` to set `API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`

# Start the API server, lead agent, and 2 workers
docker compose -f docker-compose.example.yml --env-file .env up -d

The API runs on port 3013.
The dashboard is available separately (see below).
Interactive documentation is accessible at http://localhost:3013/docs.

Option 2: Local API + Docker Workers

For more control, users can run the API server locally and connect Docker workers:

git clone https://github.com/desplega-ai/agent-swarm.git
cd agent-swarm

# Install dependencies
bun install

# Start the API server
cp .env.example .env
# Edit `.env` to set `API_KEY`
bun run start:http

In a new terminal, start a worker:

cp .env.docker.example .env.docker
# Edit `.env.docker` to set `API_KEY` and `CLAUDE_CODE_OAUTH_TOKEN`
mkdir -p ./logs ./work/shared ./work/worker-1
bun run docker:build:worker
bun run docker:run:worker

Option 3: Claude Code as Lead Agent

For users who prefer not to use Docker for the lead agent:

# After starting the API server (Option B, step 1)
bunx @desplega.ai/agent-swarm setup

This configures Claude Code to connect to the swarm. Users must then register themselves as the lead agent in Agent Swarm.

How It Works: Task Execution Flow

The workflow of Agent Swarm can be broken down into six key steps:

Task Initiation: A user sends a task via Slack, GitHub, email, or API.
Lead Agent Planning: The lead agent analyzes the task and breaks it into subtasks.
Worker Assignment: Subtasks are delegated to worker agents running in Docker containers.
Execution & Progress Tracking: Workers execute tasks while reporting progress via the dashboard or Slack threads.
Result Delivery: Agents deliver results (e.g., PRs, issue updates, Slack replies).
Learning & Improvement: Every session’s insights are stored for future reference.

(The input image visually represents this flow.)

Advanced Features

Hook System

Agent Swarm includes a hook system that fires during each Claude Code session, ensuring safety and context management: | Hook | Trigger | Purpose | |---------------|-----------------------------|------------------------------------------------------------------------| | SessionStart | Session begins | Loads identity files from the database. | | PreCompact | Before context compaction | Injects a "goal reminder" to prevent task loss of focus. | | PreToolUse | Before each tool call | Checks for task cancellation, detects loops (repeated tool calls). | | PostToolUse | After each tool call | Syncs identity file edits to the database; auto-indexes memory files. | | UserPromptSubmit | New iteration starts | Detects task cancellation requests. | | Stop | Session ends | Saves PM2 state, syncs all identity files, runs session summarization. |

Templates Registry

Agent Swarm provides pre-built agent templates (9 official roles) that users can deploy:

Lead Agent: Manages task delegation.
Coder: Focuses on code generation and debugging.
Researcher: Handles data analysis and exploration.
Reviewer: Reviews PRs, code quality, and documentation.
Tester: Executes automated tests.
FDE (Frontend Developer Expert): Specializes in frontend development.
Content-Writer: Creates documentation or marketing content.
Content-Reviewer: Evaluates written content for accuracy.
Content-Strategist: Plans content workflows.

Users can build these templates using docker-compose files provided by the project.

GitLab Integration

Agent Swarm supports GitLab via webhooks, allowing:

Task creation from @mentions in MRs/issues.
Pipeline failure notifications for CI/CD monitoring.

Workers include a pre-installed glab CLI tool for GitLab operations (e.g., creating MRs, commenting on issues).

Sentry Integration

For debugging and error tracking, workers can investigate Sentry issues directly via the /investigate-sentry-issue command. Users must set up SENTRY_AUTH_TOKEN and SENTRY_ORG in their worker’s environment.

User Interface & Dashboard

Web Dashboard (app.agent-swarm.dev)

A hosted dashboard allows users to:

Monitor agent statuses, task progress, and inter-agent communication.
Connect deployed swarms for real-time visibility.

Interactive Documentation

The platform provides:

OpenAPI 3.1 specs (http://localhost:3013/openapi.json) for API developers.
A machine-readable documentation system via Scalar UI (http://localhost:3013/docs).

Command Line Interface (CLI)

Agent Swarm offers a CLI for quick deployments and management: | Command | Description | |--------------|-----------------------------------------------------------------------------| | setup | Configures Claude Code to connect to the swarm. | | mcp | Starts the MCP API server. | | worker | Runs a worker agent in Docker. | | lead | Runs a lead agent (if using Claude Code). |

Example usage:

bunx @desplega.ai/agent-swarm setup  # Connects Claude Code to Agent Swarm

Deployment for Production

For scalable deployments, users should refer to the DEPLOYMENT.md guide:

Docker Compose setup with multiple workers.
Systemd deployment for API servers.
Graceful shutdown and task resume.
Integration configuration (Slack, GitHub, AgentMail, Sentry).

Documentation & Community Support

Official Documentation

docs.agent-swarm.dev: Comprehensive guides on setup, features, and integrations.
DEPLOYMENT.md: Production deployment guide.
ENVS.md: Environment variables reference.

Community & Contributions

Agent Swarm encourages contributions through:

Open-source licensing (MIT).
A welcoming Discord server for real-time discussions.
A CONTRIBUTING.md guide for developers.

Conclusion: Why Agent Swarm Stands Out

Agent Swarm redefines AI-powered workflows by introducing: ✅ Autonomous task delegation between lead and worker agents. ✅ Docker isolation for secure, environment-agnostic execution. ✅ Compounding memory system that enhances agent intelligence over time. ✅ Multi-platform integration (Slack, GitHub, GitLab, email). ✅ Persistent identity management for consistent agent behavior.

For developers and teams seeking a scalable, self-improving AI assistant, Agent Swarm provides an unparalleled solution that eliminates manual intervention while fostering continuous learning. Whether deployed locally or in production, the platform empowers users to automate complex workflows efficiently.

Final Thoughts

Agent Swarm is not just another AI tool—it’s a collaborative ecosystem where agents learn from each other and grow smarter with every task. By leveraging Docker isolation, memory systems, and persistent identities, it sets a new standard for AI-powered automation in software development.

For further exploration, users can visit:

Would you like a deeper dive into any specific feature or deployment scenario?

Agent Swarm: AI Coding Agents That Learn & Collaborate