README.md

July 9, 2026 · View on GitHub

_{🚀 We're live on Product Hunt today — the swarm is running its own launch. An upvote helps.}

An engine to make your company AI Native
_{Built by desplega.sh — by builders, for builders.}

Tip

This repo evolves every single day. Watch now →

_{▸ daily evolution · slack → pr · Making of}

Agent Swarm is your Company's Compounding Intelligence Layer. A system of AI agents that remember, reason, act and get better with every task.

AI-Native · Compounds · Presence · Harness & LLM-Agnostic · Your Infra · Your Memory ·

What it does

Agent Swarm runs a team of AI agents that coordinate autonomously. A lead agent receives tasks (from Slack, GitHub, GitLab, Linear, Jira, email, or the API), breaks them down, and delegates to worker agents running in isolated environments (Docker). Workers execute tasks, ship solutions, and write their learnings back to a shared memory so the whole swarm gets smarter every session.

You can run agents for Marketing, Product, UX, Engineering, Support, Operations, HR, Finance, or any role you can think of. A centralized Lead coordinates them, and they share the learnings horizontally. That's the true difference between AI First and AI Native.

Agent Swarm is the shared cloud brain and muscle that makes your whole company better every day.

Sometimes humans are the blocker. We can help you. Contact us contact@desplega.sh.

Learn more in the architecture overview.

flowchart LR
    subgraph IN["Tasks come in"]
        direction TB
        S["Slack"]
        G["GitHub / GitLab"]
        E["Email"]
        A["API / CLI"]
    end

    LEAD(["Lead Agent<br/>plans &amp; delegates"])

    subgraph WORKERS["Workers in Docker"]
        direction TB
        W1["Worker"]
        W2["Worker"]
        W3["Worker"]
    end

    subgraph BRAIN["Persistent brain"]
        direction TB
        MEM["Memory<br/>(vector search)"]
        ID["Identity<br/>(SOUL, CLAUDE.md)"]
    end

    subgraph OUT["Work ships"]
        direction TB
        PR["Pull Requests"]
        REPLY["Slack replies"]
        EMAIL["Email replies"]
    end

    IN --> LEAD --> WORKERS
    WORKERS -->|reads context| BRAIN
    WORKERS -->|writes learnings| BRAIN
    WORKERS --> OUT

Known Use Cases

Use cases that are used daily by ourselves and others. Each playbook contains: the agents, the tools & skills, and workflows & schedules behind it. Browse all playbooks →

Feature Development — Integrated with Linear and GitHub to take feature requests from Slack and turn them into pull requests.
Lead Prospecting — Integrate your prospecting tools with the swarm and let agents handle outreach, scheduling, and follow-up.
Content Generation — Generate engagement tools, blog posts, manage social media presence, update your website, and more.
UX Command Center — Agents that keep your product usable: record agentic sessions, enforce your design system, and mine user logs to detect and propose UX improvements.
Proactive Customer Support — Agents that oversee your top accounts, prepare scheduled reports, and leverage everything they know about your platform to keep those accounts up to date.
Code Health & Alert Management — Datadog, New Relic, Sentry, or any alerting tool can kick off fixes or new proposals. Monitor code health and propose improvements weekly, daily, or hourly.
Reports from Multiple Sources — Integrate your data warehouse to generate tailored reports and answer the key questions your team has, with fresh data. Your BI tool may be a thing of the past.
Self-Documenting & Release Reports — Update your docs and use frameworks like Remotion, qa-use, and browser-use to generate release videos and rich documentation in seconds, at the cadence you need.
Do you have a cool playbook to share? Send us a PR!

The patterns that compound. Five recipes show up in nearly every playbook — they're how the swarm stays reliable as it scales: Litmus Tests (LLM-as-judge quality gates) · Drain Loops (one ticket → a chain of reviewable PRs) · HITL Gates (pause for human approval on irreversible steps) · Per-Customer Working Directories (context that compounds per account) · No-op Workflows (skip silently when nothing changed). See all patterns →

Check our templates for a quick start.

Highlights

Lead/worker orchestration in Docker — isolated dev environments, priority queues, pause/resume across deploys. Architecture →
Compounding memory & persistent identity — agents remember past sessions and evolve their own persona, expertise, and notes. Memory → · Agents →
Hybrid + graph-linked memory recall — memory retrieval can blend vector and full-text ranking, expand through linked memories, surface usefulness readouts, and let agents correct an existing memory without losing its ID or history. Memory → · MCP tools →
Multi-channel inputs — Slack, GitHub, GitLab, email, WhatsApp, Linear, Jira, and the HTTP API all create tasks. Integrations
Workflow engine with Human-in-the-Loop — DAG-based automation with approval gates, retries, and structured I/O. Workflows →
Scheduled & recurring tasks — cron-based automation for standing work, with schedules that can target agent tasks, workflows, or catalog scripts. Scheduling →
Durable script workflows — launch background script runs, inspect their journals, and track them from the dashboard when a one-shot script-run is too small. Guide →
Scripts as external APIs — expose a saved script as a public POST /api/x/script/<id> endpoint with optional bearer auth, typed input validation, and per-endpoint usage tracking. Guide →
Typed script API connections — lead-managed OpenAPI, GraphQL, and MCP connections generate ctx.api.* / ctx.mcp.* clients for scripts, with credential bindings and OAuth-backed auth kept server-side. Guide →
E2B-backed eval harness — run a scenario × harness-config matrix against real swarm stacks, capture transcripts/artifacts, and grade outcomes with deterministic checks plus LLM or agentic judges. Guide →
Harness & LLM agnostic — run with Claude Code, Claude Bridge, OpenAI Codex, pi-mono (Anthropic, OpenRouter, or Amazon Bedrock), Devin, Claude Managed Agents, raw LLMs, or opencode. Tasks, schedules, and workflow agent-task nodes can use portable modelTier intent (smol, regular, smart, ultra), and operators can set per-agent reasoning effort (off → xhigh) without changing task payloads. Harness config → · Add a new provider →
OpenTelemetry traces plus OTLP cost/token metrics — export API + worker traces and finalized session cost/token counters through the same OTLP pipeline for dashboarding in SigNoz, Datadog, Tempo, or another compatible backend. Observability →
Follow-up continuity across all harnesses — child tasks inherit a bounded prior-task context preamble built from the task chain, so continuity survives restarts and works the same across every provider. Task lifecycle →
Skills & MCP servers — reusable procedural knowledge, bundled skill reference files, and per-agent MCP servers with scope cascade. MCP tools →
External tool-router access — the x command and swarm_x MCP tool let humans and agents execute approved third-party routes such as Composio without baking bespoke MCP servers first. CLI → · Composio →
Config-driven metrics dashboards — define read-only SQL widgets, version them, and render them in the dashboard without shipping custom frontend code. Metrics API →
DB-backed pages — agents publish HTML or JSON pages (reports, dashboards, action specs) via create_page, remove stale pages with delete-page, and share them with public / authed / password modes, version history, view counters, diff helpers, and PDF export. MCP tools → Pages
KV store — Redis-like namespaced key/value store with auto-scoped context (Slack thread / PR / Linear issue / page). MCP tools → KV
Real-time dashboard + task attachments — monitor agents, tasks, and inter-agent chat, create tasks with uploaded files from the sessions composer, and preview task attachments inline above session prompts. app.agent-swarm.dev →

Quick Start

Need help? Contact us at contact@desplega.sh.

Prerequisites: Docker and at least one supported harness credential. The default quick start assumes a Claude Code OAuth token (claude setup-token), but pi-mono / Bedrock, Codex, Devin, and other provider setups are also supported.

The fastest way is the onboarding wizard — it collects credentials, picks presets, and generates a working docker-compose.yml:

bunx @desplega.ai/agent-swarm onboard
npx @desplega.ai/agent-swarm onboard

Prefer manual setup? Clone and run with Docker Compose:

git clone https://github.com/desplega-ai/agent-swarm.git
cd agent-swarm
cp .env.docker.example .env
# edit .env — set API_KEY plus the credential for your chosen harness (for example CLAUDE_CODE_OAUTH_TOKEN)
docker compose -f docker-compose.example.yml --env-file .env up -d

The API runs on port 3013, with interactive docs at http://localhost:3013/docs and an OpenAPI 3.1 spec at http://localhost:3013/openapi.json.

Other setups

Local API + Docker workers — run the API on your host, workers in Docker. See Getting Started.
Claude Code as the lead agent — bunx @desplega.ai/agent-swarm connect (or npx @desplega.ai/agent-swarm connect), then tell Claude Code to register as the lead.

How It Works

You (Slack / GitHub / Email / CLI)
        |
   Lead Agent  ←→  MCP API Server  ←→  SQLite DB
        |
   ┌────┼────┐
Worker  Worker  Worker
(Docker containers with full dev environments)

A task arrives via Slack DM, GitHub @mention, email, or the API.
The lead plans and delegates subtasks to workers.
Workers execute in isolated Docker containers (git, Node.js, Python, etc.).
Progress streams to the dashboard, Slack threads, or the API.
Results ship back out as PRs, custom pages, issue replies, or Slack messages.
Session learnings are extracted and become memory for future tasks.

More detail in the task lifecycle docs.

Integrations

Missing one? Ask the swarm to build it.

Integration	What it does	Setup
Slack	DM or @mention the bot to create tasks; workers reply in threads	Guide
GitHub App	@mention or assign the bot on issues/PRs; CI failures create follow-up tasks	Guide
GitLab	Same model as GitHub — webhooks on issues/MRs, `glab` preinstalled in workers	Guide
AgentMail	Give each agent an inbox; emails become tasks or lead messages	Guide
Kapso (WhatsApp)	Native inbound WhatsApp webhook routing; agents reply over WhatsApp with MCP tools or the `kapso-whatsapp` skill	Guide
Composio	Route approved third-party app operations through `agent-swarm x composio ...` or the `swarm_x` MCP tool	Guide
Linear	Bidirectional ticket sync via OAuth + webhooks	Guide
Jira Cloud	OAuth 3LO ticket sync — assignee/comment events create tasks; lifecycle posts comments back	Guide
Sentry	Workers can triage Sentry issues with the `/investigate-sentry-issue` command	Guide
Devin	Devin can be a node in your swarm — keep your existing configuration	Guide

Dashboard

Real-time monitoring of agents, tasks, and inter-agent chat. Use the hosted version at app.agent-swarm.dev, or run locally:

cd apps/ui && bun install && bun run dev

Opens at http://localhost:5274.

CLI

bunx @desplega.ai/agent-swarm <command>
npx @desplega.ai/agent-swarm <command>

Command	Description
`onboard`	Set up a new swarm from scratch (Docker Compose wizard)
`connect`	Connect this project to an existing swarm
`api`	Start the API + MCP HTTP server
`worker`	Run a worker agent
`lead`	Run a lead agent
`e2b`	Build E2B templates and launch/manage grouped API + lead + worker swarms
`x`	Execute approved external routes such as Composio
`docs`	Open documentation (`--open` to launch in browser)

Deployment

For production deployments (Docker Compose with multiple workers, systemd for the API, graceful shutdown, integration config), see DEPLOYMENT.md and the deployment guide.

Documentation

Everything lives at docs.agent-swarm.dev. Good starting points:

Getting Started — install, configure, and run your first task
Architecture overview — how the swarm is wired together
Playbooks — eight production flows we use to run Desplega, plus the patterns behind them
CLI reference and Environment variables
API reference — every HTTP endpoint

Contributing

We love contributions! Whether it's bug reports, feature requests, docs improvements, or code — all are welcome.

See CONTRIBUTING.md to get started. The quickest way to contribute:

Fork the repo
Create a branch (git checkout -b my-feature)
Make your changes
Open a PR

Join our Discord if you have questions or want to discuss ideas.

Are you an agent? Go to agent-swarm.dev/skill.md.

Star History

License

MIT — 2025-2026 desplega.sh