claude_swarm 1.0.6 → 1.0.7

data/README.md

@@ -1,1181 +1,480 @@
-# 🚀 SwarmSDK - The New Way
+# SwarmSDK, SwarmCLI & SwarmMemory
 
-**We recommend using SwarmSDK v2 for new projects!** SwarmSDK is a complete redesign of Claude Swarm that provides a better developer experience. SwarmSDK 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](https://github.com/parruda/ruby_llm) - no more managing multiple Claude Code instances
-- **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
-- **REPL**: Built with TTY toolkit for a nice command-line experience
-- **Multiple LLM Providers**: Supports all LLM providers supported by RubyLLM
-
-## Getting Started with v2
-
-```bash
-gem install swarm_cli     # Includes swarm_sdk
-swarm --help              # Explore the modern CLI
-```
-
-**📚 Complete Documentation**: Check out the [SwarmSDK guides](docs/v2/README.md) including the comprehensive [complete tutorial](docs/v2/guides/complete-tutorial.md) covering all features.
-
-**Note**: Claude Swarm (v1, documented below) will continue to be maintained and is still a great choice if you prefer the multi-process architecture with Claude Code instances.
-
-# Claude Swarm
-
-[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust1=1.0.1)](https://badge.fury.io/rb/claude_swarm)
+[![Gem Version](https://badge.fury.io/rb/swarm_sdk.svg)](https://badge.fury.io/rb/swarm_sdk)
+[![Gem Version](https://badge.fury.io/rb/swarm_cli.svg)](https://badge.fury.io/rb/swarm_cli)
+[![Gem Version](https://badge.fury.io/rb/swarm_memory.svg)](https://badge.fury.io/rb/swarm_memory)
 [![CI](https://github.com/parruda/claude-swarm/actions/workflows/ci.yml/badge.svg)](https://github.com/parruda/claude-swarm/actions/workflows/ci.yml)
 
-Claude Swarm orchestrates multiple Claude Code instances as a collaborative AI development team. It enables running AI agents with specialized roles, tools, and directory contexts, communicating via MCP (Model Context Protocol) in a tree-like hierarchy. Define your swarm topology in simple YAML and let Claude instances delegate tasks through connected instances. Perfect for complex projects requiring specialized AI agents for frontend, backend, testing, DevOps, or research tasks.
-
----
+**A Ruby framework for orchestrating multiple AI agents as a collaborative team with persistent memory.**
 
-## Table of Contents
-
-- [Installation](#installation)
-- [Prerequisites](#prerequisites)
-- [Usage](#usage)
-  - [Quick Start](#quick-start)
-  - [Configuration Format](#configuration-format)
-  - [MCP Server Types](#mcp-server-types)
-  - [Tools](#tools)
-  - [Examples](#examples)
-  - [Command Line Options](#command-line-options)
-  - [Session Monitoring](#session-monitoring)
-  - [Session Management and Restoration](#session-management-and-restoration-experimental)
-- [How It Works](#how-it-works)
-- [Troubleshooting](#troubleshooting)
-- [Architecture](#architecture)
-- [Development](#development)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Installation
-
-Install [Claude CLI](https://docs.anthropic.com/en/docs/claude-code/overview) if you haven't already:
+SwarmSDK is a complete redesign of Claude Swarm that provides a better developer experience and is geared towards general-purpose agentic systems.
 
-```bash
-npm install -g @anthropic-ai/claude-code
-```
+## ✨ Key Features
 
-Install this gem by executing:
-
-```bash
-gem install claude_swarm
-```
+- **🚀 Decoupled from Claude Code**: No more dependency on Claude Code
+- **⚡ Single Process Architecture**: All agents run in one Ruby process using [RubyLLM](https://github.com/parruda/ruby_llm) - 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
 
-Or add it to your Gemfile:
+---
 
-```ruby
-gem 'claude_swarm', "~> 1.0"
-```
+## 🚀 Quick Start
 
-Then run:
+### Installation
 
 ```bash
-bundle install
+gem install swarm_cli     # Includes swarm_sdk
+swarm --help              # Explore the modern CLI
 ```
 
-## Prerequisites
+### Your First Swarm
 
-- Ruby 3.2.0 or higher
-- Claude CLI installed and configured
-- Any MCP servers you plan to use (optional)
-
-## Usage
-
-### Quick Start
-
-1. Run `claude-swarm init` to create a basic template, or use `claude-swarm generate` for an interactive configuration experience with Claude's help. You can also manually create a `claude-swarm.yml` file in your project:
+Create a simple swarm configuration file `my_swarm.yml`:
 
 ```yaml
-version: 1
-swarm:
-  name: "My Dev Team"
-  main: lead
-  instances:
-    lead:
-      description: "Team lead coordinating development efforts"
-      directory: .
-      model: opus
-      connections: [frontend, backend]
-      vibe: true   # Allow all tools for this instance
-    frontend:
-      description: "Frontend specialist handling UI and user experience"
-      directory: ./frontend
-      model: opus
-      allowed_tools:  # Tools aren't required if you run it with `--vibe`
-        - Edit
-        - Write
-        - Bash
-    backend:
-      description: "Backend developer managing APIs and data layer"
-      directory: ./backend  
-      model: opus
-      allowed_tools:
-        - Edit
-        - Write
-        - Bash
-```
-
-2. Start the swarm:
-
-```bash
-claude-swarm
-```
-or if you are feeling the vibes...
-```bash
-claude-swarm --vibe # That will allow ALL tools for all instances! Be Careful!
-```
-
-This will:
-- Launch the main instance (lead) with connections to other instances
-- The lead instance can communicate with the other instances via MCP
-- All session files are stored in `~/.claude-swarm/sessions/{project}/{timestamp}/` (customizable via `CLAUDE_SWARM_HOME`)
-
-#### Multi-Level Swarm Example
-
-Here's a more complex example showing specialized teams working on different parts of a project:
-
-```yaml
-version: 1
-swarm:
-  name: "Multi-Service Development Team"
-  main: architect
-  instances:
-    architect:
-      description: "System architect coordinating between service teams"
-      directory: .
-      model: opus
-      connections: [frontend_lead, backend_lead, mobile_lead, devops]
-      prompt: "You are the system architect coordinating between different service teams"
-      allowed_tools: [Read, Edit, WebSearch]
-    
-    frontend_lead:
-      description: "Frontend team lead overseeing React development"
-      directory: ./web-frontend
-      model: opus
-      connections: [react_dev, css_expert]
-      prompt: "You lead the web frontend team working with React"
-      allowed_tools: [Read, Edit, Bash]
-    
-    react_dev:
-      description: "React developer specializing in components and state management"
-      directory: ./web-frontend/src
-      model: opus
-      prompt: "You specialize in React components and state management"
-      allowed_tools: [Edit, Write, Bash]
-    
-    css_expert:
-      description: "CSS specialist handling styling and responsive design"
-      directory: ./web-frontend/styles
-      model: opus
-      prompt: "You handle all CSS and styling concerns"
-      allowed_tools: [Edit, Write, Read]
-    
-    backend_lead:
-      description: "Backend team lead managing API development"
-      directory: ./api-server
-      model: opus
-      connections: [api_dev, database_expert]
-      prompt: "You lead the API backend team"
-      allowed_tools: [Read, Edit, Bash]
-    
-    api_dev:
-      description: "API developer building REST endpoints"
-      directory: ./api-server/src
-      model: opus
-      prompt: "You develop REST API endpoints"
-      allowed_tools: [Edit, Write, Bash]
-    
-    database_expert:
-      description: "Database specialist managing schemas and migrations"
-      directory: ./api-server/db
-      model: opus
-      prompt: "You handle database schema and migrations"
-      allowed_tools: [Edit, Write, Bash]
-    
-    mobile_lead:
-      description: "Mobile team lead coordinating cross-platform development"
-      directory: ./mobile-app
-      model: opus
-      connections: [ios_dev, android_dev]
-      prompt: "You coordinate mobile development across platforms"
-      allowed_tools: [Read, Edit]
-    
-    ios_dev:
-      description: "iOS developer building native Apple applications"
-      directory: ./mobile-app/ios
-      model: opus
-      prompt: "You develop the iOS application"
-      allowed_tools: [Edit, Write, Bash]
-    
-    android_dev:
-      description: "Android developer creating native Android apps"
-      directory: ./mobile-app/android
-      model: opus
-      prompt: "You develop the Android application"
-      allowed_tools: [Edit, Write, Bash]
-    
-    devops:
-      description: "DevOps engineer managing CI/CD and infrastructure"
-      directory: ./infrastructure
-      model: opus
-      prompt: "You handle CI/CD and infrastructure"
-      allowed_tools: [Read, Edit, Bash]
-```
-
-In this setup:
-- The architect (main instance) can delegate tasks to team leads
-- Each team lead can work with their specialized developers
-- Each instance is independent - connections create separate MCP server instances
-- Teams work in isolated directories with role-appropriate tools
-- Connected instances are accessible via MCP tools like `mcp__frontend_lead__task`, `mcp__backend_lead__task`, etc.
-
-
-### Configuration Format
+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
 
-#### Top Level
+  frontend:
+    model: claude-3-5-sonnet-20241022
+    role: "Frontend specialist handling UI and user experience"
+    tools: [Read, Write, Edit]
 
-```yaml
-version: 1  # Required, currently only version 1 is supported
-swarm:
-  name: "Swarm Name"  # Display name for your swarm
-  main: instance_key  # Which instance to launch as the main interface
-  before:  # Optional: commands to run before launching the swarm
-    - "echo 'Setting up environment...'"
-    - "npm install"
-    - "docker-compose up -d"
-  after:  # Optional: commands to run after exiting the swarm
-    - "echo 'Cleaning up environment...'"
-    - "docker-compose down"
-  instances:
-    # Instance definitions...
+  backend:
+    model: claude-3-5-sonnet-20241022
+    role: "Backend developer managing APIs and data layer"
+    tools: [Read, Write, Edit, Bash]
 ```
 
-#### YAML Aliases
+Run it:
 
-Claude Swarm supports [YAML aliases](https://yaml.org/spec/1.2.2/#71-alias-nodes) to reduce duplication in your configuration. This is particularly useful for sharing common values like prompts, tool lists, or MCP configurations across multiple instances:
+```bash
+# Interactive REPL mode
+swarm run my_swarm.yml
 
-```yaml
-version: 1
-swarm:
-  name: "Development Team"
-  main: lead
-  instances:
-    lead:
-      description: "Lead developer"
-      prompt: &shared_prompt "You are an expert developer following best practices"
-      allowed_tools: &standard_tools
-        - Read
-        - Edit
-        - Bash
-        - WebSearch
-      mcps: &common_mcps
-        - name: github
-          type: stdio
-          command: gh
-          args: ["mcp"]
-          
-    frontend:
-      description: "Frontend developer"
-      prompt: *shared_prompt  # Reuses the same prompt
-      allowed_tools: *standard_tools  # Reuses the same tool list
-      mcps: *common_mcps  # Reuses the same MCP servers
-      directory: ./frontend
-      
-    backend:
-      description: "Backend developer"
-      prompt: *shared_prompt  # Reuses the same prompt
-      allowed_tools: *standard_tools  # Reuses the same tool list
-      mcps: *common_mcps  # Reuses the same MCP servers
-      directory: ./backend
+# Or with a specific prompt
+swarm run my_swarm.yml -p "Build a simple TODO app with React and Node.js"
 ```
 
-In this example:
-- `&shared_prompt` defines an anchor for the prompt string
-- `&standard_tools` defines an anchor for the tool array
-- `&common_mcps` defines an anchor for the MCP configuration
-- `*shared_prompt`, `*standard_tools`, and `*common_mcps` reference those anchors
+---
 
-This helps maintain consistency across instances and makes configuration updates easier.
+## 📚 Documentation
 
-#### Environment Variable Interpolation
+**Complete documentation is available in the [docs/v2](docs/v2/README.md) directory.**
 
-Claude Swarm supports environment variable interpolation in all configuration values using the `${ENV_VAR_NAME}` syntax:
+### Getting Started
 
-```yaml
-version: 1
-swarm:
-  name: "${APP_NAME} Development Team"
-  main: lead
-  instances:
-    lead:
-      description: "Lead developer for ${APP_NAME}"
-      directory: "${PROJECT_ROOT}"
-      model: "${CLAUDE_MODEL}"
-      prompt: "You are developing ${APP_NAME} version ${APP_VERSION}"
-      allowed_tools: ["${TOOL_1}", "${TOOL_2}", "Bash"]
-      mcps:
-        - name: github
-          type: stdio
-          command: "${MCP_GITHUB_PATH}"
-          env:
-            GITHUB_TOKEN: "${GITHUB_TOKEN}"
-```
+- **[Getting Started with SwarmSDK](docs/v2/guides/getting-started.md)** ⭐
+  Learn the basics: installation, core concepts, your first swarm (YAML & Ruby DSL)
 
-Features:
-- Variables are interpolated recursively in strings, arrays, and nested structures
-- Multiple variables can be used in the same string
-- Partial string interpolation is supported (e.g., `"prefix-${VAR}-suffix"`)
-- If a referenced environment variable is not set, Claude Swarm will exit with a clear error message
-- Non-matching patterns like `$VAR` or `{VAR}` are preserved as-is
+- **[Getting Started with SwarmCLI](docs/v2/guides/quick-start-cli.md)** ⭐
+  Command-line interface: interactive REPL and automation modes
 
-##### Default Values
+### Comprehensive Tutorial
 
-Environment variables can have default values using the `${VAR_NAME:=default_value}` syntax:
+- **[SwarmSDK Complete Tutorial](docs/v2/guides/complete-tutorial.md)**
+  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)
 
-```yaml
-version: 1
-swarm:
-  name: "Dev Team"
-  main: lead
-  instances:
-    lead:
-      description: "Lead developer"
-      directory: "${PROJECT_DIR:=.}"
-      model: "${CLAUDE_MODEL:=sonnet}"
-      mcps:
-        - name: api-server
-          type: sse
-          url: "${API_URL:=http://localhost:8080}"
-      worktree: "${BRANCH_NAME:=feature-branch}"
-```
+### Reference Documentation
 
-- Default values are used when the environment variable is not set
-- Any string can be used as a default value, including spaces and special characters
-- Empty defaults are supported: `${VAR:=}` results in an empty string if VAR is not set
-- Works in all configuration values: strings, arrays, and nested structures
+- **[Architecture Flow Diagram](docs/v2/reference/architecture-flow.md)** - Complete system architecture
+- **[Execution Flow Diagram](docs/v2/reference/execution-flow.md)** - Runtime execution journey (21 detailed steps)
+- **[CLI Reference](docs/v2/reference/cli.md)** - Complete command-line reference
+- **[Ruby DSL Reference](docs/v2/reference/ruby-dsl.md)** - Complete programmatic API
+- **[YAML Configuration Reference](docs/v2/reference/yaml.md)** - Complete YAML structure
 
-#### Instance Configuration
+### Integration Guides
 
-Each instance must have:
+- **[SwarmMemory Guide](docs/v2/guides/swarm-memory.md)** - Persistent agent knowledge with semantic search
+- **[Plugin System Guide](docs/v2/guides/plugins.md)** - Build extensions for SwarmSDK
+- **[Memory Adapter Development](docs/v2/guides/memory-adapters.md)** - Custom storage backends
+- **[Rails Integration Guide](docs/v2/guides/rails-integration.md)** - Integrate with Ruby on Rails
 
-- **description** (required): Brief description of the agent's role (used in task tool descriptions)
+---
 
-Each instance can have:
+## 💡 Core Concepts
 
-- **directory**: Working directory for this instance (can use ~ for home). Can be a string for a single directory or an array of strings for multiple directories
-- **model**: Claude model to use (opus, sonnet)
-- **connections**: Array of other instances this one can communicate with
-- **allowed_tools**: Array of tools this instance can use (backward compatible with `tools`)
-- **disallowed_tools**: Array of tools to explicitly deny (takes precedence over allowed_tools)
-- **mcps**: Array of additional MCP servers to connect
-- **prompt**: Custom system prompt to append to the instance
-- **vibe**: Enable vibe mode (--dangerously-skip-permissions) for this instance (default: false)
-- **worktree**: Configure Git worktree usage for this instance (true/false/string)
-- **provider**: AI provider to use - "claude" (default) or "openai"
-- **hooks**: Configure Claude Code hooks for this instance (see Hooks Configuration section below)
+### SwarmSDK
 
-#### OpenAI Provider Configuration
+A Ruby framework for orchestrating multiple AI agents that work together as a team. Each agent has:
 
-When using `provider: openai`, the following additional fields are available:
+- **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
 
-- **temperature**: Temperature for GPT models only (0.0-2.0). Not supported for O-series reasoning models (o1, o1-preview, o1-mini, o3, etc.)
-- **api_version**: API version to use - "chat_completion" (default) or "responses"
-- **openai_token_env**: Environment variable name for OpenAI API key (default: "OPENAI_API_KEY")
-- **base_url**: Custom base URL for OpenAI API (optional)
-- **reasoning_effort**: Reasoning effort for O-series models only - "low", "medium", or "high"
+### SwarmCLI
 
-**Important Notes:**
-- O-series models (o1, o1-preview, o1-mini, o3, etc.) use deterministic reasoning and do not support the `temperature` parameter
-- The `reasoning_effort` parameter is only supported by O-series models
-- GPT models support `temperature` but not `reasoning_effort`
-- OpenAI instances default to and ONLY operate as `vibe: true` and use MCP for tool access
-- By default it comes with Claude Code tools, connected with MCP to `claude mcp serve`
-- **Using the responses API requires ruby-openai >= 8.0** - the gem will validate this requirement at runtime
+A command-line interface for running SwarmSDK swarms with two modes:
 
-```yaml
-instance_name:
-  description: "Specialized agent focused on specific tasks"
-  directory: ~/project/path
-  model: opus
-  connections: [other_instance1, other_instance2]
-  prompt: "You are a specialized agent focused on..."
-  vibe: false  # Set to true to skip all permission checks for this instance
-  allowed_tools:
-    - Read
-    - Edit
-    - Write
-    - Bash
-    - WebFetch
-    - WebSearch
-  disallowed_tools:  # Optional: explicitly deny specific tools
-    - "Write(*.log)"
-    - "Bash(rm:*)"
-  mcps:
-    - name: server_name
-      type: stdio
-      command: command_to_run
-      args: ["arg1", "arg2"]
-      env:
-        VAR1: value1
-
-# OpenAI instance examples
-
-# GPT model with temperature
-gpt_instance:
-  description: "OpenAI GPT-powered creative assistant"
-  provider: openai
-  model: gpt-4o
-  temperature: 0.7  # Supported for GPT models
-  api_version: chat_completion
-  openai_token_env: OPENAI_API_KEY
-  prompt: "You are a creative assistant specializing in content generation"
-
-# O-series reasoning model with reasoning_effort
-reasoning_instance:
-  description: "OpenAI O-series reasoning assistant"
-  provider: openai
-  model: o1-mini
-  reasoning_effort: medium  # Only for O-series models
-  api_version: responses    # Can use either API version
-  prompt: "You are a reasoning assistant for complex problem solving"
-```
+- **Interactive (REPL)**: Conversational interface for exploration and iteration
+- **Non-Interactive**: One-shot execution perfect for automation and scripting
 
-### MCP Server Types
+### SwarmMemory
 
-#### stdio (Standard I/O)
-```yaml
-mcps:
-  - name: my_tool
-    type: stdio
-    command: /path/to/executable
-    args: ["--flag", "value"]
-    env:
-      API_KEY: "secret"
-```
+A persistent memory system for agents with semantic search capabilities:
 
-#### sse (Server-Sent Events)
-```yaml
-mcps:
-  - name: remote_api
-    type: sse
-    url: "https://api.example.com/mcp"
-    headers:  # Optional: custom headers for authentication
-      Authorization: "Bearer ${API_TOKEN}"
-      X-Custom-Header: "value"
-```
+- **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
 
-#### http (HTTP-based MCP)
-```yaml
-mcps:
-  - name: http_service
-    type: http
-    url: "https://api.example.com/mcp-endpoint"
-    headers:  # Optional: custom headers for authentication
-      Authorization: "Bearer ${API_TOKEN}"
-      X-API-Key: "${API_KEY}"
-```
+### Configuration Formats
 
-### Hooks Configuration
+- **YAML**: Declarative, easy to read, great for shell-based hooks
+- **Ruby DSL**: Programmatic, dynamic, full Ruby power, IDE support
 
-Claude Swarm supports configuring [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) for each instance. Hooks allow you to run custom scripts before/after tools, on prompt submission, and more. Each instance can have its own hooks configuration.
-
-#### Supported Hook Events
-
-- **PreToolUse**: Run before a tool is executed
-- **PostToolUse**: Run after a tool completes
-- **UserPromptSubmit**: Run when a user prompt is submitted
-- **Stop**: Run when the Claude instance stops
-- **SessionStart**: Run when a session starts
-- **And more...** (see Claude Code hooks documentation)
+---
 
-#### Configuration Example
+## 🎯 Example: Code Review Team
 
 ```yaml
-instances:
-  lead:
-    description: "Lead developer"
-    directory: .
-    # Hooks configuration follows Claude Code's format exactly
+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:
-      PreToolUse:
-        - matcher: "Write|Edit"
-          hooks:
-            - type: "command"
-              command: "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-code.py"
-              timeout: 10
-      PostToolUse:
-        - matcher: "Bash"
-          hooks:
-            - type: "command"
-              command: "echo 'Bash executed by ${INSTANCE_NAME}' >> ${LOG_DIR}/commands.log"
-      UserPromptSubmit:
-        - hooks:
-            - type: "command"
-              command: "${HOOKS_DIR:=$CLAUDE_PROJECT_DIR/.claude/hooks}/add-context.py"
-  frontend:
-    description: "Frontend developer"
-    directory: ./frontend
+      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:
-      PreToolUse:
-        - matcher: "Write"
-          hooks:
-            - type: "command"
-              command: "npm run lint"
-              timeout: 5
-```
-
-#### How It Works
-
-1. Define hooks in your instance configuration using the exact format expected by Claude Code
-2. Claude Swarm generates a `settings.json` file for each instance with hooks
-3. The settings file is passed to Claude Code SDK via the `--settings` parameter
-4. Each instance runs with its own hooks configuration
-
-#### Environment Variables in Hooks
+      on_user_message:
+        - run: "semgrep --config=auto --json"
+          append_output_to_context: true
 
-Hooks have access to standard Claude Code environment variables plus:
-- `$CLAUDE_PROJECT_DIR` - The project directory
-- `$CLAUDE_SWARM_SESSION_DIR` - The swarm session directory
-- `$CLAUDE_SWARM_INSTANCE_NAME` - The name of the current instance
-
-### Tools
-
-Specify which tools each instance can use:
-
-```yaml
-allowed_tools:
-  - Bash           # Command execution
-  - Edit           # File editing
-  - Write          # File creation
-  - Read           # File reading
-  - WebFetch       # Fetch web content
-  - WebSearch      # Search the web
-
-# Note: Pattern-based tool restrictions have been deprecated.
-# Use allowed_tools and disallowed_tools with tool names only.
+  performance_analyst:
+    model: claude-3-5-sonnet-20241022
+    role: "Performance analyst identifying bottlenecks"
+    tools: [Read, Bash]
 ```
 
-Tools are passed to Claude using the `--allowedTools` and `--disallowedTools` flags with comma-separated values. Disallowed tools take precedence over allowed tools.
+Run the code review:
 
-#### Available Tools
-
-```yaml
-allowed_tools:
-  - Read          # File reading
-  - Edit          # File editing
-  - Write         # File creation
-  - Bash          # Command execution
-  - WebFetch      # Fetch web content
-  - WebSearch     # Search the web
+```bash
+swarm run code_review.yml -p "Review the recent changes in the authentication module"
 ```
 
-### Examples
-
-#### Full Stack Development Team
+---
 
-```yaml
-version: 1
-swarm:
-  name: "Full Stack Team"
-  main: architect
-  instances:
-    architect:
-      description: "Lead architect responsible for system design and code quality"
-      directory: .
-      model: opus
-      connections: [frontend, backend, devops]
-      prompt: "You are the lead architect responsible for system design and code quality"
-      allowed_tools:
-        - Read
-        - Edit
-        - WebSearch
-        
-    frontend:
-      description: "Frontend developer specializing in React and TypeScript"
-      directory: ./frontend
-      model: opus
-      connections: [architect]
-      prompt: "You specialize in React, TypeScript, and modern frontend development"
-      allowed_tools:
-        - Edit
-        - Write
-        - Bash
-        
-    backend:
-      description: "Backend developer building APIs and services"
-      directory: ./backend
-      model: opus
-      connections: [database]
-      allowed_tools:
-        - Edit
-        - Write
-        - Bash
-        
-    database:
-      description: "Database administrator managing data persistence"
-      directory: ./db
-      model: sonnet
-      allowed_tools:
-        - Read
-        - Bash
-        
-    devops:
-      description: "DevOps engineer handling deployment and infrastructure"
-      directory: .
-      model: opus
-      connections: [architect]
-      allowed_tools:
-        - Read
-        - Edit
-        - Bash
-```
+## 🧠 SwarmMemory Example
 
-#### Research Team with External Tools
+Enable persistent memory for your agents:
 
-```yaml
-version: 1
-swarm:
-  name: "Research Team"
-  main: lead_researcher
-  instances:
-    lead_researcher:
-      description: "Lead researcher coordinating analysis and documentation"
-      directory: ~/research
-      model: opus
-      connections: [data_analyst, writer]
-      allowed_tools:
-        - Read
-        - WebSearch
-        - WebFetch
-      mcps:
-        - name: arxiv
-          type: sse
-          url: "https://arxiv-mcp.example.com"
-          
-    data_analyst:
-      description: "Data analyst processing research data and statistics"
-      directory: ~/research/data
-      model: opus
-      allowed_tools:
-        - Read
-        - Write
-        - Bash
-      mcps:
-        - name: jupyter
-          type: stdio
-          command: jupyter-mcp
-          args: ["--notebook-dir", "."]
-          
-    writer:
-      description: "Technical writer preparing research documentation"
-      directory: ~/research/papers
-      model: opus
-      allowed_tools:
-        - Edit
-        - Write
-        - Read
+```bash
+gem install swarm_memory
 ```
 
-#### Multi-Directory Support
-
-Instances can have access to multiple directories using an array (uses `claude --add-dir`):
-
 ```yaml
-version: 1
-swarm:
-  name: "Multi-Module Project"
-  main: fullstack_dev
-  instances:
-    fullstack_dev:
-      description: "Full-stack developer working across multiple modules"
-      directory: [./frontend, ./backend, ./shared]  # Access to multiple directories
-      model: opus
-      allowed_tools: [Read, Edit, Write, Bash]
-      prompt: "You work across frontend, backend, and shared code modules"
-      
-    documentation_writer:
-      description: "Documentation specialist with access to code and docs"
-      directory: ["./docs", "./src", "./examples"]  # Multiple directories as array
-      model: sonnet
-      allowed_tools: [Read, Write, Edit]
-      prompt: "You maintain documentation based on code and examples"
+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
 ```
 
-When using multiple directories:
-- The first directory in the array is the primary working directory
-- Additional directories are accessible via the `--add-dir` flag in Claude
-- All directories must exist or the configuration will fail validation
-
-#### Mixed AI Provider Team
-
-Combine Claude and OpenAI instances in a single swarm:
+The agent now has access to memory tools:
 
-```yaml
-version: 1
-swarm:
-  name: "Mixed AI Development Team"
-  main: lead_developer
-  instances:
-    lead_developer:
-      description: "Claude lead developer coordinating the team"
-      directory: .
-      model: opus
-      connections: [creative_assistant, reasoning_expert, backend_dev]
-      prompt: "You are the lead developer coordinating a mixed AI team"
-      allowed_tools: [Read, Edit, Bash, Write]
-      
-    creative_assistant:
-      description: "OpenAI-powered assistant for creative and UI/UX tasks"
-      provider: openai
-      model: gpt-4o
-      temperature: 0.7  # Supported for GPT models
-      directory: ./frontend
-      prompt: "You are a creative frontend developer specializing in UI/UX design"
-      # OpenAI instances default to vibe: true
-      
-    reasoning_expert:
-      description: "OpenAI O-series model for complex problem solving"
-      provider: openai
-      model: o1-mini
-      reasoning_effort: high  # For O-series models only
-      directory: ./architecture
-      prompt: "You solve complex architectural and algorithmic problems"
-      
-    backend_dev:
-      description: "Claude backend developer for system architecture"
-      directory: ./backend
-      model: sonnet
-      prompt: "You specialize in backend development and system architecture"
-      allowed_tools: [Read, Edit, Write, Bash]
-```
+- `MemoryWrite` - Store new knowledge
+- `MemoryRead` - Retrieve specific memories
+- `MemorySearch` - Semantic search across all knowledge
+- `LoadSkill` - Dynamically load specialized skills
+- And more...
 
-Note: OpenAI instances require the API key to be set in the environment variable (default: `OPENAI_API_KEY`).
+[Learn more about SwarmMemory →](docs/v2/guides/swarm-memory.md)
 
-#### Before and After Commands
-
-You can specify commands to run before launching and after exiting the swarm using the `before` and `after` fields:
+---
 
-```yaml
-version: 1
-swarm:
-  name: "Development Environment"
-  main: lead_developer
-  before:
-    - "echo '🚀 Setting up development environment...'"
-    - "npm install"
-    - "docker-compose up -d"
-    - "bundle install"
-  after:
-    - "echo '🛑 Cleaning up development environment...'"
-    - "docker-compose down"
-    - "rm -rf temp/*"
-  instances:
-    lead_developer:
-      description: "Lead developer coordinating the team"
-      directory: .
-      model: opus
-      allowed_tools: [Read, Edit, Write, Bash]
-```
+## 🔧 Ruby DSL Example
 
-The `before` commands:
-- Are executed in sequence before launching any Claude instances
-- Execute in the main instance's directory (including worktree if enabled)
-- Must all succeed for the swarm to launch (exit code 0)
-- Are only executed on initial swarm launch, not when restoring sessions
-- Have their output logged to the session log file
-- Will abort the swarm launch if any command fails
+For programmatic control, use the Ruby DSL:
 
-The `after` commands:
-- Are executed after Claude exits but before cleanup processes
-- Execute in the main instance's directory (including worktree if enabled)
-- Run even when the swarm is interrupted by signals (Ctrl+C)
-- Failures do not prevent cleanup from proceeding
-- Are only executed on initial swarm runs, not when restoring sessions
-- Have their output logged to the session log file
+```ruby
+require 'swarm_sdk'
 
-This is useful for:
-- Installing dependencies in the isolated worktree environment
-- Starting required services (databases, Docker containers, etc.)
-- Setting up the development environment
-- Running any prerequisite setup scripts
-- Ensuring setup commands affect only the working directory, not the original repository
+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
 
-#### Mixed Permission Modes
+  agent :backend do
+    model "claude-3-5-sonnet-20241022"
+    role "Backend specialist"
+    tools :Read, :Write, :Edit, :Bash
+  end
+end
 
-You can have different permission modes for different instances:
+# Execute with the lead agent
+result = swarm.execute(
+  agent: :lead,
+  prompt: "Build a simple TODO app"
+)
 
-```yaml
-version: 1
-swarm:
-  name: "Mixed Mode Team"
-  main: lead
-  instances:
-    lead:
-      description: "Lead with full permissions"
-      directory: .
-      model: opus
-      vibe: true  # This instance runs with --dangerously-skip-permissions
-      connections: [restricted_worker, trusted_worker]
-      
-    restricted_worker:
-      description: "Worker with restricted permissions"
-      directory: ./sensitive
-      model: sonnet
-      allowed_tools: [Read, Bash]  # Allow read and bash commands
-      
-    trusted_worker:
-      description: "Trusted worker with more permissions"
-      directory: ./workspace
-      model: sonnet
-      vibe: true  # This instance also skips permissions
-      allowed_tools: []  # Tools list ignored when vibe: true
+puts result.message
 ```
 
-#### Git Worktrees
-
-Claude Swarm supports running instances in Git worktrees, allowing isolated work without affecting your main repository state. Worktrees are created in an external directory (`~/.claude-swarm/worktrees/`) to ensure proper isolation from the main repository and avoid conflicts with bundler and other tools.
+[Learn more about the Ruby DSL →](docs/v2/reference/ruby-dsl.md)
 
-**Example Structure:**
-```
-~/.claude-swarm/worktrees/
-└── [session_id]/
-    ├── my-repo-[hash]/
-    │   └── feature-x/     (worktree for feature-x branch)
-    └── other-repo-[hash]/
-        └── feature-x/     (worktree for feature-x branch)
-```
+---
 
-**CLI Option:**
-```bash
-# Create worktrees with auto-generated name (worktree-SESSION_ID)
-claude-swarm --worktree
+## 🛠️ Advanced Features
 
-# Create worktrees with custom name
-claude-swarm --worktree feature-branch
+### Node Workflows
 
-# Short form
-claude-swarm -w
-```
+Build multi-stage processing pipelines:
 
-**Per-Instance Configuration:**
 ```yaml
-version: 1
-swarm:
-  name: "Worktree Example"
-  main: lead
-  instances:
-    lead:
-      description: "Lead developer"
-      directory: .
-      worktree: true  # Use shared worktree name from CLI (or auto-generate)
-      
-    testing:
-      description: "Test developer"  
-      directory: ./tests
-      worktree: false  # Don't use worktree for this instance
-      
-    feature_dev:
-      description: "Feature developer"
-      directory: ./features
-      worktree: "feature-x"  # Use specific worktree name
-```
-
-**Worktree Behavior:**
-- `worktree: true` - Uses the shared worktree name (from CLI or auto-generated)
-- `worktree: false` - Disables worktree for this instance
-- `worktree: "name"` - Uses a specific worktree name
-- Omitted - Follows CLI behavior (use worktree if `--worktree` is specified)
-
-**Notes:**
-- Auto-generated worktree names use the session ID (e.g., `worktree-20241206_143022`)
-- This makes it easy to correlate worktrees with their Claude Swarm sessions
-- Worktrees are stored externally in `~/.claude-swarm/worktrees/[session_id]/`
-- All worktrees are automatically cleaned up when the swarm exits
-- Worktrees with the same name across different repositories share that name
-- Non-Git directories are unaffected by worktree settings
-- Existing worktrees with the same name are reused
-- The `claude-swarm clean` command also removes orphaned worktrees
-
-### Command Line Options
-
-```bash
-# Use default claude-swarm.yml in current directory
-claude-swarm
-
-# Specify a different configuration file
-claude-swarm start my-swarm.yml
-claude-swarm start team-config.yml
-
-# Run with --dangerously-skip-permissions for all instances
-claude-swarm --vibe
-
-# Run in non-interactive mode with a prompt
-claude-swarm -p "Implement the new user authentication feature"
-claude-swarm --prompt "Fix the bug in the payment module"
-
-# Run in interactive mode with an initial prompt
-claude-swarm -i "Review the codebase and suggest improvements"
-claude-swarm --interactive "Help me debug this test failure"
-
-# Use a custom session ID instead of auto-generated UUID
-claude-swarm --session-id my-custom-session-123
+version: 2
+nodes:
+  analyzer:
+    agent: code_analyst
+    prompt: "Analyze the codebase and identify issues"
 
-# Stream logs to stdout in prompt mode
-claude-swarm -p "Fix the tests" --stream-logs
+  fixer:
+    agent: code_fixer
+    prompt: "Fix the issues identified: {{ analyzer.output }}"
+    depends_on: [analyzer]
 
-# Run all instances in Git worktrees
-claude-swarm --worktree                  # Auto-generated name (worktree-SESSION_ID)
-claude-swarm --worktree feature-branch   # Custom worktree name
-claude-swarm -w                          # Short form
+  reviewer:
+    agent: code_reviewer
+    prompt: "Review the fixes: {{ fixer.output }}"
+    depends_on: [fixer]
 
-# Initialize a new configuration file
-claude-swarm init
-claude-swarm init --force  # Overwrite existing file
+agents:
+  code_analyst:
+    model: claude-3-5-sonnet-20241022
+    role: "Code analyst"
+    tools: [Read]
 
-# Generate configuration interactively with Claude's help
-claude-swarm generate                       # Claude names file based on swarm function
-claude-swarm generate -o my-swarm.yml       # Custom output file
-claude-swarm generate --model opus          # Use a specific model
+  code_fixer:
+    model: claude-3-5-sonnet-20241022
+    role: "Code fixer"
+    tools: [Read, Write, Edit]
 
-# Show version
-claude-swarm version
-
-# Note: The permission MCP server has been deprecated. 
-# Tool permissions are now handled through allowed_tools and disallowed_tools in your configuration.
-
-# Internal command for MCP server (used by connected instances)
-claude-swarm mcp-serve INSTANCE_NAME --config CONFIG_FILE --session-timestamp TIMESTAMP
+  code_reviewer:
+    model: claude-3-5-sonnet-20241022
+    role: "Code reviewer"
+    tools: [Read]
 ```
 
-### Session Monitoring
-
-Claude Swarm provides commands to monitor and inspect running sessions:
-
-```bash
-# List running swarm sessions with costs and uptime
-claude-swarm ps
-
-# Show detailed information about a session including instance hierarchy
-claude-swarm show 20250617_235233
+[Learn more about Node Workflows →](docs/v2/guides/complete-tutorial.md#part-5-node-workflows)
 
-# Watch live logs from a session
-claude-swarm watch 20250617_235233
+### Hooks System
 
-# Watch logs starting from the last 50 lines
-claude-swarm watch 20250617_235233 -n 50
+Run custom logic at key execution points:
 
-# List all available sessions (including completed ones)
-claude-swarm list-sessions
-claude-swarm list-sessions --limit 20
+```yaml
+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 }}'"
 
-# Clean up stale session symlinks and orphaned worktrees
-claude-swarm clean
+      # Run after successful tool execution
+      on_post_tool:
+        - run: "echo 'Tool {{ tool_name }} completed successfully'"
 
-# Remove sessions and worktrees older than 30 days
-claude-swarm clean --days 30
-```
+      # Append git diff to every user message
+      on_user_message:
+        - run: "git diff"
+          append_output_to_context: true
 
-Example output from `claude-swarm ps`:
+      # Run tests before the agent responds
+      on_pre_response:
+        - run: "npm test"
+          stop_on_error: true
 ```
-⚠️  Total cost does not include the cost of the main instance
 
-SESSION_ID       SWARM_NAME                 TOTAL_COST    UPTIME      DIRECTORY
--------------------------------------------------------------------------------
-20250617_235233  Feature Development        $0.3847       15m         .
-20250617_143022  Bug Investigation          $1.2156       1h          .
-20250617_091547  Multi-Module Dev           $0.8932       30m         ./frontend, ./backend, ./shared
-```
+[Learn more about Hooks →](docs/v2/guides/complete-tutorial.md#part-4-hooks-system)
 
-Note: The total cost shown reflects only the costs of connected instances called via MCP. The main instance cost is not tracked when running interactively.
+---
 
-Example output from `claude-swarm show`:
-```
-Session: 20250617_235233
-Swarm: Feature Development
-Total Cost: $0.3847 (excluding main instance)
-Start Directory: /Users/paulo/project
-
-Instance Hierarchy:
---------------------------------------------------
-├─ orchestrator [main] (orchestrator_e85036fc)
-   Cost: n/a (interactive) | Calls: 0
-   └─ test_archaeologist (test_archaeologist_c504ca5f)
-      Cost: $0.1925 | Calls: 1
-   └─ pr_analyst (pr_analyst_bfbefe56)
-      Cost: $0.1922 | Calls: 1
-
-Note: Main instance (orchestrator) cost is not tracked in interactive mode.
-      View costs directly in the Claude interface.
-```
+## 📊 Cost Tracking & Logging
 
-### Session Management and Restoration (Experimental)
+SwarmSDK provides built-in cost tracking and structured logging:
 
-Claude Swarm provides experimental session management with restoration capabilities. **Note: This feature is experimental and has limitations - the main instance's conversation context is not fully restored.**
+```ruby
+require 'swarm_sdk'
 
-#### Session Structure
-All session files are organized in `~/.claude-swarm/sessions/{project}/{timestamp}/`:
-- `config.yml`: Copy of the original swarm configuration
-- `state/`: Directory containing individual instance states
-  - `{instance_id}.json`: Claude session ID and status for each instance (e.g., `lead_abc123.json`)
-- `{instance_name}.mcp.json`: MCP configuration files
-- `session.log`: Human-readable request/response tracking
-- `session.log.json`: All events in JSONL format (one JSON per line)
-# Note: permissions.log is no longer generated as the permission MCP server has been deprecated
+swarm = SwarmSDK.load('my_swarm.yml')
 
-#### Listing Sessions
-View your previous Claude Swarm sessions:
+result = swarm.execute(
+  agent: :lead,
+  prompt: "Build a simple TODO app",
+  logger: Logger.new($stdout)
+)
 
-```bash
-# List recent sessions (default: 10)
-claude-swarm list-sessions
-
-# List more sessions
-claude-swarm list-sessions --limit 20
+# Access cost information
+puts "Total cost: $#{result.cost}"
+puts "Tokens used: #{result.tokens}"
 ```
 
-Output shows:
-- Session ID (timestamp)
-- Creation time
-- Main instance name
-- Number of instances
-- Configuration file used
-- Full session path
-
-#### Resuming Sessions
-Resume a previous session with all instances restored to their Claude session states:
+[Learn more about Production Features →](docs/v2/guides/complete-tutorial.md#part-7-production-features)
 
-```bash
-# Restore using the session's UUID
-claude-swarm restore 550e8400-e29b-41d4-a716-446655440000
-```
+---
 
-This will:
-1. Load the session manifest and instance states
-2. Restore the original swarm configuration
-3. Resume the main instance with its Claude session ID
-4. Restore all connected instances with their session IDs
-5. Maintain the same working directories and tool permissions
+## 🔗 Integration Examples
 
-#### How Session Restoration Works
-- Each instance's Claude session ID is automatically captured and persisted
-- Instance states are stored in separate files named by instance ID to prevent concurrency issues
-- MCP configurations are regenerated with the saved session IDs
-- The main instance uses Claude's `--resume` flag (limited effectiveness)
-- Connected instances receive their session IDs via `--claude-session-id`
+### Rails Integration
 
-**Important Limitations:**
-- The main instance's conversation history and context are not fully restored
-- Only the session ID is preserved, not the actual conversation state
-- Connected instances restore more reliably than the main instance
-- This is an experimental feature and may not work as expected
+```ruby
+# 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'))
 
-## How It Works
+    result = swarm.execute(
+      agent: :lead_reviewer,
+      prompt: "Review PR ##{pull_request_id}"
+    )
 
-1. **Configuration Parsing**: Claude Swarm reads your YAML configuration and validates it
-2. **MCP Generation**: For each instance, it generates an MCP configuration file that includes:
-   - Any explicitly defined MCP servers
-   - MCP servers for each connected instance (using `claude-swarm mcp-serve`)
-3. **Tool Permissions**: Claude Swarm manages tool permissions through configuration:
-   - Each instance's `allowed_tools` specifies which tools it can use
-   - Connected instances are accessible via `mcp__<instance_name>__*` pattern
-   - Disallowed tools take precedence over allowed tools for fine-grained control
-   - Per-instance `vibe: true` skips all permission checks for that specific instance
-4. **Session Persistence**: Claude Swarm automatically tracks session state:
-   - Generates a shared session path for all instances
-   - Each instance's Claude session ID is captured and saved
-   - Instance states are stored using instance IDs as filenames to avoid conflicts
-   - Sessions can be fully restored with all instances reconnected
-5. **Main Instance Launch**: The main instance is launched with its MCP configuration, giving it access to all connected instances
-6. **Inter-Instance Communication**: Connected instances expose themselves as MCP servers with these tools:
-   - **task**: Execute tasks using Claude Code with configurable tools and return results. The tool description includes the instance name and description (e.g., "Execute a task using Agent frontend_dev. Frontend developer specializing in React and TypeScript")
-   - **session_info**: Get current Claude session information including ID and working directory
-   - **reset_session**: Reset the Claude session for a fresh start
+    PullRequest.find(pull_request_id).update(
+      review_status: 'completed',
+      review_comments: result.message
+    )
+  end
+end
+```
 
-## Troubleshooting
+[Learn more about Rails Integration →](docs/v2/guides/rails-integration.md)
 
-### Common Issues
+### Custom Plugins
 
-**"Configuration file not found"**
-- Ensure `claude-swarm.yml` exists in the current directory
-- Or specify the path with `--config`
+```ruby
+# lib/my_plugin.rb
+class MyPlugin < SwarmSDK::Plugin
+  def on_agent_init(agent)
+    # Add custom behavior when agent initializes
+  end
 
-**"Main instance not found in instances"**
-- Check that your `main:` field references a valid instance key
+  def on_user_message(message, agent)
+    # Process user messages
+  end
 
-**"Unknown instance in connections"**
-- Verify all instances in `connections:` arrays are defined
+  def provide_tools
+    [MyCustomTool.new]
+  end
+end
 
-**Permission Errors**
-- Ensure Claude CLI is properly installed and accessible
-- Check directory permissions for specified paths
+# Register the plugin
+SwarmSDK.register_plugin(:my_plugin, MyPlugin)
+```
 
-### Debug Output
+[Learn more about Plugins →](docs/v2/guides/plugins.md)
 
-The swarm will display:
-- Session directory location (`~/.claude-swarm/sessions/{project}/{timestamp}/`)
-- Main instance details (model, directory, tools, connections)
-- The exact command being run
+---
 
-### Session Files
+## 🆚 SwarmSDK (v2) vs Claude Swarm (v1)
+
+| Feature                | SwarmSDK v2            | Claude Swarm v1                 |
+| ---------------------- | ---------------------- | ------------------------------- |
+| **Architecture**       | Single Ruby process    | Multiple Claude Code processes  |
+| **Dependencies**       | RubyLLM (Ruby-only)    | Requires Claude CLI (Node.js)   |
+| **Performance**        | Direct method calls    | MCP inter-process communication |
+| **LLM Support**        | All RubyLLM providers  | Claude + OpenAI (via MCP)       |
+| **Memory System**      | Built-in SwarmMemory   | Not available                   |
+| **Plugin System**      | Yes                    | No                              |
+| **Node Workflows**     | Yes                    | No                              |
+| **Hooks**              | 12 events, 6 actions   | Claude Code hooks only          |
+| **Context Management** | Fine-grained control   | Limited                         |
+| **Cost Tracking**      | Built-in               | Limited to MCP calls            |
+| **Interactive REPL**   | TTY-based with history | Not available                   |
+| **Ruby DSL**           | Full support           | Not available                   |
 
-Check the session directory `~/.claude-swarm/sessions/{project}/{session-id}/` for:
-- `session.log`: Human-readable logs with request/response tracking
-- `session.log.json`: All events in JSONL format (one JSON object per line)
-- `{instance}.mcp.json`: MCP configuration for each instance
-- All files for a session are kept together for easy review
+---
 
+## 📖 Looking for v1 Documentation?
 
-## Architecture
+**Claude Swarm (v1)** continues to be maintained and is still a great choice if you prefer the multi-process architecture with Claude Code instances.
 
-Claude Swarm consists of these core components:
+[View Claude Swarm v1 Documentation →](docs/v1/README.md)
 
-- **ClaudeSwarm::CLI** (`cli.rb`): Thor-based command-line interface with `start` and `mcp-serve` commands
-- **ClaudeSwarm::Configuration** (`configuration.rb`): YAML parser and validator with path expansion
-- **ClaudeSwarm::McpGenerator** (`mcp_generator.rb`): Generates MCP JSON configs for each instance
-- **ClaudeSwarm::Orchestrator** (`orchestrator.rb`): Launches the main Claude instance with shared session management
-- **ClaudeSwarm::ClaudeCodeExecutor** (`claude_code_executor.rb`): Executor for Claude Code with session persistence
-- **ClaudeSwarm::ClaudeMcpServer** (`claude_mcp_server.rb`): FastMCP-based server providing task execution, session info, and reset capabilities
+To install Claude Swarm v1:
 
-## Development
+```bash
+gem install claude_swarm
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+---
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+## 🤝 Contributing
 
-### Development Commands
+Bug reports and pull requests are welcome on GitHub at https://github.com/parruda/claude-swarm.
 
-```bash
-bin/setup              # Install dependencies
-rake test             # Run the Minitest test suite
-rake rubocop -A       # Run RuboCop linter with auto-fix
-bin/console           # Start IRB session with gem loaded
-bundle exec rake install    # Install gem locally
-bundle exec rake release    # Release gem to RubyGems.org
-rake                  # Default: runs both tests and RuboCop
-```
+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
 
-### Release Process
+---
 
-The gem is automatically published to RubyGems when a new release is created on GitHub:
+## 📄 License
 
-1. Update the version number in `lib/claude_swarm/version.rb`
-2. Update `CHANGELOG.md` with the new version's changes
-3. Commit the changes: `git commit -am "Bump version to x.y.z"`
-4. Create a version tag: `git tag -a vx.y.z -m "Release version x.y.z"`
-5. Push the changes and tag: `git push && git push --tags`
-6. The GitHub workflow will create a draft release - review and publish it
-7. Once published, the gem will be automatically built and pushed to RubyGems
+The gems are available as open source under the terms of the [MIT License](LICENSE).
 
-**Note**: You need to set up the `RUBYGEMS_AUTH_TOKEN` secret in your GitHub repository settings with your RubyGems API key.
+---
 
-## Contributing
+## 🔗 Links
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/parruda/claude-swarm.
+- **Documentation**: [docs/v2/README.md](docs/v2/README.md)
+- **GitHub Repository**: [parruda/claude-swarm](https://github.com/parruda/claude-swarm)
+- **RubyGems**:
+  - [swarm_sdk](https://rubygems.org/gems/swarm_sdk)
+  - [swarm_cli](https://rubygems.org/gems/swarm_cli)
+  - [swarm_memory](https://rubygems.org/gems/swarm_memory)
+- **Issues & Support**: [GitHub Issues](https://github.com/parruda/claude-swarm/issues)
 
-## License
+---
 
-The gem is available as open source under the terms of the [MIT License](LICENSE).
+**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)