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.

• 🚀 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

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

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"

Complete documentation is available in the docs/v2 directory.

• 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

• 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)

• 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

• 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

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

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

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

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

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"

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 →

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 →

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 →

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 →

SwarmSDK provides built-in cost tracking and structured logging:

require 'swarm_sdk'

swarm = SwarmSDK.load('my_swarm.yml')

result = swarm.execute(
  agent: :lead,
  prompt: "Build a simple TODO app",
  logger: Logger.new($stdout)
)

# Access cost information
puts "Total cost: $#{result.cost}"
puts "Tokens used: #{result.tokens}"

Learn more about Production Features →

# app/jobs/code_review_job.rb
class CodeReviewJob < ApplicationJob
  def perform(pull_request_id)
    swarm = SwarmSDK.load(Rails.root.join('config', 'code_review_swarm.yml'))

    result = swarm.execute(
      agent: :lead_reviewer,
      prompt: "Review PR ##{pull_request_id}"
    )

    PullRequest.find(pull_request_id).update(
      review_status: 'completed',
      review_comments: result.message
    )
  end
end

Learn more about Rails Integration →

# lib/my_plugin.rb
class MyPlugin < SwarmSDK::Plugin
  def on_agent_init(agent)
    # Add custom behavior when agent initializes
  end

  def on_user_message(message, agent)
    # Process user messages
  end

  def provide_tools
    [MyCustomTool.new]
  end
end

# Register the plugin
SwarmSDK.register_plugin(:my_plugin, MyPlugin)

Learn more about Plugins →

Claude Swarm (v1) continues to be maintained and is still a great choice if you prefer the multi-process architecture with Claude Code instances.

View Claude Swarm v1 Documentation →

To install Claude Swarm v1:

gem install claude_swarm

Bug reports and pull requests are welcome on GitHub at https://github.com/parruda/claude-swarm.

1. Fork the repository
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

The gems are available as open source under the terms of the MIT License.

• Documentation: docs/v2/README.md
• GitHub Repository: parruda/claude-swarm
• RubyGems:
  • swarm_sdk
  • swarm_cli
  • swarm_memory
• Issues & Support: GitHub Issues

Ready to get started? → Getting Started with SwarmSDK or Getting Started with SwarmCLI