desplega-ai / agent-swarm

Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants. Built by desplega.sh — by builders, for builders. https://github.com/user-attachments/assets/bd308567-d21e-44a5-87ec-d25aeb1de3d3 > **What if your AI agents remembered everything, learned from every mistake, and got better with every task?** Agent Swarm lets you run a team of AI coding agents that coordinate autonomously. A **lead agent** receives tasks (from you, Slack, or GitHub), breaks them down, and delegates to **worker agents** running in Docker containers. Workers execute tasks, report progress, and ship code — all without manual intervention. Key Features • **Lead/Worker coordination** — A lead agent delegates and tracks work across multiple workers • **Docker isolation** — Each worker runs in its own container with a full dev environment • **Slack, GitHub, GitLab & Email integration** — Create tasks by messaging the bot, @mentioning it in issues/PRs/MRs, or sending an email • **Task lifecycle** — Priority queues, dependencies, pause/resume across deployments • **Compounding memory** — Agents learn from every session and get smarter over time • **Persistent identity** — Each agent has its own personality, expertise, and working style that evolves • **Dashboard UI** — Real-time monitoring of agents, tasks, and inter-agent chat • **Service discovery** — Workers can expose HTTP services and discover each other • **Scheduled tasks** — Cron-based recurring task automation • **Templates registry** — Pre-built agent templates (9 official: lead, coder, researcher, reviewer, tester, FDE, content-writer, content-reviewer, content-strategist) with a gallery UI and docker-compose builder • **GitLab integration** — Full GitLab webhook support alongside GitHub via provider adapter pattern • **Working directory support** — Tasks can specify a custom starting directory for agents via the parameter • **Multi-provider** — Run agents with Claude Code or pi-mono ( ) • **Agent-fs integration** — Persistent, searchable filesystem shared across the swarm with auto-registration on first boot • **Debug dashboard** — SQL query interface with Monaco editor and AG Grid results for database inspection • **Workflow engine** — DAG-based workflow automation with executor registry, checkpoint durability, webhook/schedule/manual triggers, per-step retry, structured I/O schemas, fan-out/convergence, configurable failure handling, and version history • **Linear integration** — Bidirectional ticket tracker sync via OAuth + webhooks with AgentSession lifecycle and generic tracker abstraction • **Portless local dev** — Friendly URLs for local development ( ) via portless proxy • **Onboarding wizard** — Interactive CLI wizard ( ) to set up a new swarm from scratch with presets, credential collection, and docker-compose generation Quick Start Prerequisites • Docker and Docker Compose • A Claude Code OAuth token ( ) Option A: Docker Compose (recommended) The fastest way to get a full swarm running — API server, lead agent, and 2 workers. The API runs on port . The dashboard is available separately (see Dashboard). The API includes interactive documentation at (Scalar UI) and a machine-readable OpenAPI 3.1 spec at . Option B: Local API + Docker Workers Run the API locally and connect Docker workers to it. In a new terminal, start a worker: Option C: Claude Code as Lead Agent Use Claude Code directly as the lead agent — no Docker required for the lead. This configures Claude Code to connect to the swarm. Start Claude Code and tell it: How It Works • **You send a task** — via Slack DM, GitHub @mention, email, or directly through the API • **Lead agent plans** — breaks the task down and assigns subtasks to workers • **Workers execute** — each in an isolated Docker container with git, Node.js, Python, etc. • **Progress is tracked** — real-time updates in the dashboard, Slack threads, or API • **Results are delivered** — PRs created, issues closed, Slack replies sent • **Agents learn** — every session's learnings are extracted and recalled in future tasks Agents Get Smarter Over Time Agent Swarm agents aren't stateless. They build compounding knowledge through multiple automatic mechanisms: Memory System Every agent has a searchable memory backed by OpenAI embeddings ( ). Memories are automatically created from: • **Session summaries** — At the end of each session, a lightweight model extracts key learnings: mistakes made, patterns discovered, failed approaches, and codebase knowledge. These summaries become searchable memories. • **Task completions** — Every completed (or failed) task's output is indexed. Failed tasks include notes about what went wrong, so the agent avoids repeating the same mistake. • **File-based notes** — Agents write to in their per-agent directory. Files are automatically indexed and can be promoted to swarm scope. • **Lead-to-worker injection** — The lead agent can push specific learnings into any worker's memory using the tool, closing the feedback loop. Before starting each task, the runner automatically searches for relevant memories and includes them in the agent's context. Past experience directly informs future work. Persistent Identity Each agent has four identity files that persist across sessions and evolve over time: | File | Purpose | Example | |------|---------|---------| | **SOUL.md** | Core persona, values, behavioral directives | "You're not a chatbot. Be thorough. Own your mistakes." | | **IDENTITY.md** | Expertise, working style, track record | "I'm the coding arm of the swarm. I ship fast and clean." | | **TOOLS.md** | Environment knowledge — repos, services, APIs | "The API runs on port 3013. Use for worktree management." | | **CLAUDE.md** | Persistent notes and instructions | Learnings, preferences, important context | Agents can edit these files directly during a session. Changes are synced to the database in real-time (on every file edit) and at session end. Wh…