agent-swarm

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

[!TIP] This repo evolves every single day. Watch now →

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

agent-swarm.dev is an open-source operating system for AI work. A lead agent delegates goals to workers such as Claude Code or Codex. Isolated containers, shared memory, tools, schedules, and review gates preserve work across sessions.

What you get

• A lead agent that receives work from Slack, repositories, issue trackers, email, or the API
• Schema-validated task results for callers that need structured JSON output
• Deferred tasks that wake when all or any watched tasks reach an outcome, or a deadline arrives
• Inline tool-result images in task logs, with previews that open at full size
• Dashboard file attachments by paste, drag-and-drop, or file picker
• Workers in isolated Docker containers with development environments
• Memory and identity that persist across sessions
• Workflows, schedules, scripts, and apps for recurring work
• Extensions for trusted TypeScript hooks, installed as agent-owned inert drafts and activated by a trusted lead, operator, or dashboard user
• Realtime rooms for shared page state, presence, and live channels
• Your choice of harness and models: Claude Code, Codex, pi, opencode, Devin, or ACP agents

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

Quick Start

Give your coding agent the operator skill for Docker Compose or Kubernetes:

npx skills add desplega-ai/agent-swarm

Or install it as a plugin in your harness:

Harness	Command
Claude Code	/plugin marketplace add desplega-ai/agent-swarm then /plugin install agent-swarm@agent-swarm
Codex	codex plugin add https://github.com/desplega-ai/agent-swarm (or use npx skills above)
Cursor	/add-plugin desplega-ai/agent-swarm
Gemini CLI	gemini extensions install https://github.com/desplega-ai/agent-swarm
Antigravity / Factory Droid	droid plugin marketplace add https://github.com/desplega-ai/agent-swarm then droid plugin install agent-swarm@agent-swarm
OpenCode, pi, Devin, Kimi, others	npx skills add desplega-ai/agent-swarm

The plugin's privacy and terms links describe the Agent Swarm website and Cloud service. The self-hosted software remains covered by the MIT License.

Or use the examples directly:

git clone https://github.com/desplega-ai/agent-swarm.git && cd agent-swarm
cp .env.docker.example .env  # Set API_KEY, a harness credential, and all eight agent UUIDs.
openssl rand -base64 32 > encryption_key
chmod 600 .env encryption_key
docker compose -f docker-compose.example.yml --env-file .env up -d

Read the Compose checklist before starting. API: http://localhost:3013, with /docs and /openapi.json. Dashboard: connect it to your API. Kubernetes: install the OCI Helm chart.

Integrations

Slack · GitHub · GitLab · Linear · Jira · AgentMail · WhatsApp (Kapso) · Composio · Sentry · Devin · Serply search. Integration guides.

AgentMail archives verified inbound deliveries before acknowledging them and retains the archive for 30 days, including mail excluded from task routing. See the contact inbox triage runbook for retention, coverage limits, and rollout instructions.

Learn more

• Getting started · Architecture · Playbooks · CLI · API reference
• Agent templates
• Help: contact@desplega.sh · Discord

Contributing

Read CONTRIBUTING.md, fork the repository, create a branch, and open a PR. Discuss ideas on Discord.

Are you an agent? Run npx skills add desplega-ai/agent-swarm or read the operator skill.

Star History

License

MIT · 2025-2026 desplega.sh

Feature defaults

Fresh deployments enable Slack thread renderer v2, queued Slack steering to the lead, task steering, multi-runtime workers, RBAC, and task-tool preloading. Hybrid memory search and graph expansion are also enabled. Explicit environment/config overrides remain supported; see the environment reference. When upgrading older workers, keep MULTI_RUNTIME_ENABLED=false until they support runtime identities. Slack delegation rendering remains opt-in, and database retention continues to default to dry-run.