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