{"id":32614627,"url":"https://github.com/parruda/swarm","last_synced_at":"2026-04-10T10:02:21.884Z","repository":{"id":296022995,"uuid":"989749540","full_name":"parruda/swarm","owner":"parruda","description":"Ruby gems for general-purpose AI agent systems: automation, research, data processing, customer support, content creation. SwarmSDK provides single-process orchestration, persistent memory with semantic   search, node workflows, and hooks. SwarmMemory/SwarmCLI included. Claude Swarm v1 for dev teams.","archived":false,"fork":false,"pushed_at":"2026-02-17T02:07:40.000Z","size":8413,"stargazers_count":1683,"open_issues_count":12,"forks_count":123,"subscribers_count":17,"default_branch":"main","last_synced_at":"2026-03-19T14:28:26.566Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parruda.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.claude-swarm.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-24T18:42:36.000Z","updated_at":"2026-03-19T06:43:12.000Z","dependencies_parsed_at":"2025-06-11T22:29:33.289Z","dependency_job_id":"750b2877-d6b1-40b6-9993-0eb92092851a","html_url":"https://github.com/parruda/swarm","commit_stats":null,"previous_names":["parruda/claude-swarm","parruda/swarm"],"tags_count":120,"template":false,"template_full_name":null,"purl":"pkg:github/parruda/swarm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parruda%2Fswarm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parruda%2Fswarm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parruda%2Fswarm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parruda%2Fswarm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parruda","download_url":"https://codeload.github.com/parruda/swarm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parruda%2Fswarm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31637748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-30T16:00:46.247Z","updated_at":"2026-04-10T10:02:21.878Z","avatar_url":"https://github.com/parruda.png","language":"Ruby","readme":"# SwarmSDK, SwarmCLI \u0026 SwarmMemory\n\n[![Gem Version](https://badge.fury.io/rb/swarm_sdk.svg)](https://badge.fury.io/rb/swarm_sdk)\n[![Gem Version](https://badge.fury.io/rb/swarm_cli.svg)](https://badge.fury.io/rb/swarm_cli)\n[![Gem Version](https://badge.fury.io/rb/swarm_memory.svg)](https://badge.fury.io/rb/swarm_memory)\n[![CI](https://github.com/parruda/claude-swarm/actions/workflows/ci.yml/badge.svg)](https://github.com/parruda/claude-swarm/actions/workflows/ci.yml)\n\n**A Ruby framework for orchestrating multiple AI agents as a collaborative team with persistent memory.**\n\nSwarmSDK is a complete redesign of Claude Swarm that provides a better developer experience and is geared towards general-purpose agentic systems.\n\n## ✨ Key Features\n\n- **🚀 Decoupled from Claude Code**: No more dependency on Claude Code\n- **⚡ Single Process Architecture**: All agents run in one Ruby process using [RubyLLM](https://github.com/parruda/ruby_llm) - no more managing multiple processes\n- **🎯 More Efficient**: Direct method calls instead of MCP inter-process communication\n- **🔧 Richer Features**: Node workflows, hooks system, scratchpad/memory tools, and more\n- **🎮 Better Control**: Fine-grained permissions, cost tracking, structured logging\n- **💻 Interactive REPL**: Built with TTY toolkit for a nice command-line experience\n- **🌐 Multiple LLM Providers**: Supports all LLM providers supported by RubyLLM (Claude, OpenAI, Gemini, etc.)\n- **🧠 SwarmMemory**: Persistent agent knowledge storage with semantic search and FAISS indexing\n- **🔌 Plugin System**: Extensible architecture for custom integrations\n\n---\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\ngem install swarm_cli     # Includes swarm_sdk\nswarm --help              # Explore the modern CLI\n```\n\n### Your First Swarm\n\nCreate a simple swarm configuration file `my_swarm.yml`:\n\n```yaml\nversion: 2\nagents:\n  lead:\n    model: claude-3-5-sonnet-20241022\n    role: \"Lead developer coordinating development efforts\"\n    tools:\n      - Read\n      - Write\n      - Edit\n      - Bash\n    delegates_to:\n      - frontend\n      - backend\n\n  frontend:\n    model: claude-3-5-sonnet-20241022\n    role: \"Frontend specialist handling UI and user experience\"\n    tools: [Read, Write, Edit]\n\n  backend:\n    model: claude-3-5-sonnet-20241022\n    role: \"Backend developer managing APIs and data layer\"\n    tools: [Read, Write, Edit, Bash]\n```\n\nRun it:\n\n```bash\n# Interactive REPL mode\nswarm run my_swarm.yml\n\n# Or with a specific prompt\nswarm run my_swarm.yml -p \"Build a simple TODO app with React and Node.js\"\n```\n\n---\n\n## 📚 Documentation\n\n**Complete documentation is available in the [docs/v2](docs/v2/README.md) directory.**\n\n### Getting Started\n\n- **[Getting Started with SwarmSDK](docs/v2/guides/getting-started.md)** ⭐\n  Learn the basics: installation, core concepts, your first swarm (YAML \u0026 Ruby DSL)\n\n- **[Getting Started with SwarmCLI](docs/v2/guides/quick-start-cli.md)** ⭐\n  Command-line interface: interactive REPL and automation modes\n\n### Comprehensive Tutorial\n\n- **[SwarmSDK Complete Tutorial](docs/v2/guides/complete-tutorial.md)**\n  In-depth guide covering every feature:\n  - Part 1: Fundamentals (agents, models, tools)\n  - Part 2: Tools \u0026 Permissions (all 11 tools, path/command permissions)\n  - Part 3: Agent Collaboration (delegation patterns)\n  - Part 4: Hooks System (all 12 events, 6 actions)\n  - Part 5: Node Workflows (multi-stage pipelines, transformers)\n  - Part 6: Advanced Configuration (MCP, providers, context management)\n  - Part 7: Production Features (logging, cost tracking, error handling)\n  - Part 8: Best Practices (architecture, testing, optimization)\n\n### Reference Documentation\n\n- **[Architecture Flow Diagram](docs/v2/reference/architecture-flow.md)** - Complete system architecture\n- **[Execution Flow Diagram](docs/v2/reference/execution-flow.md)** - Runtime execution journey (21 detailed steps)\n- **[CLI Reference](docs/v2/reference/cli.md)** - Complete command-line reference\n- **[Ruby DSL Reference](docs/v2/reference/ruby-dsl.md)** - Complete programmatic API\n- **[YAML Configuration Reference](docs/v2/reference/yaml.md)** - Complete YAML structure\n\n### Integration Guides\n\n- **[SwarmMemory Guide](docs/v2/guides/swarm-memory.md)** - Persistent agent knowledge with semantic search\n- **[Plugin System Guide](docs/v2/guides/plugins.md)** - Build extensions for SwarmSDK\n- **[Memory Adapter Development](docs/v2/guides/memory-adapters.md)** - Custom storage backends\n- **[Rails Integration Guide](docs/v2/guides/rails-integration.md)** - Integrate with Ruby on Rails\n\n---\n\n## 💡 Core Concepts\n\n### SwarmSDK\n\nA Ruby framework for orchestrating multiple AI agents that work together as a team. Each agent has:\n\n- **Role**: Specialized expertise (backend developer, code reviewer, etc.)\n- **Tools**: Capabilities (Read files, Write files, Run bash commands, etc.)\n- **Delegation**: Ability to delegate subtasks to other agents\n- **Hooks**: Custom logic that runs at key points in execution\n\n### SwarmCLI\n\nA command-line interface for running SwarmSDK swarms with two modes:\n\n- **Interactive (REPL)**: Conversational interface for exploration and iteration\n- **Non-Interactive**: One-shot execution perfect for automation and scripting\n\n### SwarmMemory\n\nA persistent memory system for agents with semantic search capabilities:\n\n- **Storage**: Hierarchical knowledge organization (concept, fact, skill, experience)\n- **Semantic Search**: FAISS-based vector similarity with local ONNX embeddings\n- **Memory Tools**: 9 tools for writing, reading, editing, and searching knowledge\n- **LoadSkill**: Dynamic tool swapping based on semantic skill discovery\n- **Plugin Architecture**: Integrates seamlessly via SwarmSDK plugin system\n\n### Configuration Formats\n\n- **YAML**: Declarative, easy to read, great for shell-based hooks\n- **Ruby DSL**: Programmatic, dynamic, full Ruby power, IDE support\n\n---\n\n## 🎯 Example: Code Review Team\n\n```yaml\nversion: 2\nagents:\n  lead_reviewer:\n    model: claude-3-5-sonnet-20241022\n    role: \"Lead code reviewer ensuring quality and best practices\"\n    tools: [Read, Write]\n    delegates_to: [security_expert, performance_analyst]\n    hooks:\n      on_user_message:\n        - run: \"git diff main..HEAD \u003e /tmp/changes.diff\"\n          append_output_to_context: true\n\n  security_expert:\n    model: claude-3-5-sonnet-20241022\n    role: \"Security specialist checking for vulnerabilities\"\n    tools: [Read]\n    hooks:\n      on_user_message:\n        - run: \"semgrep --config=auto --json\"\n          append_output_to_context: true\n\n  performance_analyst:\n    model: claude-3-5-sonnet-20241022\n    role: \"Performance analyst identifying bottlenecks\"\n    tools: [Read, Bash]\n```\n\nRun the code review:\n\n```bash\nswarm run code_review.yml -p \"Review the recent changes in the authentication module\"\n```\n\n---\n\n## 🧠 SwarmMemory Example\n\nEnable persistent memory for your agents:\n\n```bash\ngem install swarm_memory\n```\n\n```yaml\nversion: 2\nagents:\n  research_assistant:\n    model: claude-3-5-sonnet-20241022\n    role: \"Research assistant with long-term memory\"\n    tools: [Read, Write]\n    plugins:\n      - swarm_memory:\n          storage_dir: ./memories\n```\n\nThe agent now has access to memory tools:\n\n- `MemoryWrite` - Store new knowledge\n- `MemoryRead` - Retrieve specific memories\n- `MemorySearch` - Semantic search across all knowledge\n- `LoadSkill` - Dynamically load specialized skills\n- And more...\n\n[Learn more about SwarmMemory →](docs/v2/guides/swarm-memory.md)\n\n---\n\n## 🔧 Ruby DSL Example\n\nFor programmatic control, use the Ruby DSL:\n\n```ruby\nrequire 'swarm_sdk'\n\nswarm = SwarmSDK.build do\n  agent :lead do\n    model \"claude-3-5-sonnet-20241022\"\n    role \"Lead developer\"\n    tools :Read, :Write, :Edit, :Bash\n    delegates_to :frontend, :backend\n  end\n\n  agent :frontend do\n    model \"claude-3-5-sonnet-20241022\"\n    role \"Frontend specialist\"\n    tools :Read, :Write, :Edit\n  end\n\n  agent :backend do\n    model \"claude-3-5-sonnet-20241022\"\n    role \"Backend specialist\"\n    tools :Read, :Write, :Edit, :Bash\n  end\nend\n\n# Execute with the lead agent\nresult = swarm.execute(\n  agent: :lead,\n  prompt: \"Build a simple TODO app\"\n)\n\nputs result.message\n```\n\n[Learn more about the Ruby DSL →](docs/v2/reference/ruby-dsl.md)\n\n---\n\n## 🛠️ Advanced Features\n\n### Node Workflows\n\nBuild multi-stage processing pipelines:\n\n```yaml\nversion: 2\nnodes:\n  analyzer:\n    agent: code_analyst\n    prompt: \"Analyze the codebase and identify issues\"\n\n  fixer:\n    agent: code_fixer\n    prompt: \"Fix the issues identified: {{ analyzer.output }}\"\n    depends_on: [analyzer]\n\n  reviewer:\n    agent: code_reviewer\n    prompt: \"Review the fixes: {{ fixer.output }}\"\n    depends_on: [fixer]\n\nagents:\n  code_analyst:\n    model: claude-3-5-sonnet-20241022\n    role: \"Code analyst\"\n    tools: [Read]\n\n  code_fixer:\n    model: claude-3-5-sonnet-20241022\n    role: \"Code fixer\"\n    tools: [Read, Write, Edit]\n\n  code_reviewer:\n    model: claude-3-5-sonnet-20241022\n    role: \"Code reviewer\"\n    tools: [Read]\n```\n\n[Learn more about Node Workflows →](docs/v2/guides/complete-tutorial.md#part-5-node-workflows)\n\n### Hooks System\n\nRun custom logic at key execution points:\n\n```yaml\nversion: 2\nagents:\n  developer:\n    model: claude-3-5-sonnet-20241022\n    role: \"Full-stack developer\"\n    tools: [Read, Write, Edit, Bash]\n    hooks:\n      # Run before each tool execution\n      on_pre_tool:\n        - run: \"echo 'About to use {{ tool_name }}'\"\n\n      # Run after successful tool execution\n      on_post_tool:\n        - run: \"echo 'Tool {{ tool_name }} completed successfully'\"\n\n      # Append git diff to every user message\n      on_user_message:\n        - run: \"git diff\"\n          append_output_to_context: true\n\n      # Run tests before the agent responds\n      on_pre_response:\n        - run: \"npm test\"\n          stop_on_error: true\n```\n\n[Learn more about Hooks →](docs/v2/guides/complete-tutorial.md#part-4-hooks-system)\n\n---\n\n## 📊 Cost Tracking \u0026 Logging\n\nSwarmSDK provides built-in cost tracking and structured logging:\n\n```ruby\nrequire 'swarm_sdk'\n\nswarm = SwarmSDK.load('my_swarm.yml')\n\nresult = swarm.execute(\n  agent: :lead,\n  prompt: \"Build a simple TODO app\",\n  logger: Logger.new($stdout)\n)\n\n# Access cost information\nputs \"Total cost: $#{result.cost}\"\nputs \"Tokens used: #{result.tokens}\"\n```\n\n[Learn more about Production Features →](docs/v2/guides/complete-tutorial.md#part-7-production-features)\n\n---\n\n## 🔗 Integration Examples\n\n### Rails Integration\n\n```ruby\n# app/jobs/code_review_job.rb\nclass CodeReviewJob \u003c ApplicationJob\n  def perform(pull_request_id)\n    swarm = SwarmSDK.load(Rails.root.join('config', 'code_review_swarm.yml'))\n\n    result = swarm.execute(\n      agent: :lead_reviewer,\n      prompt: \"Review PR ##{pull_request_id}\"\n    )\n\n    PullRequest.find(pull_request_id).update(\n      review_status: 'completed',\n      review_comments: result.message\n    )\n  end\nend\n```\n\n[Learn more about Rails Integration →](docs/v2/guides/rails-integration.md)\n\n### Custom Plugins\n\n```ruby\n# lib/my_plugin.rb\nclass MyPlugin \u003c SwarmSDK::Plugin\n  def on_agent_init(agent)\n    # Add custom behavior when agent initializes\n  end\n\n  def on_user_message(message, agent)\n    # Process user messages\n  end\n\n  def provide_tools\n    [MyCustomTool.new]\n  end\nend\n\n# Register the plugin\nSwarmSDK.register_plugin(:my_plugin, MyPlugin)\n```\n\n[Learn more about Plugins →](docs/v2/guides/plugins.md)\n\n---\n\n## 🆚 SwarmSDK (v2) vs Claude Swarm (v1)\n\n| Feature                | SwarmSDK v2            | Claude Swarm v1                 |\n| ---------------------- | ---------------------- | ------------------------------- |\n| **Architecture**       | Single Ruby process    | Multiple Claude Code processes  |\n| **Dependencies**       | RubyLLM (Ruby-only)    | Requires Claude CLI (Node.js)   |\n| **Performance**        | Direct method calls    | MCP inter-process communication |\n| **LLM Support**        | All RubyLLM providers  | Claude + OpenAI (via MCP)       |\n| **Memory System**      | Built-in SwarmMemory   | Not available                   |\n| **Plugin System**      | Yes                    | No                              |\n| **Node Workflows**     | Yes                    | No                              |\n| **Hooks**              | 12 events, 6 actions   | Claude Code hooks only          |\n| **Context Management** | Fine-grained control   | Limited                         |\n| **Cost Tracking**      | Built-in               | Limited to MCP calls            |\n| **Interactive REPL**   | TTY-based with history | Not available                   |\n| **Ruby DSL**           | Full support           | Not available                   |\n\n---\n\n## 📖 Looking for v1 Documentation?\n\n**Claude Swarm (v1)** continues to be maintained and is still a great choice if you prefer the multi-process architecture with Claude Code instances.\n\n[View Claude Swarm v1 Documentation →](docs/v1/README.md)\n\nTo install Claude Swarm v1:\n\n```bash\ngem install claude_swarm\n```\n\n---\n\n## 🤝 Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/parruda/claude-swarm.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n---\n\n## 📄 License\n\nThe gems are available as open source under the terms of the [MIT License](LICENSE).\n\n---\n\n## 🔗 Links\n\n- **Documentation**: [docs/v2/README.md](docs/v2/README.md)\n- **GitHub Repository**: [parruda/claude-swarm](https://github.com/parruda/claude-swarm)\n- **RubyGems**:\n  - [swarm_sdk](https://rubygems.org/gems/swarm_sdk)\n  - [swarm_cli](https://rubygems.org/gems/swarm_cli)\n  - [swarm_memory](https://rubygems.org/gems/swarm_memory)\n- **Issues \u0026 Support**: [GitHub Issues](https://github.com/parruda/claude-swarm/issues)\n\n---\n\n**Ready to get started?** → [Getting Started with SwarmSDK](docs/v2/guides/getting-started.md) or [Getting Started with SwarmCLI](docs/v2/guides/quick-start-cli.md)\n","funding_links":[],"categories":["Ruby","AI Coding Agents"],"sub_categories":["Claude Code"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparruda%2Fswarm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparruda%2Fswarm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparruda%2Fswarm/lists"}