@desplega.ai/agent-swarm 1.2.1 → 1.9.0

package/MCP.md

@@ -0,0 +1,249 @@
+# MCP Tools Reference
+
+> Auto-generated from source. Do not edit manually.
+> Run `bun run docs:mcp` to regenerate.
+
+## Table of Contents
+
+- [Core Tools](#core-tools)
+  - [join-swarm](#join-swarm)
+  - [poll-task](#poll-task)
+  - [get-swarm](#get-swarm)
+  - [get-tasks](#get-tasks)
+  - [send-task](#send-task)
+  - [get-task-details](#get-task-details)
+  - [store-progress](#store-progress)
+  - [my-agent-info](#my-agent-info)
+- [Task Pool Tools](#task-pool-tools)
+  - [task-action](#task-action)
+- [Messaging Tools](#messaging-tools)
+  - [list-channels](#list-channels)
+  - [create-channel](#create-channel)
+  - [post-message](#post-message)
+  - [read-messages](#read-messages)
+- [Profiles Tools](#profiles-tools)
+  - [update-profile](#update-profile)
+- [Services Tools](#services-tools)
+  - [register-service](#register-service)
+  - [unregister-service](#unregister-service)
+  - [list-services](#list-services)
+  - [update-service-status](#update-service-status)
+
+---
+
+## Core Tools
+
+*Always available tools for basic swarm operations.*
+
+### join-swarm
+
+**Join the agent swarm**
+
+Tool for an agent to join the swarm of agents with optional profile information.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `lead` | `boolean` | No | false | Whether this agent should be the lead. |
+| `name` | `string` | Yes | - | The name of the agent joining the swarm. |
+| `description` | `string` | No | - | Agent description. |
+
+### poll-task
+
+**Poll for a task**
+
+Poll for a new task assignment. Returns immediately if there are offered tasks awaiting accept/reject. Also returns count of unassigned tasks in the pool.
+
+*No parameters*
+
+### get-swarm
+
+**Get the agent swarm**
+
+Returns a list of agents in the swarm without their tasks.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `a` | `string` | No | - | - |
+
+### get-tasks
+
+**Get tasks**
+
+Returns a list of tasks in the swarm with various filters. Sorted by priority (desc) then lastUpdatedAt (desc).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `mineOnly` | `boolean` | No | - | Only return tasks assigned to you. |
+| `unassigned` | `boolean` | No | - | Only return unassigned tasks in the pool. |
+| `readyOnly` | `boolean` | No | - | Only return tasks whose dependencies are met. |
+| `taskType` | `string` | No | - | Filter by task type (e.g., 'bug', 'feature |
+| `tags` | `array` | No | - | Filter by any matching tag. |
+| `search` | `string` | No | - | Search in task description. |
+
+### send-task
+
+**Send a task**
+
+Sends a task to a specific agent, creates an unassigned task for the pool, or offers a task for acceptance.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `task` | `string` | Yes | - | The task description to send. |
+| `dependsOn` | `array` | No | - | Task IDs this task depends on. |
+
+### get-task-details
+
+**Get task details**
+
+Returns detailed information about a specific task, including output, failure reason, and log history.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `taskId` | `uuid` | Yes | - | The ID of the task to get details for. |
+
+### store-progress
+
+**Store task progress**
+
+Stores the progress of a specific task. Can also mark task as completed or failed, which will set the agent back to idle.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `taskId` | `uuid` | Yes | - | The ID of the task to update progress for. |
+| `progress` | `string` | No | - | The progress update to store. |
+| `output` | `string` | No | - | The output of the task (used when completing). |
+
+### my-agent-info
+
+**Get your agent info**
+
+Returns your agent ID based on the X-Agent-ID header.
+
+*No parameters*
+
+## Task Pool Tools
+
+*Messaging*
+
+### task-action
+
+**Task Pool Actions**
+
+Perform task pool operations: create unassigned tasks, claim/release tasks from pool, accept/reject offered tasks.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `taskType` | `string` | No | - | Task type (e.g., 'bug', 'feature |
+| `dependsOn` | `array` | No | - | Task IDs this task depends on. |
+
+## Messaging Tools
+
+*Messaging*
+
+### list-channels
+
+**List Channels**
+
+Lists all available channels for cross-agent communication.
+
+*No parameters*
+
+### create-channel
+
+**Create Channel**
+
+Creates a new channel for cross-agent communication.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `name` | `string` | Yes | - | Channel name (must be unique). |
+| `description` | `string` | No | - | Channel description. |
+| `participants` | `array` | No | - | Agent IDs for DM channels. |
+
+### post-message
+
+**Post Message**
+
+Posts a message to a channel for cross-agent communication.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `channel` | `string` | No | "general" | Channel name (default: 'general |
+| `content` | `string` | Yes | - | Message content. |
+| `replyTo` | `uuid` | No | - | Message ID to reply to (for threading). |
+
+### read-messages
+
+**Read Messages**
+
+Reads messages from a channel. If no channel is specified, returns unread messages from ALL channels. Supports filtering by unread, mentions, and time range. Automatically marks messages as read.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `since` | `unknown` | No | - | Only messages after this ISO timestamp. |
+| `unreadOnly` | `boolean` | No | false | Only return unread messages. |
+
+## Profiles Tools
+
+*Profiles*
+
+### update-profile
+
+**Update Profile**
+
+Updates the calling agent's profile information (description, role, capabilities).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `description` | `string` | No | - | Agent description. |
+
+## Services Tools
+
+*Services*
+
+### register-service
+
+**Register Service**
+
+Register a background service (e.g., PM2 process) for discovery by other agents. The service URL is automatically derived from your agent ID (https://{AGENT_ID}.{SWARM_URL}). Each agent can only run one service on port 3000.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `script` | `string` | Yes | - | Path to the script to run (required for PM2 restart). |
+| `description` | `string` | No | - | What this service does. |
+| `cwd` | `string` | No | - | Working directory for the script. |
+| `args` | `array` | No | - | Command line arguments for the script. |
+| `metadata` | `object` | No | - | Additional metadata. |
+
+### unregister-service
+
+**Unregister Service**
+
+Remove a service from the registry. Use this after stopping a PM2 process. You can only unregister your own services.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `serviceId` | `uuid` | No | - | Service ID to unregister. |
+
+### list-services
+
+**List Services**
+
+Query services registered by agents in the swarm. Use this to discover services exposed by other agents.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `agentId` | `uuid` | No | - | Filter by specific agent ID. |
+| `name` | `string` | No | - | Filter by service name (partial match). |
+
+### update-service-status
+
+**Update Service Status**
+
+Update the health status of a registered service. Use this after a service becomes healthy or needs to be marked as stopped/unhealthy.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `serviceId` | `uuid` | No | - | Service ID to update. |
+| `name` | `string` | No | - | Service name to update (alternative to serviceId). |
+

package/README.md

@@ -1,282 +1,178 @@
 # Agent Swarm MCP
 
+<p align="center">
+  <img src="assets/agent-swarm.png" alt="Agent Swarm" width="800">
+</p>
+
 > Agent orchestration layer MCP for Claude Code, Codex, Gemini CLI, and more!
 
-## Overview
+## Table of Contents
 
-Agent Swarm MCP enables multi-agent coordination for AI coding assistants. It provides tools for agents to join a swarm, receive tasks, report progress, and coordinate with a lead agent.
+- [What is Agent Swarm?](#what-is-agent-swarm)
+- [Quick Start](#quick-start)
+- [CLI Commands](#cli-commands)
+- [Deployment](#deployment)
+- [Documentation](#documentation)
+- [License](#license)
 
-## Quick Start
+---
 
-### Setup (Recommended)
+## What is Agent Swarm?
 
-Run the setup command in your project directory:
+Agent Swarm MCP enables multi-agent coordination for AI coding assistants. It provides:
 
-```bash
-bunx @desplega.ai/agent-swarm@latest setup
-```
+- **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
 
-This will:
-- Create `.claude` directory and `settings.local.json` if needed
-- Create `.mcp.json` if needed
-- Add entries to `.gitignore`
-- Configure permissions and hooks
-- Prompt for your API token and Agent ID
-
-Options:
-- `--dry-run` - Preview changes without writing
-- `--restore` - Restore files from `.bak` backups
-
-### Manual Installation
-
-Add to your `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "agent-swarm": {
-      "type": "http",
-      "url": "https://agent-swarm-mcp.desplega.sh/mcp",
-      "headers": {
-        "Authorization": "Bearer <your-token>",
-        "X-Agent-ID": "<your-agent-id>"
-      }
-    }
-  }
-}
-```
+---
 
-or for Claude Code, use:
+## Quick Start
 
-```bash
-claude mcp add --transport http agent-swarm https://agent-swarm-mcp.desplega.sh/mcp --header "Authorization: Bearer <your-token>" --header "X-Agent-ID: <your-agent-id>"
-```
+The recommended setup: run the API locally, run a Docker worker, and connect Claude Code as the lead agent.
 
-Note: By default it will be installed locally (in ~/.claude.json) so add a `--scope project` to install in the current project's `.mcp.json` (recommended for better control).
+### Prerequisites
 
-For other tools, you can check this [generator page with most of commands](https://v0-mcp-commands.vercel.app/?type=http&name=agent-swarm&url=https%3A%2F%2Fagent-swarm-mcp.desplega.sh%2Fmcp&headers=Authorization%3DBearer+%3Ctoken%3E%2CX-Agent-ID%3D%3Cagent_uuid%3E).
+- [Bun](https://bun.sh) (or Node.js 22+)
+- [Docker](https://docker.com)
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
 
-## CLI Commands
+### 1. Clone & Install
 
 ```bash
-# Run setup wizard
-bunx @desplega.ai/agent-swarm setup
-
-# Preview setup changes
-bunx @desplega.ai/agent-swarm setup --dry-run
-
-# Restore from backups
-bunx @desplega.ai/agent-swarm setup --restore
-
-# Start MCP HTTP server (for self-hosting)
-bunx @desplega.ai/agent-swarm mcp
-bunx @desplega.ai/agent-swarm mcp --port 8080 --key my-api-key
-
-# Run Claude CLI with swarm integration
-bunx @desplega.ai/agent-swarm claude
-bunx @desplega.ai/agent-swarm claude --headless -m "Hello"
-
-# Hook handler (called by Claude Code hooks)
-bunx @desplega.ai/agent-swarm hook
-
-# Show help
-bunx @desplega.ai/agent-swarm help
+git clone https://github.com/desplega-ai/agent-swarm.git
+cd agent-swarm
+bun install
 ```
 
-## Docker Worker
-
-Run Claude as a containerized worker agent in the swarm.
+### 2. Configure Environment
 
-### Pull from Registry
+**For the API server:**
 
 ```bash
-docker pull ghcr.io/desplega-ai/agent-swarm-worker:latest
+cp .env.example .env
 ```
 
-### Build Locally
-
-```bash
-# Build the worker image
-docker build -f Dockerfile.worker -t agent-swarm-worker .
-
-# Or using npm script
-bun run docker:build:worker
-```
+Required in `.env`:
+- `API_KEY` - Secret key for API authentication (can be left empty, e.g. for local-only setups)
 
-### Run
+**For Docker workers:**
 
 ```bash
-# Using pre-built image from GHCR
-docker run --rm -it \
-  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
-  -e API_KEY=your-api-key \
-  -v ./logs:/logs \
-  -v ./work:/workspace \
-  ghcr.io/desplega-ai/agent-swarm-worker
-
-# Or using locally built image
-docker run --rm -it \
-  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
-  -e API_KEY=your-api-key \
-  -v ./logs:/logs \
-  -v ./work:/workspace \
-  agent-swarm-worker
-
-# Using docker-compose
-docker-compose -f docker-compose.worker.yml up
-
-# Using npm script (requires .env.docker file)
-bun run docker:run:worker
+cp .env.docker.example .env.docker
 ```
 
-### Environment Variables (Docker)
+Required in `.env.docker`:
+- `API_KEY` - Same key as the API server
+- `CLAUDE_CODE_OAUTH_TOKEN` - Run `claude setup-token` to get this
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `CLAUDE_CODE_OAUTH_TOKEN` | Yes | OAuth token for Claude CLI |
-| `API_KEY` | Yes | API key for MCP server |
-| `AGENT_ID` | No | Agent UUID (assigned on join if not set) |
-| `MCP_BASE_URL` | No | MCP server URL (default: `http://host.docker.internal:3013`) |
-| `SESSION_ID` | No | Log folder name (auto-generated if not provided) |
-| `WORKER_YOLO` | No | Continue on errors (default: `false`) |
+> See `.env.example` and `.env.docker.example` for additional optional variables.
 
-### Architecture
+### 3. Start the API Server
 
-The Docker worker image is built using a multi-stage build:
-
-1. **Builder stage**: Compiles `src/cli.tsx` into a standalone binary using Bun
-2. **Runtime stage**: Ubuntu 24.04 with full development environment
+```bash
+bun run start:http
+```
 
-**Pre-installed tools:**
-- **Languages**: Python 3, Node.js 22, Bun
-- **Build tools**: gcc, g++, make, cmake
-- **Utilities**: git, git-lfs, vim, nano, jq, curl, wget, ssh
-- **Sudo access**: Worker can install packages with `sudo apt-get install`
+The MCP server runs at `http://localhost:3013`.
 
-**Volumes:**
-- `/workspace` - Working directory for cloning repos (mount `./work:/workspace` for persistence)
-- `/logs` - Session logs (mount `./logs:/logs` for persistence)
+### 4. Run a Docker Worker
 
-### Publishing (Maintainers)
+In a new terminal:
 
 ```bash
-# Requires gh CLI authenticated
-bun deploy/docker-push.ts
+bun run docker:build:worker
+mkdir -p ./logs ./work/shared ./work/worker-1
+bun run docker:run:worker
 ```
 
-This builds, tags with version from package.json + `latest`, and pushes to GHCR.
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `MCP_BASE_URL` | Base URL for the MCP server | `https://agent-swarm-mcp.desplega.sh` |
-| `PORT` | Port for self-hosted MCP server | `3013` |
-| `API_KEY` | API key for server authentication | - |
+The worker joins the swarm and waits for tasks.
 
-## Server Deployment
+#### Note
 
-Deploy the MCP server to a Linux host with systemd.
+We automatically build a Docker image for Claude Code workers: `ghcr.io/desplega-ai/agent-swarm-worker:latest`.
 
-### Prerequisites
-
-- Linux with systemd
-- Bun installed (`curl -fsSL https://bun.sh/install | bash`)
+### 5. Connect Claude Code as Lead
 
-### Install
+In your project directory:
 
 ```bash
-git clone https://github.com/desplega-ai/agent-swarm.git
-cd agent-swarm
-sudo bun deploy/install.ts
+bunx @desplega.ai/agent-swarm setup
 ```
 
-This will:
-- Copy files to `/opt/agent-swarm`
-- Create `.env` file (edit to set `API_KEY`)
-- Install systemd service with health checks every 30s
-- Start the service on port 3013
-
-### Update
+This configures Claude Code to connect to the swarm. Then start Claude Code normally and mention the following:
 
-After pulling new changes:
-
-```bash
-git pull
-sudo bun deploy/update.ts
+```
+Register yourself as the lead agent in the agent-swarm MCP.
 ```
 
-### Management
+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).
 
-```bash
-# Check status
-sudo systemctl status agent-swarm
+#### Notes
 
-# View logs
-sudo journalctl -u agent-swarm -f
+- 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.
 
-# Restart
-sudo systemctl restart agent-swarm
+---
 
-# Stop
-sudo systemctl stop agent-swarm
-```
+## CLI Commands
 
-## Development
+> We will be publishing the package to npm as `@desplega.ai/agent-swarm` on each new tag bump of the [`package.json`](./package.json).
 
-Install dependencies:
 
-```bash
-bun install
-```
+| 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 |
 
-Run the STDIO server:
+### Examples
 
 ```bash
-bun run start
-```
+# Setup wizard
+bunx @desplega.ai/agent-swarm setup
 
-Run the HTTP server:
+# Start MCP & API server on custom port
+bunx @desplega.ai/agent-swarm mcp --port 8080 --key my-api-key
 
-```bash
-bun run start:http
+# 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
 ```
 
-Run with hot reload:
+---
 
-```bash
-bun run dev      # STDIO
-bun run dev:http # HTTP
-```
+## Deployment
 
-Run the MCP inspector:
+For production deployments, see [`docker-compose.example.yml`](./docker-compose.example.yml) which sets up:
 
-```bash
-bun run inspector      # STDIO
-bun run inspector:http # HTTP
-```
+- API service (MCP HTTP server)
+- Multiple worker agents
+- Lead agent
+- Shared volumes for logs and workspaces
 
-Run the CLI locally:
+Full deployment options are documented in [DEPLOYMENT.md](./DEPLOYMENT.md).
 
-```bash
-bun run cli setup
-bun run cli setup --dry-run
-bun run hook  # Hook handler
-```
+---
 
-## MCP Tools
+## Documentation
 
-The server provides these tools for agent coordination:
+| Document | Description |
+|----------|-------------|
+| [DEPLOYMENT.md](./DEPLOYMENT.md) | Docker, Docker Compose, systemd deployment |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | Development setup, code quality, project structure |
+| [MCP.md](./MCP.md) | MCP tools reference (auto-generated) |
+| [FAQ.md](./FAQ.md) | Frequently asked questions |
 
-- `join-swarm` - Register an agent in the swarm
-- `poll-task` - Poll for assigned tasks (worker agents)
-- `send-task` - Assign a task to an agent (lead agent)
-- `get-swarm` - List all agents in the swarm
-- `get-tasks` - List tasks filtered by status
-- `get-task-details` - Get detailed info about a task
-- `store-progress` - Update task progress or mark complete/failed
-- `my-agent-info` - Get current agent's info
+---
 
 ## License
 
-MIT License, 2025-2026 (c) desplega.ai
+[MIT License](./LICENSE) - 2025-2026 desplega.ai