SwarmSDK, SwarmCLI & SwarmMemory

A Ruby framework for orchestrating multiple AI agents as a collaborative team with persistent memory.

SwarmSDK is a complete redesign of Claude Swarm that provides a better developer experience and is geared towards general-purpose agentic systems.

✨ Key Features

• 🚀 Decoupled from Claude Code: No more dependency on Claude Code
• ⚡ Single Process Architecture: All agents run in one Ruby process using RubyLLM - no more managing multiple processes
• 🎯 More Efficient: Direct method calls instead of MCP inter-process communication
• 🔧 Richer Features: Node workflows, hooks system, scratchpad/memory tools, and more
• 🎮 Better Control: Fine-grained permissions, cost tracking, structured logging
• 💻 Interactive REPL: Built with TTY toolkit for a nice command-line experience
• 🌐 Multiple LLM Providers: Supports all LLM providers supported by RubyLLM (Claude, OpenAI, Gemini, etc.)
• 🧠 SwarmMemory: Persistent agent knowledge storage with semantic search and FAISS indexing
• 🔌 Plugin System: Extensible architecture for custom integrations

---

🚀 Quick Start

Installation

gem install swarm_cli     # Includes swarm_sdk
swarm --help              # Explore the modern CLI

Your First Swarm

Create a simple swarm configuration file my_swarm.yml:

version: 2
agents:
  lead:
    model: claude-3-5-sonnet-20241022
    role: "Lead developer coordinating development efforts"
    tools:
      - Read
      - Write
      - Edit
      - Bash
    delegates_to:
      - frontend
      - backend

  frontend:
    model: claude-3-5-sonnet-20241022
    role: "Frontend specialist handling UI and user experience"
    tools: [Read, Write, Edit]

  backend:
    model: claude-3-5-sonnet-20241022
    role: "Backend developer managing APIs and data layer"
    tools: [Read, Write, Edit, Bash]

Run it:

# Interactive REPL mode
swarm run my_swarm.yml

# Or with a specific prompt
swarm run my_swarm.yml -p "Build a simple TODO app with React and Node.js"

---

📚 Documentation

Complete documentation is available in the docs/v2 directory.

Getting Started

• Getting Started with SwarmSDK ⭐ Learn the basics: installation, core concepts, your first swarm (YAML & Ruby DSL)

• Getting Started with SwarmCLI ⭐ Command-line interface: interactive REPL and automation modes

Comprehensive Tutorial

• SwarmSDK Complete Tutorial In-depth guide covering every feature:
  • Part 1: Fundamentals (agents, models, tools)
  • Part 2: Tools & Permissions (all 11 tools, path/command permissions)
  • Part 3: Agent Collaboration (delegation patterns)
  • Part 4: Hooks System (all 12 events, 6 actions)
  • Part 5: Node Workflows (multi-stage pipelines, transformers)
  • Part 6: Advanced Configuration (MCP, providers, context management)
  • Part 7: Production Features (logging, cost tracking, error handling)
  • Part 8: Best Practices (architecture, testing, optimization)

Reference Documentation

• Architecture Flow Diagram - Complete system architecture
• Execution Flow Diagram - Runtime execution journey (21 detailed steps)
• CLI Reference - Complete command-line reference
• Ruby DSL Reference - Complete programmatic API
• YAML Configuration Reference - Complete YAML structure

Integration Guides

• SwarmMemory Guide - Persistent agent knowledge with semantic search
• Plugin System Guide - Build extensions for SwarmSDK
• Memory Adapter Development - Custom storage backends
• Rails Integration Guide - Integrate with Ruby on Rails

---

💡 Core Concepts

SwarmSDK

A Ruby framework for orchestrating multiple AI agents that work together as a team. Each agent has:

• Role: Specialized expertise (backend developer, code reviewer, etc.)
• Tools: Capabilities (Read files, Write files, Run bash commands, etc.)
• Delegation: Ability to delegate subtasks to other agents
• Hooks: Custom logic that runs at key points in execution

SwarmCLI

A command-line interface for running SwarmSDK swarms with two modes:

• Interactive (REPL): Conversational interface for exploration and iteration
• Non-Interactive: One-shot execution perfect for automation and scripting

SwarmMemory

A persistent memory system for agents with semantic search capabilities:

• Storage: Hierarchical knowledge organization (concept, fact, skill, experience)
• Semantic Search: FAISS-based vector similarity with local ONNX embeddings
• Memory Tools: 9 tools for writing, reading, editing, and searching knowledge
• LoadSkill: Dynamic tool swapping based on semantic skill discovery
• Plugin Architecture: Integrates seamlessly via SwarmSDK plugin system

Configuration Formats

• YAML: Declarative, easy to read, great for shell-based hooks
• Ruby DSL: Programmatic, dynamic, full Ruby power, IDE support

---

🎯 Example: Code Review Team

version: 2
agents:
  lead_reviewer:
    model: claude-3-5-sonnet-20241022
    role: "Lead code reviewer ensuring quality and best practices"
    tools: [Read, Write]
    delegates_to: [security_expert, performance_analyst]
    hooks:
      on_user_message:
        - run: "git diff main..HEAD > /tmp/changes.diff"
          append_output_to_context: true

  security_expert:
    model: claude-3-5-sonnet-20241022
    role: "Security specialist checking for vulnerabilities"
    tools: [Read]
    hooks:
      on_user_message:
        - run: "semgrep --config=auto --json"
          append_output_to_context: true

  performance_analyst:
    model: claude-3-5-sonnet-20241022
    role: "Performance analyst identifying bottlenecks"
    tools: [Read, Bash]

Run the code review:

swarm run code_review.yml -p "Review the recent changes in the authentication module"

---

🧠 SwarmMemory Example

Enable persistent memory for your agents:

gem install swarm_memory

version: 2
agents:
  research_assistant:
    model: claude-3-5-sonnet-20241022
    role: "Research assistant with long-term memory"
    tools: [Read, Write]
    plugins:
      - swarm_memory:
          storage_dir: ./memories

The agent now has access to memory tools:

• MemoryWrite - Store new knowledge
• MemoryRead - Retrieve specific memories
• MemorySearch - Semantic search across all knowledge
• LoadSkill - Dynamically load specialized skills
• And more...

Learn more about SwarmMemory →

---

🔧 Ruby DSL Example

For programmatic control, use the Ruby DSL:

require 'swarm_sdk'

swarm = SwarmSDK.build do
  agent :lead do
    model "claude-3-5-sonnet-20241022"
    role "Lead developer"
    tools :Read, :Write, :Edit, :Bash
    delegates_to :frontend, :backend
  end

  agent :frontend do
    model "claude-3-5-sonnet-20241022"
    role "Frontend specialist"
    tools :Read, :Write, :Edit
  end

  agent :backend do
    model "claude-3-5-sonnet-20241022"
    role "Backend specialist"
    tools :Read, :Write, :Edit, :Bash
  end
end

# Execute with the lead agent
result = swarm.execute(
  agent: :lead,
  prompt: "Build a simple TODO app"
)

puts result.message

Learn more about the Ruby DSL →

---

🛠️ Advanced Features

Node Workflows

Build multi-stage processing pipelines:

version: 2
nodes:
  analyzer:
    agent: code_analyst
    prompt: "Analyze the codebase and identify issues"

  fixer:
    agent: code_fixer
    prompt: "Fix the issues identified: {{ analyzer.output }}"
    depends_on: [analyzer]

  reviewer:
    agent: code_reviewer
    prompt: "Review the fixes: {{ fixer.output }}"
    depends_on: [fixer]

agents:
  code_analyst:
    model: claude-3-5-sonnet-20241022
    role: "Code analyst"
    tools: [Read]

  code_fixer:
    model: claude-3-5-sonnet-20241022
    role: "Code fixer"
    tools: [Read, Write, Edit]

  code_reviewer:
    model: claude-3-5-sonnet-20241022
    role: "Code reviewer"
    tools: [Read]

Learn more about Node Workflows →

Hooks System

Run custom logic at key execution points:

version: 2
agents:
  developer:
    model: claude-3-5-sonnet-20241022
    role: "Full-stack developer"
    tools: [Read, Write, Edit, Bash]
    hooks:
      # Run before each tool execution
      on_pre_tool:
        - run: "echo 'About to use {{ tool_name }}'"

      # Run after successful tool execution
      on_post_tool:
        - run: "echo 'Tool {{ tool_name }} completed successfully'"

      # Append git diff to every user message
      on_user_message:
        - run: "git diff"
          append_output_to_context: true

      # Run tests before the agent responds
      on_pre_response:
        - run: "npm test"
          stop_on_error: true

Learn more about Hooks →

---

📊 Cost Tracking & Logging

SwarmSDK provides built-in cost tracking and structure