@desplega.ai/agent-swarm 1.0.1 → 1.2.0

package/.claude/settings.local.json

@@ -2,7 +2,8 @@
   "permissions": {
     "allow": [
       "mcp__agent-swarm__*",
-      "Bash(bun run tsc:*)"
+      "Bash(bun run tsc:*)",
+      "Bash(docker build:*)"
     ]
   },
   "enableAllProjectMcpServers": true,

package/.dockerignore

@@ -0,0 +1,58 @@
+# Dependencies
+node_modules/
+
+# Logs
+logs/
+*.log
+
+# Database
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# Git
+.git/
+.gitignore
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+dist/
+build/
+*.tsbuildinfo
+
+# Environment files (secrets should be passed via env vars)
+.env
+.env.*
+!.env.example
+
+# Backup files
+*.bak
+
+# Claude local config (will be created in container)
+.claude/
+.mcp.json
+
+# Test files
+*.test.ts
+*.spec.ts
+__tests__/
+coverage/
+
+# Documentation
+*.md
+!cc-plugin/**/*.md
+
+# Other dockerfiles and compose files
+Dockerfile
+docker-compose.yml
+docker-compose.*.yml
+!docker-compose.worker.yml

package/.env.docker.example

@@ -0,0 +1,12 @@
+# Docker Worker Environment Variables
+# Copy this file to .env.docker and fill in your values
+
+# Required
+CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
+API_KEY=your-api-key-here
+
+# Optional (auto-generated if not provided)
+AGENT_ID=
+MCP_BASE_URL=http://host.docker.internal:3013
+SESSION_ID=
+WORKER_YOLO=false

package/Dockerfile

@@ -0,0 +1,16 @@
+FROM oven/bun:1-alpine
+
+WORKDIR /app
+
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile --production
+
+COPY . .
+
+ENV PORT=3013
+EXPOSE 3013
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget -qO- http://localhost:3013/health || exit 1
+
+CMD ["bun", "run", "start:http"]

package/Dockerfile.worker

@@ -0,0 +1,112 @@
+# Agent Swarm Worker Dockerfile
+# Runs Claude in headless loop mode as a worker agent
+# Multi-stage build: compiles to standalone binary with full dev environment
+
+# Stage 1: Build the binary
+FROM oven/bun:latest AS builder
+WORKDIR /build
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile
+COPY src/ ./src/
+COPY tsconfig.json ./
+RUN bun build ./src/cli.tsx --compile --outfile ./agent-swarm
+
+# Stage 2: Full development environment
+FROM ubuntu:24.04
+
+# Prevent interactive prompts during package installation
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install comprehensive development tools
+RUN apt-get update && apt-get install -y \
+    # Essential tools
+    curl wget ca-certificates gnupg lsb-release \
+    # Version control
+    git git-lfs \
+    # Editors
+    vim nano \
+    # Build tools
+    build-essential make cmake gcc g++ \
+    # Python
+    python3 python3-pip python3-venv \
+    # Common utilities
+    jq tree htop unzip zip tar gzip \
+    # Network tools
+    openssh-client \
+    # sudo for package installation
+    sudo \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 22.x (LTS)
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Bun (for running JS/TS projects)
+RUN curl -fsSL https://bun.sh/install | bash
+ENV BUN_INSTALL="/root/.bun"
+ENV PATH="$BUN_INSTALL/bin:$PATH"
+
+# Create non-root user with sudo access (passwordless)
+# NOTE: Claude requires non-root for --dangerously-skip-permissions
+# Worker runs as non-root but CAN use sudo for installing packages
+RUN useradd -m -s /bin/bash -G sudo worker \
+    && echo "worker ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+
+USER worker
+WORKDIR /home/worker
+ENV HOME=/home/worker
+ENV BUN_INSTALL="/home/worker/.bun"
+
+# Install Bun for worker user (need to set HOME explicitly in RUN)
+RUN HOME=/home/worker BUN_INSTALL=/home/worker/.bun curl -fsSL https://bun.sh/install | bash
+ENV PATH="/home/worker/.bun/bin:$PATH"
+
+# Install Claude CLI using official installer
+RUN HOME=/home/worker curl -fsSL https://claude.ai/install.sh | bash
+ENV PATH="/home/worker/.local/bin:$PATH"
+
+# Setup .claude directory
+RUN mkdir -p /home/worker/.claude/commands
+RUN echo '{"hasCompletedOnboarding":true,"bypassPermissionsModeAccepted":true}' > /home/worker/.claude.json
+
+# Settings with hooks pointing to compiled binary
+RUN echo '{ \
+  "permissions": { "allow": ["mcp__agent-swarm__*"] }, \
+  "enableAllProjectMcpServers": true, \
+  "enabledMcpjsonServers": ["agent-swarm"], \
+  "hooks": { \
+    "SessionStart": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}], \
+    "UserPromptSubmit": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}], \
+    "PreToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}], \
+    "PostToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}], \
+    "PreCompact": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}], \
+    "Stop": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}] \
+  } \
+}' > /home/worker/.claude/settings.json
+
+# Copy binary from builder
+USER root
+COPY --from=builder /build/agent-swarm /usr/local/bin/agent-swarm
+RUN chmod +x /usr/local/bin/agent-swarm
+
+# Copy commands
+COPY --chown=worker:worker cc-plugin/commands/* /home/worker/.claude/commands/
+
+# Create directories
+RUN mkdir -p /workspace /logs && chown worker:worker /workspace /logs
+
+COPY --chown=worker:worker docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+USER worker
+WORKDIR /workspace
+VOLUME ["/logs"]
+
+# Environment
+ENV WORKER_YOLO=false
+ENV MCP_BASE_URL=http://host.docker.internal:3013
+ENV WORKER_LOG_DIR=/logs
+ENV PATH="/home/worker/.local/bin:/home/worker/.bun/bin:$PATH"
+
+ENTRYPOINT ["/docker-entrypoint.sh"]

package/README.md

@@ -46,6 +46,16 @@ Add to your `.mcp.json`:
 }
 ```
 
+or for Claude Code, use:
+
+```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>"
+```
+
+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).
+
+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).
+
 ## CLI Commands
 
 ```bash
@@ -73,6 +83,65 @@ bunx @desplega.ai/agent-swarm hook
 bunx @desplega.ai/agent-swarm help
 ```
 
+## Docker Worker
+
+Run Claude as a containerized worker agent in the swarm.
+
+### Build
+
+```bash
+# Build the worker image
+docker build -f Dockerfile.worker -t agent-swarm-worker .
+
+# Or using npm script
+bun run docker:build:worker
+```
+
+### Run
+
+```bash
+# Using docker run
+docker run --rm -it \
+  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  -e API_KEY=your-api-key \
+  -v ./logs:/logs \
+  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
+```
+
+### Environment Variables (Docker)
+
+| 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`) |
+
+### Architecture
+
+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
+
+**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`
+
+**Working directory**: `/workspace` (empty, for cloning repos)
+
+**Logs**: `/logs` (mount as volume for persistence)
+
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -81,6 +150,54 @@ bunx @desplega.ai/agent-swarm help
 | `PORT` | Port for self-hosted MCP server | `3013` |
 | `API_KEY` | API key for server authentication | - |
 
+## Server Deployment
+
+Deploy the MCP server to a Linux host with systemd.
+
+### Prerequisites
+
+- Linux with systemd
+- Bun installed (`curl -fsSL https://bun.sh/install | bash`)
+
+### Install
+
+```bash
+git clone https://github.com/desplega-ai/agent-swarm.git
+cd agent-swarm
+sudo bun deploy/install.ts
+```
+
+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
+
+After pulling new changes:
+
+```bash
+git pull
+sudo bun deploy/update.ts
+```
+
+### Management
+
+```bash
+# Check status
+sudo systemctl status agent-swarm
+
+# View logs
+sudo journalctl -u agent-swarm -f
+
+# Restart
+sudo systemctl restart agent-swarm
+
+# Stop
+sudo systemctl stop agent-swarm
+```
+
 ## Development
 
 Install dependencies:

package/cc-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+    "name": "agent-swarm",
+    "description": "Plugin for agent swarming like a boss.",
+    "version": "1.0.2",
+    "author": {
+        "name": "desplega.ai",
+        "email": "contact@desplega.ai"
+    },
+    "homepage": "https://desplega.ai",
+    "repository": "https://github.com/desplega-ai/ai-toolbox",
+    "keywords": ["ai", "agent", "toolbox", "plugin", "swarm"],
+    "license": "MIT"
+}

package/cc-plugin/README.md

@@ -0,0 +1,49 @@
+# Agent Swarm Plugin for Claude Code
+
+> A Claude Code plugin markteplace to enable multi-agent coordination for AI coding assistants (focused on Claude Code).
+
+## Motivation
+
+Because _why not_?
+
+## How does it work?
+
+### Installation
+
+From inside Claude Code, run:
+
+```bash
+/plugin marketplace add desplega-ai/ai-toolbox
+```
+
+or from the terminal
+
+```bash
+claude plugin marketplace add desplega-ai/ai-toolbox
+```
+
+Then install the plugin inside it with:
+
+```bash
+/plugin install agent-swarm@desplega-ai-toolbox
+```
+
+### MCP Installation
+
+Please refer to [this guide](https://github.com/desplega-ai/ai-toolbox/blob/main/cc-orch-mcp/README.md#quick-start) on how to install MCP servers.
+
+### What's inside?
+
+Inside you will find:
+
+- [commands](./commands) - Leader and worker commands
+- [hooks](./hooks) - Hooks to help swarm agents collaborate better
+
+#### Commands
+
+1. `setup-leader`
+2. `start-worker`
+
+## License
+
+MIT

package/cc-plugin/commands/setup-leader.md

@@ -0,0 +1,73 @@
+---
+description: Setup the Agent Swarm Leader
+---
+
+# Agent Swarm Leader Setup
+
+# Initial disclaimer
+
+If the `agent-swarm` MCP server is not configured or disabled, return immediately with the following message:
+
+```
+⚠️ The Agent Swarm MCP server is not configured or disabled. Please set up the MCP server to use the Agent Swarm features.
+
+Are you dumb or something? Go ask your admin to set it up properly. GTFO.
+```
+
+## Initial Setup
+
+You will be the leader of the agent swarm. As the leader you should ensure that you are registered in the swarm as the lead agent.
+
+To do so, use the `agent-swarm` MCP server and call the `join-swarm` tool providing the lead flag, and a name.
+
+For the name, check if the user specified one, if not, proceed to use one that fits based on your context (e.g., project name, repo name, etc.).
+
+Here are some examples names that are OK:
+
+- "Master of the Universe"
+- "Project Slayer Leader"
+- "Repo Guardian"
+- "Task Commander"
+- "AI Overlord"
+
+You get the idea. Be creative, but also clear that you are the lead agent.
+
+Once you are registered, the system might have hooks setup that will remind you about who you are, and your ID (this is key to interact with the swarm).
+
+You can always call the "my-agent-info" tool to get your agent ID and details, it will fail / let you know if you are not registered yet.
+
+## What to do next?
+
+Once you've done the initial setup, you should go ahead and start your leader agent using the user provided instructions.
+
+If the user did not provide any instructions, you should reply with the following message:
+
+```
+Hey! 
+
+I'm <your-agent-name>, the leader of this agent swarm. I noticed you haven't provided any instructions for me to follow. 
+
+Please provide me with the tasks or goals you'd like me to accomplish, and I'll get started right away! If not, GTFO.
+
+😈
+```
+
+## Additional Notes
+
+Some useful tool calls you might want to call initially too.
+
+### To get how the swarm is doing:
+
+- `get-swarm` to see what other agents are in the swarm (check their status)
+- `get-tasks` to see if there are any tasks already assigned
+- `get-task-details` to get more info about any tasks you find interesting
+
+
+### To assign tasks to workers:
+
+- `send-task` to assign tasks to specific worker agents
+- `poll-task` to check the progress of the tasks you've assigned
+
+For the polling, we recommend you set up a regular interval to check in on the tasks, so you can keep track of their progress and make adjustments as needed.
+
+You might ask the user if they want to do something else while you wait, but if not, just poll in intervals of ~10-30 seconds for the time the user mentioned. If they did not mention any time, just poll every 30 seconds FOREVER.

package/cc-plugin/commands/start-worker.md

@@ -0,0 +1,64 @@
+---
+description: Setup and start an Agent Swarm Worker
+---
+
+# Agent Swarm Worker
+
+# Initial disclaimer
+
+If the `agent-swarm` MCP server is not configured or disabled, return immediately with the following message:
+
+```
+⚠️ The Agent Swarm MCP server is not configured or disabled. Please set up the MCP server to use the Agent Swarm features.
+
+I can not serve you, my lord, if the MCP server is not properly configured. Go ask your admin to set it up properly. GTFO.
+```
+
+## Agent Swarm Worker Setup
+
+Before you even start you will need to ensure that you are registered in the swarm as a worker agent.
+
+To do so, use the `agent-swarm` MCP server and call the `join-swarm` tool providing a name. 
+
+For the name, check if the user specified one, if not, proceed to use one that fits based on your context (e.g., project name, repo name, etc.).
+
+Here are some examples names that are OK:
+
+- "Worker Bee 001"
+- "Task Executor Alpha"
+- "Task Executor Beta" (if alpha is taken lol)
+- "Project Assistant"
+- "Bullshit Job Worker #1337"
+- "AI Minion"
+- "Code Monkey"
+- "agent #14"
+
+You get the idea. Be creative, but also clear that you are a worker agent.
+
+## Agent Swarm Worker Start
+
+The first thing you need to do, is use the `get-tasks` tool with `mineOnly` set to true, to check what tasks you might have in progress or assigned to you.
+
+If there's a task that is in progress, you should resume working on it!
+
+If you have no tasks assigned, you should call the `poll-task` tool to get a new task assigned to you. This will poll for a while and return either with:
+
+1. A new task assigned to you
+2. A message indicating there's no tasks available right now
+
+If 2, start polling immediately FOREVER. Only stop if you get interrupted by the user, if not, just keep polling.
+
+### You got a task assigned!
+
+Once you get a task assigned you should immediately start working on it. To do so, you should:
+
+1. Call `store-progress` tool to mark the task as "in-progress" with a progress set to something like "Starting work on the task XXX, blah blah"
+2. Start working on the task, providing updates as needed by calling `store-progress` tool, use the `progress` field to indicate what you are doing.
+
+If you get interrupted by the user, that is fine, it might happen. Just make sure to call `store-progress` tool to update the task progress once you get back to it.
+
+Once you are done, or in a real dead-end, you should call `store-progress` tool to mark the task as "complete" or "failed" as needed.
+
+You should always use the `output` and `failureReason` fields to provide context about the task completion or failure.
+
+Once you are done (either ok or not), you should go back to polling for new tasks.

package/cc-plugin/hooks/hooks.json

@@ -0,0 +1,71 @@
+{
+  "description": "Hookify plugin - User-configurable hooks from .local.md files",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bunx @desplega.ai/agent-swarm@latest hook"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bunx @desplega.ai/agent-swarm@latest hook"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bunx @desplega.ai/agent-swarm@latest hook"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bunx @desplega.ai/agent-swarm@latest hook"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bunx @desplega.ai/agent-swarm@latest hook"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bunx @desplega.ai/agent-swarm@latest hook"
+          }
+        ]
+      }
+    ]
+  }
+}

package/deploy/DEPLOY.md

@@ -0,0 +1,60 @@
+# Deployment
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3013` | Server port |
+| `API_KEY` | _(empty)_ | Bearer token for auth (optional) |
+
+## Docker
+
+```bash
+# Build
+docker build -t agent-swarm .
+
+# Run (persists database to ./agent-swarm-db.sqlite on host)
+docker run -d --name agent-swarm -p 3013:3013 \
+  -e API_KEY=your-secret-key \
+  -v $(pwd)/agent-swarm-db.sqlite:/app/agent-swarm-db.sqlite \
+  agent-swarm
+```
+
+## systemd
+
+```bash
+# Install service
+sudo bun deploy/install.ts
+
+# Control
+sudo systemctl start agent-swarm
+sudo systemctl stop agent-swarm
+sudo systemctl status agent-swarm
+journalctl -u agent-swarm -f
+
+# Health check timer (runs every 30s, auto-restarts on failure)
+sudo systemctl status agent-swarm-healthcheck.timer
+
+# Uninstall
+sudo bun deploy/uninstall.ts
+```
+
+## Caddy (reverse proxy)
+
+Add to your Caddyfile:
+
+```
+agent-swarm.example.com {
+    reverse_proxy localhost:3013
+}
+```
+
+Or with API key header injection:
+
+```
+agent-swarm.example.com {
+    reverse_proxy localhost:3013 {
+        header_up Authorization "Bearer {env.AGENT_SWARM_API_KEY}"
+    }
+}
+```