Agent Swarm MCP

agent-swarm.mp4

Agent orchestration layer MCP for Claude Code, Codex, Gemini CLI, and more!

Table of Contents

• What is Agent Swarm?
• Quick Start
• CLI Commands
• Deployment
• Documentation
• License

---

What is Agent Swarm?

Agent Swarm MCP enables multi-agent coordination for AI coding assistants. It provides:

• Task Management - Assign, track, and coordinate tasks across agents
• Agent Communication - Channel-based messaging between agents
• Service Discovery - Register and discover background services
• Docker Workers - Run isolated Claude workers in containers
• Lead/Worker Pattern - Coordinate work with a lead agent and multiple workers
• Dashboard UI - Real-time monitoring dashboard for agents, tasks, and channels

---

Dashboard UI

A React-based monitoring dashboard is available in the ui/ directory. See UI.md for details.

cd ui
pnpm install
pnpm run dev

The dashboard runs at http://localhost:5173 by default.

---

GitHub Integration

Agent Swarm can receive tasks from GitHub via webhooks. When someone mentions @agent-swarm-bot (or your configured bot name) in an issue, PR, or comment, a task is automatically created for the lead agent.

Setup

1. Create a GitHub App at https://github.com/settings/apps/new
2. Set the webhook URL to https://your-server.com/api/github/webhook
3. Generate a webhook secret and add to .env:

   GITHUB_WEBHOOK_SECRET=your-secret
   GITHUB_BOT_NAME=agent-swarm-bot  # optional, default: agent-swarm-bot

4. Enable webhook events: Issues, Issue comment, Pull request, Pull request review comment
5. Install the app on your repositories

Agent Commands

Command	Description
/implement-issue	Read issue, implement changes, create PR
/review-pr	Analyze and review a pull request
/create-pr	Create PR from current branch changes
/close-issue	Close issue with summary comment
/respond-github	Comment on an issue or PR

---

Sentry Integration

Docker workers include sentry-cli pre-installed, enabling agents to investigate and triage Sentry issues directly. This is useful for debugging errors reported via Slack alerts.

Setup

1. Create an Organization Auth Token at https://sentry.io/settings/{org}/auth-tokens/ with scopes:

   • event:read - Read issues and events
   • project:read - Read project data
   • org:read - Read organization info

2. Add to .env.docker:

   SENTRY_AUTH_TOKEN=your-auth-token
   SENTRY_ORG=your-org-slug

3. Verify authentication in a worker:

   sentry-cli info

Agent Commands

Command	Description
/investigate-sentry-issue <url-or-id>	Investigate a Sentry issue, get stacktrace, and triage

Usage

Workers can use the /investigate-sentry-issue command to:

• Get issue details and stacktraces
• Analyze breadcrumbs and context
• Resolve, mute, or unresolve issues

Example:

/investigate-sentry-issue https://sentry.io/organizations/myorg/issues/123456/

Or just the issue ID:

/investigate-sentry-issue 123456

---

Quick Start

The recommended setup: run the API locally, run a Docker worker, and connect Claude Code as the lead agent.

Prerequisites

• Bun (or Node.js 22+)
• Docker
• Claude Code CLI

1. Clone & Install

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

2. Configure Environment

For the API server:

cp .env.example .env

Required in .env:

• API_KEY - Secret key for API authentication (can be left empty, e.g. for local-only setups)

For Docker workers:

cp .env.docker.example .env.docker

Required in .env.docker:

• API_KEY - Same key as the API server
• CLAUDE_CODE_OAUTH_TOKEN - Run claude setup-token to get this

See .env.example and .env.docker.example for additional optional variables.

3. Start the API Server

bun run start:http

The MCP server runs at http://localhost:3013.

4. Run a Docker Worker

In a new terminal:

bun run docker:build:worker
mkdir -p ./logs ./work/shared ./work/worker-1
bun run docker:run:worker

The worker joins the swarm and waits for tasks.

Note

We automatically build a Docker image for Claude Code workers: ghcr.io/desplega-ai/agent-swarm-worker:latest.

5. Connect Claude Code as Lead

In your project directory:

bunx @desplega.ai/agent-swarm setup

This configures Claude Code to connect to the swarm. Then start Claude Code normally and mention the following:

Register yourself as the lead agent in the agent-swarm MCP.

This will be a one-time setup, to make sure you are registered as the lead agent in the swarm, using the provided API key and agent ID (optional).

Notes

• The setup command will automatically back-up the updated files, in case you want to revert later (using --restore).
• Use --dry-run to preview changes without applying them.

---

CLI Commands

We will be publishing the package to npm as @desplega.ai/agent-swarm on each new tag bump of the package.json.

Command	Description
setup	Initialize agent-swarm in a project
mcp	Start the MCP HTTP server
worker	Run Claude as a worker agent
lead	Run Claude as a lead agent
hook	Handle Claude Code hook events
help	Show help message

Examples

# Setup wizard
bunx @desplega.ai/agent-swarm setup

# Start MCP & API server on custom port
bunx @desplega.ai/agent-swarm mcp --port 8080 --key my-api-key

# Run worker with custom system prompt (not in docker!!! beware)
bunx @desplega.ai/agent-swarm worker --system-prompt "You are a Python specialist"

# Run lead agent in the background (without human-in-the-loop mode via MCP client)
bunx @desplega.ai/agent-swarm lead

---

Deployment

For production deployments, see docker-compose.example.yml which sets up:

• API service (MCP HTTP server)
• Multiple worker agents
• Lead agent
• Shared volumes for logs and workspaces

Full deployment options are documented in DEPLOYMENT.md.

---

Documentation

Document	Description
UI.md	Dashboard UI overview
DEPLOYMENT.md	Docker, Docker Compose, systemd deployment
CONTRIBUTING.md	Development setup, code quality, project structure
MCP.md	MCP tools reference (auto-generated)
FAQ.md	Frequently asked questions

---

License

MIT License - 2025-2026 desplega.ai