Agent Swarm

┌─────────────────────────────────────────────────────────────────────┐
│                         Source Providers                             │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐    │
│  │ GitHub Issues│  │Linear Tickets│  │  Machine Queue (Spore) │    │
│  │ (webhook +   │  │ (GraphQL     │  │  (Supabase polling)    │    │
│  │  polling)    │  │  polling)    │  │                        │    │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬─────────────┘   │
└─────────┼─────────────────┼────────────────────── ┼────────────────┘
          │                 │                        │
          ▼                 ▼                        ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      swarm-daemon (services/)                        │
│                                                                      │
│  ┌─────────────────┐     ┌──────────────────────────────────────┐   │
│  │ webhook-server  │     │           orchestrator.ts            │   │
│  │ :9300           │────▶│  1. List queued work items           │   │
│  └─────────────────┘     │  2. selectAgent() (label/load)       │   │
│                           │  3. WorkspaceManager.create()        │   │
│  ┌─────────────────┐     │  4. OrbitBridge.enrich()             │   │
│  │ api-server      │     │  5. PromptRenderer.render()          │   │
│  │ :9301           │     │  6. AgentAdapter.startSession()       │   │
│  └─────────────────┘     │  7. Stream AgentEvents               │   │
│                           │  8. Transition state + notify        │   │
│  ┌─────────────────┐     └──────────────────────────────────────┘   │
│  │ metrics         │                       │                         │
│  │ :9302           │                       │                         │
│  └─────────────────┘                       ▼                         │
└────────────────────────────────────────────┼────────────────────────┘
                                             │
          ┌────────────────┬─────────────────┼─────────────────┐
          ▼                ▼                 ▼                   ▼
   ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
   │  Supabase   │  │ Agent CLI    │  │   Discord    │  │  NUMU Bus    │
   │ State + FSM │  │ Claude/Codex │  │ Notifications│  │ :7890 Events │
   │ Audit trail │  │ /Gemini/SSH  │  │              │  │              │
   └─────────────┘  └──────────────┘  └──────────────┘  └──────────────┘

queued ──▶ preparing ──▶ running ──┬──▶ succeeded ✓
   └──▶ cancelled ✗          ├──▶ failed ✗
                              ├──▶ retrying ──▶ running
                              └──▶ waiting_approval ──▶ running

GitHub Issue opened
        │
        ▼
webhook-server (:9300)
   HMAC verify → SourceProvider.handleWebhook()
        │
        ▼
WorkItem normalized (externalId, title, description, labels, git info)
        │
        ▼
SupabaseStore.create() → status: "queued"
        │
        ▼
Dispatch loop (every 30s)
   listByStatus("queued")
   selectAgent() ──► label hint? → metadata pref? → load balance
        │
        ▼
WorkspaceManager.createForIssue()
   mkdir [home-path]
   git clone --depth=1 <repo>
        │
        ▼
OrbitBridge.enrich() → inject project context
        │
        ▼
PromptRenderer.render(workflow, issue)
   pick template by labels (feature-impl.md, bug-fix.md, ios-build.md…)
   Liquid render with issue variables
        │
        ▼
AgentAdapter.startSession({ cwd, model, approvalMode, prompt })
   spawn: claude --dangerously-skip-permissions --output-format stream-json
        │
        ▼
Stream AgentEvents:
   text_delta → accumulate
   tool_start / tool_result → log
   approval_request → auto-approve or pause
   session_end
        │
        ▼
SupabaseStore.transition("running" → "succeeded" | "failed")
SourceProvider.updateStatus() → GitHub label, Linear status
Discord.postCompletion()
NUMUBridge.publish("swarm.task.complete", { ... })
WorkspaceManager.scheduleCleanup(hours)

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

# Via Supabase CLI
supabase db push --db-url "postgresql://..."

# Or manually in the Supabase SQL editor
cat migrations/001_swarm_work_items.sql | supabase sql

cp .env.example .env

# Development (with hot reload)
bun run dev

# Production
bun build services/swarm-daemon/src/index.ts --outdir dist --target bun
bun dist/index.js

https://your-host:9300/webhooks/github

curl -X POST http://localhost:9301/work-items \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refactor auth module",
    "description": "Clean up the JWT validation logic in src/auth/",
    "source": "manual",
    "labels": ["refactor"],
    "gitRepoUrl": "https://github.com/Diomandeee/myapp",
    "gitBranch": "main"
  }'

# List all running tasks
curl http://localhost:9301/work-items?status=running

# Get Prometheus metrics
curl http://localhost:9301/metrics

# Check a specific item
curl http://localhost:9301/work-items/<uuid>

[
  {
    "id": "uuid",
    "title": "Fix login bug",
    "status": "running",
    "agentKind": "claude",
    "source": "github",
    "externalId": "123",
    "url": "https://github.com/...",
    "createdAt": "2026-03-17T10:00:00Z",
    "updatedAt": "2026-03-17T10:05:00Z"
  }
]

{
  "title": "string (required)",
  "description": "string",
  "source": "manual",
  "labels": ["string"],
  "agentKind": "claude | codex | gemini",
  "gitRepoUrl": "string",
  "gitBranch": "string",
  "priority": 0,
  "metadata": {}
}

{ "status": "cancelled" }

---
name: My Custom Task
agent: claude
approval_mode: auto-all
max_retries: 2
timeout_seconds: 900
labels: [my-label]
---

# Task: {{ issue.title }}

## Context
Repository: {{ issue.gitRepoUrl }}
Branch: {{ issue.gitBranch | default: "main" }}
Workspace: {{ workspace.path }}

## Issue Description
{{ issue.description }}

{% if issue.labels %}
## Labels
{{ issue.labels | join: ", " }}
{% endif %}

## Instructions
1. Read the codebase in {{ workspace.path }}
2. Implement the requested changes
3. Ensure all tests pass
4. Create a summary of changes made

CREATE TABLE swarm_work_items (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  external_id     TEXT,                    -- GitHub issue number, Linear ID
  identifier      TEXT UNIQUE,             -- e.g. "github/Diomandeee/myapp/123"
  title           TEXT NOT NULL,
  description     TEXT,
  source_kind     TEXT NOT NULL,           -- "github" | "linear" | "manual" | "machine_queue"
  project         TEXT,
  priority        INTEGER DEFAULT 0,
  labels          TEXT[] DEFAULT '{}',
  status          TEXT NOT NULL DEFAULT 'queued',
  agent_kind      TEXT,                    -- "claude" | "codex" | "gemini"
  session_id      TEXT,
  workspace_path  TEXT,
  retry_count     INTEGER DEFAULT 0,
  max_retries     INTEGER DEFAULT 3,
  git_repo_url    TEXT,
  git_branch      TEXT DEFAULT 'main',
  url             TEXT,
  metadata        JSONB DEFAULT '{}',
  created_at      TIMESTAMPTZ DEFAULT now(),
  updated_at      TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE swarm_transitions (
  id              BIGSERIAL PRIMARY KEY,
  work_item_id    UUID NOT NULL REFERENCES swarm_work_items(id),
  from_status     TEXT NOT NULL,
  to_status       TEXT NOT NULL,
  event_type      TEXT NOT NULL,
  event_data      JSONB DEFAULT '{}',
  created_at      TIMESTAMPTZ DEFAULT now()
);

agent-swarm/
├── migrations/              # Supabase DDL (apply once)
├── packages/
│   ├── agent-adapters/      # Claude/Codex/Gemini/SSH adapter interfaces
│   ├── discord/             # Notification formatting
│   ├── logger/              # Structured logger
│   ├── metrics/             # Prometheus client
│   ├── numu-bridge/         # NUMU Bus WebSocket client
│   ├── orbit-bridge/        # Orbit context enrichment
│   ├── prompt-renderer/     # Liquid template engine
│   ├── source-providers/    # GitHub + Linear + Machine Queue
│   ├── state-machine/       # FSM + Supabase store
│   └── workspace-manager/   # Git workspace isolation
├── services/
│   └── swarm-daemon/
│       └── src/
│           ├── index.ts         # Bootstrap (servers + loops)
│           ├── orchestrator.ts  # Core dispatch loop
│           ├── dispatch.ts      # Agent selection logic
│           ├── api-server.ts    # REST API + metrics
│           ├── webhook-server.ts# GitHub/Linear receiver
│           └── config.ts        # Zod-validated config
├── workflows/               # 13 Liquid task templates
├── .env.example
└── package.json             # Bun workspaces manifest

# Install all workspace dependencies
bun install

# Run daemon with hot reload
bun run dev

# Type check across all packages
bunx tsc --noEmit

# Run tests
bun test

# Build production binary
bun build services/swarm-daemon/src/index.ts --outdir dist --target bun

# Lint
bunx eslint packages/ services/

   export interface SourceProvider {
     initialize(): Promise<void>
     poll?(): Promise<SourceEvent[]>
     handleWebhook?(payload: unknown, headers: Headers): Promise<SourceEvent[]>
     updateStatus(item: StoredWorkItem, status: WorkItemStatus): Promise<void>
     postComment(item: StoredWorkItem, body: string): Promise<void>
     getWorkItem(externalId: string): Promise<WorkItem | null>
   }

   export interface AgentAdapter {
     startSession(config: SessionConfig): Promise<string>
     sendPrompt(sessionId: string, prompt: string): AsyncIterableIterator<AgentEvent>
     respondToApproval(sessionId: string, approved: boolean): Promise<void>
     interrupt(sessionId: string): Promise<void>
     endSession(sessionId: string): Promise<void>
     isAlive(sessionId: string): boolean
     shutdown(): Promise<void>
   }

# Load
launchctl load [home-path]

# Status
launchctl list | grep swarm

# Logs
tail -f [home-path]