Summary

Agent Swarm is a framework for orchestrating multiple AI coding agents, designed to automate complex development tasks. It addresses the need for AI agents that can learn from past mistakes, maintain persistent identities, and coordinate autonomously. The target audience includes engineers, researchers, and power users seeking to leverage AI for coding assistance, offering benefits like improved agent performance over time and reduced manual intervention in development workflows.

How It Works

The system employs a lead-and-worker agent architecture, where a lead agent breaks down tasks and delegates subtasks to worker agents running within isolated Docker containers. Communication and state management are handled by an MCP API server, backed by a SQLite database. Its core novelty lies in a compounding memory system utilizing OpenAI embeddings to store and recall session summaries and task outcomes, alongside persistent agent identity files (SOUL.md, IDENTITY.md, TOOLS.md, CLAUDE.md) that evolve with experience. This allows agents to learn, adapt, and avoid repeating errors, enhancing their effectiveness across sessions.

Quick Start & Requirements

The recommended quick start involves cloning the repository, configuring environment variables (including a Claude Code OAuth token), and launching the system via Docker Compose:

git clone https://github.com/desplega-ai/agent-swarm.git
cd agent-swarm
cp .env.docker.example .env
# Edit .env with API_KEY and CLAUDE_CODE_OAUTH_TOKEN
docker compose -f docker-compose.example.yml --env-file .env up -d

Prerequisites include Docker and Docker Compose. The API server runs on port 3013. Further documentation is available at docs.agent-swarm.dev.

Highlighted Details

• Compounding Memory: Agents learn from every session via summaries and indexed task completions, leveraging OpenAI embeddings for searchable recall.
• Persistent Identity: Agents possess evolving identity files (SOUL.md, IDENTITY.md, TOOLS.md, CLAUDE.md) that define persona, expertise, and knowledge, syncing in real-time.
• Multi-Agent Orchestration: Lead/worker coordination with Docker isolation provides full development environments for workers.
• Extensive Integrations: Supports task creation and notifications via Slack, GitHub, GitLab, and email (AgentMail).
• Hook System: Six hooks manage agent lifecycle, context, tool use, and persistence during sessions.
• Templates Registry: Offers pre-built agent roles like coder, researcher, reviewer, and tester.

Maintenance & Community

The project is developed "by builders, for builders" and encourages contributions. A Discord community is available for discussion and support.

Licensing & Compatibility

The project is licensed under the MIT License (2025-2026). This license generally permits commercial use and integration into closed-source projects.

Limitations & Caveats

Setup requires familiarity with Docker and Docker Compose, potentially increasing the initial barrier to entry. Core functionality relies on external AI models (Claude Code) and services (OpenAI embeddings), introducing external dependencies and potential costs. The system's complexity may necessitate a learning curve for users unfamiliar with multi-agent systems.