claude_swarm 0.1.14 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84e312dafa827cdd4e47476f06dde741574b6d3592a41f0f4461758e04c7a2ed
-  data.tar.gz: dc2d25cbd5524074543902ce715dbd239a0701e450444f1012fc2c0fe96a37c9
+  metadata.gz: dc1ac6dbcc7eac54e907f574c827580275e147e42e92122d467809addb614ae9
+  data.tar.gz: d579b2a49bc0323c4704736597c1d3a9bf8e24a29c0bfe63bd21969560b4dbf9
 SHA512:
-  metadata.gz: 912831b498945b3aad80bfd8fac504e661150bce3f82aa0b69c0e74034f7d4b40faaf0f75bafabe44152fa030ec2ca85d0f7ed56e112a29c6b26f5927875c4c0
-  data.tar.gz: 7cc1775698b209bfde6564324ca8fddd85a0a7bfcb869faea7d0f8572b8c2d2e64ff55f9b393d12a7d1beca96a0f615e304de0ab53da2d99f67ce6d72fa77b13
+  metadata.gz: 20398e7167acc7f88c611da67a0d613fbfba9e225701c5dd1681f2a2ffac12bd81bbf9e4463c45564df0046edd17f3a299edbfedd1c79b0a463127c53853283f
+  data.tar.gz: be84c91452a5cc0e00ec725e9e4f3a75b8e4b94f72438a796a3a6e8f787c4c8a2c46ad857bb661c50971c2fda25ca51fe2e25fc650c3025001292dba054f293b

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.1.15]
+
+### Changed
+- **Dependency update**: Switched from `fast-mcp` to `fast-mcp-annotations` for improved tool annotation support
+- **Task tool annotations**: Added read-only, non-destructive, and closed-world hints to the task tool to allow parallel execution
+- Change the task tool description to say there's no description parameter, so claude does not try to send it.
+
 ## [0.1.14]
 
 ### Changed

data/EXAMPLES.md

@@ -0,0 +1,164 @@
+## Draft use case
+
+Imagine you're working in the storefront-web repository. Page load times doubled yesterday. You're not sure why. 
+
+To investigate today you'd use a generalized Claude. It has access to dozens of MCP tools. Tools to read data from BigQuery. Tools to crawl repositories. Tools to checkout code it needs. Tools for GitHub interactions. Tools for Kafka. Tools for file operations.
+
+You need to query BigQuery to pinpoint when the performance degraded. You also need to check recent gem upgrades. But Claude doesn't know which gem repositories to look at. You have to provide context about where to find gem source code. You have to guide it through vendor directories or gem installation paths.
+
+Claude might be able to do this. But with dozens of MCP tools loaded and lots of context it can be overwhelmed and unfocused. It struggles to pick the right tools. It struggles to understand which repos to read. It struggles to keep context in mind while switching between data analysis and code exploration.
+
+## Enter Claude-Swarm
+
+```
+Without Swarm:                         With Claude-Swarm:
+                                      
+┌──────────────────────────────┐       ┌─────────────────────────────────┐
+│           You                │       │            You                  │
+└──────────────┬───────────────┘       └──────────────┬──────────────────┘
+               │                                      │
+               v                                      v
+┌──────────────────────────────┐       ┌─────────────────────────────────┐
+│     Generalized Claude       │       │         Coordinator             │
+│                              │       │                                 │
+│ [30+ MCP Tools]              │       │      [Task delegation]          │
+│ • BigQuery tools             │       └──────────────┬──────────────────┘
+│ • File tools                 │                      │
+│ • Git tools                  │       ┌──────────────┼──────────────────┐
+│ • GitHub tools               │       │              │                  │
+│ • Kafka tools                │       v              v                  v
+│ • ...                        │     ┌────────┐  ┌────────┐    ┌────────┐
+│                              │     │Data    │  │Code    │    │PR      │
+│ Overwhelmed &                │     │Expert  │  │Expert  │    │Expert  │
+│ Context switching            │     │[BQ]    │  │[Files] │    │[GitHub]│
+└──────────────────────────────┘     └────────┘  └────────┘    └────────┘
+```
+
+Claude-swarm is one AI that can hire specialist AIs. Each specialist lives in one domain. You talk to the manager not the specialists. Manager coordinates and gives you answers.
+
+It's NOT multiple AIs running at once. It's ONE AI with "summon expert" superpowers. Experts appear and answer questions. Then they disappear.
+
+## Three Key Features
+
+### Domain Isolation
+- Data expert can pull BigQuery and performance metrics
+- Code expert lives in gem source directory
+- PR Expert only cares about writing a quality PR
+- Each expert focused on their domain. Each expert with custom context and prompts.
+
+### Selective Tool Access
+- Data expert ONLY gets BigQuery and Kafka tools (prompt it with best practices and context for querying)
+- Code expert ONLY gets file and git tools. It instantiates in a specific repo (Prompt it and provide it special context)
+- PR expert ONLY gets PR/GH tools. Can prompt it with best practices for PR submissions/context
+
+### Coordinated Intelligence
+- You ask one question
+- Get answers from multiple domains, each with specialized context and prompts
+- "Why are pages loading slowly?"
+- Data expert finds timing spike at 2pm yesterday
+- Code expert finds the problem
+- Code expert fixes the problem
+- PR Expert creates the PR with your specifications
+
+## Example Configuration
+
+```yaml
+version: 1
+swarm:
+  name: "Performance Investigation"
+  main: coordinator
+  instances:
+    coordinator:
+      description: "Lead developer coordinating performance investigation"
+      directory: ~/storefront-web
+      connections: [data_expert, code_expert, pr_expert]
+      prompt: |
+        You are a senior lead developer coordinating a performance investigation team.
+        Your role is to delegate tasks to specialists and synthesize their findings.
+        
+        When investigating performance issues:
+        1. Start with data_expert to identify when/where problems occurred
+        2. Use code_expert to analyze code changes and identify root causes
+        3. Use pr_expert to implement fixes via pull requests
+        
+        Always provide clear, actionable summaries to the user.
+      
+    data_expert:
+      description: "Analyzes performance metrics and data"
+      directory: ~/analysis
+      tools: [data_mcp_portal_find_tables, data_mcp_portal_query]
+      prompt: |
+        You are a data analyst specializing in web performance metrics.
+        You have access to BigQuery and performance monitoring data.
+        
+        When analyzing performance issues:
+        - Always use partition filters (date-based) to limit query scope
+        - Look for correlations between timing spikes and deployments
+        - Focus on p95/p99 latencies, not just averages
+        - Identify affected user segments and geographic regions
+        
+        Provide specific timestamps and quantified impact metrics.
+      
+    code_expert:
+      description: "Analyzes code, dependencies, and implementations"
+      directory: ~/gems/http-client
+      tools: [read, grep, glob, git]
+      prompt: |
+        You are a senior Ruby developer specializing in performance optimization.
+        You work primarily with gems, dependencies, and low-level implementations.
+        
+        When investigating performance issues:
+        - Check recent version changes in Gemfile.lock
+        - Look for connection pooling, caching, and resource management patterns
+        - Identify blocking I/O operations and inefficient algorithms
+        - Consider memory allocation and garbage collection impacts
+        
+        Focus on actionable code-level fixes and configuration changes.
+        
+    pr_expert:
+      description: "Creates high-quality pull requests"
+      directory: ~/storefront-web
+      tools: [read, write, gh_cli, git]
+      prompt: |
+        You are a senior developer focused on creating excellent pull requests.
+        
+        For performance fixes:
+        - Write clear, specific titles: "Fix: Enable HTTP connection pooling for 40% latency reduction"
+        - Include before/after performance metrics in description
+        - Add links to supporting data analysis
+        - Include deployment considerations and rollback plans
+        - Add relevant reviewers based on affected systems
+        
+        Always follow the team's PR template and coding standards.
+```
+
+## Investigation and Fix Flow
+
+**You:** "Why are pages loading slowly?"
+
+**Coordinator asks data_expert:** "When did latency spike and what's the impact?"
+
+**Data expert:** 
+```sql
+-- Query shows latency spike at 2:15 PM yesterday
+-- P95 response time increased from 250ms to 890ms
+-- Affecting 15% of traffic, primarily checkout flows
+```
+
+**Coordinator asks code_expert:** "What changed around 2:15 PM yesterday that could cause this?"
+
+**Code expert:** 
+```ruby
+# Gemfile.lock shows http-client gem updated from 3.1.9 to 3.2.0 at 2:14 PM
+# Version 3.2.0 changelog: "Removed automatic connection pooling for thread safety"
+# Now creates new HTTP connection per request instead of reusing connections
+```
+
+**Coordinator:** "The http-client gem update removed connection pooling, causing 3x latency increase during checkout."
+
+**You:** "Fix this and create a PR"
+
+**Code expert:** "Two options: downgrade to 3.1.9 or configure explicit pooling with `pool_size: 10` in initializer"
+
+**PR expert:** "Created PR #1234: 'Fix: Enable HTTP connection pooling for 40% latency reduction' with performance benchmarks and rollback plan"
+

data/README.md

@@ -1,6 +1,6 @@
 # Claude Swarm
 
-[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=0.1.13)](https://badge.fury.io/rb/claude_swarm)
+[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=0.1.14)](https://badge.fury.io/rb/claude_swarm)
 [![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.

data/example/test-generation.yml

@@ -36,7 +36,7 @@ swarm:
       description: "Unit test specialist focusing on models, services, and isolated business logic with Minitest"
       directory: ./spec
       model: opus
-      connections: [test_architect, factory_specialist]
+      connections: [factory_specialist]
       prompt: |
         You are a Rails unit testing expert specializing in Minitest. Your focus areas:
         
@@ -76,7 +76,7 @@ swarm:
       description: "Integration test specialist for controllers, API endpoints, and request specs"
       directory: ./spec
       model: opus
-      connections: [test_architect, factory_specialist]
+      connections: [factory_specialist]
       prompt: |
         You are a Rails integration testing expert focusing on request specs and controller tests. Your expertise:
         
@@ -117,7 +117,6 @@ swarm:
       description: "System test specialist for end-to-end user flows and JavaScript interactions"
       directory: ./spec/system
       model: opus
-      connections: [test_architect]
       prompt: |
         You are a Rails system testing expert using Capybara and Selenium. Your specialization:
         
@@ -161,7 +160,6 @@ swarm:
       description: "Test data specialist managing factories, traits, and test data generation"
       directory: ./spec/factories
       model: opus
-      connections: [test_architect, unit_test_expert, integration_test_expert]
       prompt: |
         You are a Rails test data expert specializing in FactoryBot. Your responsibilities:
         
@@ -206,7 +204,6 @@ swarm:
       description: "Test quality assurance specialist ensuring best practices, coverage, and maintainability"
       directory: .
       model: opus
-      connections: [test_architect]
       prompt: |
         You are a Rails test quality reviewer ensuring all tests meet the highest standards. Your review criteria:
         

data/lib/claude_swarm/claude_mcp_server.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "fast_mcp"
+require "fast_mcp_annotations"
 require "json"
 require_relative "claude_code_executor"
 require_relative "task_tool"

data/lib/claude_swarm/permission_mcp_server.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
-require "fast_mcp"
+require "fast_mcp_annotations"
 require "logger"
 require "fileutils"
 require_relative "permission_tool"

data/lib/claude_swarm/permission_tool.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
-require "fast_mcp"
+require "fast_mcp_annotations"
 
 module ClaudeSwarm
   class PermissionTool < FastMcp::Tool

data/lib/claude_swarm/task_tool.rb

@@ -3,7 +3,8 @@
 module ClaudeSwarm
   class TaskTool < FastMcp::Tool
     tool_name "task"
-    description "Execute a task using Claude Code"
+    description "Execute a task using Claude Code. There is no description parameter."
+    annotations(readOnlyHint: true, openWorldHint: false, destructiveHint: false)
 
     arguments do
       required(:prompt).filled(:string).description("The task or question for the agent")

data/lib/claude_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeSwarm
-  VERSION = "0.1.14"
+  VERSION = "0.1.15"
 end

data/llms.txt

@@ -0,0 +1,384 @@
+# claude-swarm
+claude-swarm is a Ruby gem that 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).
+## Purpose
+claude-swarm allows you to:
+- Create teams of specialized AI agents working together
+- Restrict tool access per agent for safety and focus
+- Organize agents in tree-like hierarchies for delegation
+- Maintain separate working directories per agent
+- Enable inter-agent communication via MCP protocol
+- Track sessions and restore previous swarm states
+## Installation
+```bash
+# Install via RubyGems
+gem install claude_swarm
+# Or add to Gemfile
+gem 'claude_swarm'
+bundle install
+```
+### Prerequisites
+- Ruby 3.2.0 or higher
+- Claude CLI installed and configured (`claude` command available)
+- Any MCP servers you plan to use (optional)
+## Quick Start
+1. Initialize a configuration:
+```bash
+claude-swarm init
+```
+2. Or create `claude-swarm.yml`:
+```yaml
+version: 1
+swarm:
+  name: "My Dev Team"
+  main: lead
+  instances:
+    lead:
+      description: "Team lead coordinating development"
+      directory: .
+      model: opus
+      connections: [frontend, backend]
+      allowed_tools: [Read, Edit, Bash]
+      prompt: "You coordinate the team"
+    frontend:
+      description: "Frontend developer"
+      directory: ./frontend
+      model: sonnet
+      allowed_tools: [Read, Edit, Write, "Bash(npm:*)"]
+```
+3. Start the swarm:
+```bash
+claude-swarm
+claude-swarm --vibe  # Allow all tools (dangerous!)
+```
+## Key Concepts
+### Swarm
+A collection of Claude instances (agents) working together. One instance is designated as "main" - the entry point that coordinates others.
+### Instance
+An individual Claude Code agent with:
+- **description** (required): Role and responsibilities
+- **directory**: Working directory context
+- **model**: Claude model (opus/sonnet/haiku)
+- **connections**: Other instances it can delegate to
+- **allowed_tools**: Tools this instance can use
+- **disallowed_tools**: Explicitly denied tools (override allowed)
+- **prompt**: Custom system prompt
+- **vibe**: Skip permission checks for this instance
+- **mcps**: Additional MCP servers
+### MCP (Model Context Protocol)
+Protocol enabling Claude to use external tools. claude-swarm uses MCP for:
+- Inter-instance communication (task delegation)
+- Permission management
+- Additional tool integration
+## Configuration Format
+```yaml
+version: 1
+swarm:
+  name: "Swarm Name"
+  main: instance_key  # Entry point instance
+  instances:
+    instance_name:
+      description: "Agent role description"  # REQUIRED
+      directory: ~/path/to/dir              # Working directory
+      model: opus                           # opus/sonnet/haiku
+      connections: [other1, other2]         # Connected instances
+      prompt: "Custom system prompt"        # Additional instructions
+      vibe: false                          # Skip permissions (default: false)
+      allowed_tools:                       # Tools this instance can use
+        - Read
+        - Edit
+        - Write
+        - Bash
+        - WebSearch
+        - WebFetch
+      disallowed_tools:                    # Explicitly deny patterns
+        - "Write(*.log)"
+        - "Bash(rm:*)"
+      mcps:                                # Additional MCP servers
+        - name: database
+          type: stdio
+          command: /path/to/mcp
+          args: ["--flag"]
+          env:
+            API_KEY: "value"
+        - name: api
+          type: sse
+          url: https://example.com/mcp
+```
+## Tool Patterns
+Tools can be restricted using patterns:
+- `Bash(npm:*)` - Only npm commands in Bash
+- `Write(*.md)` - Only write markdown files
+- `mcp__frontend__*` - All frontend MCP tools
+- `Read` - Unrestricted Read tool
+Disallowed tools always override allowed tools.
+## Inter-Instance Communication
+Instances communicate via the `task` tool exposed by connected instances:
+### Task Tool
+When instance A connects to instance B, A can use:
+```
+mcp__B__task
+```
+**Parameters:**
+- `prompt` (required): The task or question for the agent
+- `new_session` (optional): Start fresh session (default: false)
+- `system_prompt` (optional): Override system prompt for this request
+**Example Usage:**
+```
+Main instance: "Please analyze the frontend performance"
+→ Uses mcp__frontend__task with prompt "Analyze performance bottlenecks"
+→ Frontend instance executes with its tools and returns results
+```
+### Session Info Tool
+```
+mcp__B__session_info
+```
+Returns current Claude session ID and working directory.
+### Reset Session Tool
+```
+mcp__B__reset_session
+```
+Resets the Claude session for a fresh start.
+## Commands
+### Start Swarm
+```bash
+# Default configuration
+claude-swarm
+# Custom configuration
+claude-swarm --config team.yml
+claude-swarm -c my-swarm.yml
+# Skip all permissions (dangerous!)
+claude-swarm --vibe
+# Non-interactive mode with prompt
+claude-swarm -p "Build a login feature"
+claude-swarm --prompt "Fix the bug" --stream-logs
+# Resume session
+claude-swarm --session-id 20241225_120000
+claude-swarm --session-id ~/.claude-swarm/sessions/project/20241225_120000
+```
+### List Sessions
+```bash
+# List recent sessions (default: 10)
+claude-swarm list-sessions
+# List more sessions
+claude-swarm list-sessions --limit 20
+# List for specific project
+claude-swarm list-sessions --project myapp
+```
+### Other Commands
+```bash
+# Initialize starter config
+claude-swarm init
+# Show version
+claude-swarm version
+# Start permission MCP server (for testing)
+claude-swarm tools-mcp --allowed-tools 'Read,Edit,mcp__*'
+# Internal MCP serve command (used by swarm)
+claude-swarm mcp-serve -n NAME -d DIR -m MODEL [options]
+```
+## Session Management
+### Session Structure
+Sessions are stored in `~/.claude-swarm/sessions/{project}/{timestamp}/`:
+```
+20241225_143022/
+├── config.yml          # Swarm configuration used
+├── state/              # Instance states
+│   ├── lead_abc123.json    # Lead instance state
+│   └── frontend_def456.json # Frontend instance state
+├── lead.mcp.json       # MCP configurations
+├── frontend.mcp.json
+├── session.log         # Human-readable logs
+├── session.log.json    # JSONL format events
+└── permissions.log     # Permission decisions
+```
+### Session Files
+- **config.yml**: Copy of swarm configuration
+- **state/*.json**: Claude session IDs for each instance
+- **session.log**: Request/response tracking
+- **session.log.json**: All events in JSONL format
+- **permissions.log**: Tool permission checks
+### Restoring Sessions (Experimental)
+```bash
+claude-swarm --session-id 20241225_143022
+```
+**Limitations:**
+- Main instance conversation context not fully restored
+- Only session IDs preserved, not full state
+- Connected instances restore more reliably
+## Debugging
+### Enable Debug Output
+```bash
+claude-swarm --debug
+```
+### Check Logs
+```bash
+# Session logs
+cat ~/.claude-swarm/sessions/PROJECT/TIMESTAMP/session.log
+cat ~/.claude-swarm/sessions/PROJECT/TIMESTAMP/permissions.log
+# JSONL events
+cat ~/.claude-swarm/sessions/PROJECT/TIMESTAMP/session.log.json
+```
+### Common Issues
+**"Configuration file not found"**
+- Ensure `claude-swarm.yml` exists
+- Or use `--config path/to/config.yml`
+**"Main instance not found"**
+- Check `main:` references valid instance key
+**"Circular dependency detected"**
+- Remove circular connections between instances
+**"Permission denied for tool X"**
+- Check `allowed_tools` includes the tool
+- Check `disallowed_tools` doesn't block it
+- Use `--vibe` to skip permissions (dangerous)
+**"MCP server failed to start"**
+- Check the command/URL is correct
+- Verify MCP server is installed
+- Check logs for error details
+## Common Patterns
+### Full-Stack Team
+```yaml
+instances:
+  architect:
+    description: "System architect"
+    connections: [frontend_lead, backend_lead, devops]
+  frontend_lead:
+    description: "Frontend team lead"
+    connections: [ui_dev, ux_designer]
+  backend_lead:
+    description: "Backend team lead"
+    connections: [api_dev, db_admin]
+```
+### Investigation Team
+```yaml
+instances:
+  investigator:
+    description: "Lead investigator"
+    connections: [data_analyst, code_expert, test_runner]
+  data_analyst:
+    description: "Analyzes metrics and logs"
+    allowed_tools: ["Bash(grep:*, awk:*)", Read]
+  code_expert:
+    description: "Reviews code changes"
+    allowed_tools: [Read, Grep, Glob]
+```
+### Mixed Permissions
+```yaml
+instances:
+  trusted_lead:
+    description: "Trusted lead with full access"
+    vibe: true  # Skip all permission checks
+  restricted_worker:
+    description: "Limited access worker"
+    allowed_tools: [Read]  # Read-only access
+  normal_worker:
+    description: "Standard developer"
+    allowed_tools: [Read, Edit, Write]
+```
+## Complete Example
+### Performance Investigation Swarm
+```yaml
+version: 1
+swarm:
+  name: "Performance Investigation"
+  main: coordinator
+  instances:
+    coordinator:
+      description: "Coordinates performance investigation"
+      directory: ~/projects/webapp
+      model: opus
+      connections: [metrics_analyst, code_reviewer, fix_implementer]
+      allowed_tools: [Read]
+      prompt: |
+        You coordinate a performance investigation team.
+        1. Use metrics_analyst to identify when/where issues occur
+        2. Use code_reviewer to find root causes
+        3. Use fix_implementer to create solutions
+        
+    metrics_analyst:
+      description: "Analyzes performance metrics"
+      directory: ~/projects/webapp/logs
+      model: sonnet
+      allowed_tools: [Read, "Bash(grep:*, awk:*, sort:*)"]
+      prompt: |
+        You analyze logs and metrics for performance issues.
+        Focus on response times, error rates, and patterns.
+        
+    code_reviewer:
+      description: "Reviews code for performance issues"
+      directory: ~/projects/webapp/src
+      model: opus
+      allowed_tools: [Read, Grep, Glob]
+      prompt: |
+        You review code for performance bottlenecks.
+        Look for N+1 queries, missing indexes, inefficient algorithms.
+        
+    fix_implementer:
+      description: "Implements performance fixes"
+      directory: ~/projects/webapp
+      model: opus
+      allowed_tools: [Read, Edit, Write, Bash]
+      prompt: |
+        You implement optimizations and fixes.
+        Always add tests and measure improvements.
+```
+### Usage Flow
+1. **User**: "The checkout page is slow"
+2. **Coordinator** → **metrics_analyst**: "Find checkout performance metrics"
+3. **Metrics analyst** returns: "Latency spike at 2pm, 3x increase"
+4. **Coordinator** → **code_reviewer**: "What changed around 2pm?"
+5. **Code reviewer** returns: "HTTP client gem updated, removed connection pooling"
+6. **Coordinator** → **fix_implementer**: "Add connection pooling configuration"
+7. **Fix implementer**: Creates fix and tests
+## How It Works
+1. **Configuration Parsing**: Validates YAML and expands paths
+2. **MCP Generation**: Creates MCP configs in `.claude-swarm/`
+3. **Permission Setup**: Adds permission MCP server (unless vibe mode)
+4. **Instance Launch**: Starts main instance with connections
+5. **Task Delegation**: Main instance uses mcp__instance__task tools
+6. **Session Tracking**: All activity logged to session directory
+## Development
+```bash
+# Setup
+bin/setup
+# Run tests
+rake test
+# Lint code
+rake rubocop -A
+# Console
+bin/console
+# Install locally
+bundle exec rake install
+# Release to RubyGems
+bundle exec rake release
+```
+## Architecture
+- **CLI** (`cli.rb`): Thor-based commands
+- **Configuration** (`configuration.rb`): YAML parser/validator
+- **McpGenerator** (`mcp_generator.rb`): Creates MCP JSON configs
+- **Orchestrator** (`orchestrator.rb`): Launches main instance
+- **ClaudeCodeExecutor** (`claude_code_executor.rb`): Executes Claude
+- **ClaudeMcpServer** (`claude_mcp_server.rb`): Inter-instance MCP
+- **PermissionMcpServer** (`permission_mcp_server.rb`): Tool permissions
+## Environment Variables
+- `CLAUDE_SWARM_HOME`: Override session storage location (default: ~/.claude-swarm)
+- `ANTHROPIC_MODEL`: Default Claude model if not specified
+## Security Considerations
+- Tool restrictions enforced at permission layer
+- All permissions logged for audit
+- Vibe mode bypasses ALL restrictions - use carefully
+- Session files may contain sensitive data
+- Each instance runs with its directory context
+- MCP servers inherit instance permissions
+## Limitations
+- Tree hierarchy only (no circular dependencies)
+- Session restoration is experimental
+- Main instance context not fully preserved
+- All paths expand relative to execution directory
+- MCP servers must support required protocol
+## Best Practices
+1. **Clear Descriptions**: Help agents understand their roles
+2. **Focused Tools**: Give each instance only needed tools
+3. **Directory Context**: Place instances in relevant directories
+4. **Prompt Engineering**: Use prompts to guide behavior
+5. **Test Configurations**: Start simple, add complexity gradually
+6. **Monitor Logs**: Check session logs for issues
+7. **Use Vibe Sparingly**: Only for trusted operations

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.1.15
 platform: ruby
 authors:
 - Paulo Arruda
@@ -24,7 +24,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
-  name: fast-mcp
+  name: fast-mcp-annotations
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -54,6 +54,7 @@ files:
 - ".ruby-version"
 - CHANGELOG.md
 - CLAUDE.md
+- EXAMPLES.md
 - LICENSE
 - README.md
 - RELEASING.md
@@ -79,6 +80,7 @@ files:
 - lib/claude_swarm/session_path.rb
 - lib/claude_swarm/task_tool.rb
 - lib/claude_swarm/version.rb
+- llms.txt
 - sdk-docs.md
 homepage: https://github.com/parruda/claude-swarm
 licenses: []