claude_swarm 0.1.14 → 0.1.16

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/cli.rb

@@ -6,7 +6,6 @@ require_relative "configuration"
 require_relative "mcp_generator"
 require_relative "orchestrator"
 require_relative "claude_mcp_server"
-require_relative "permission_mcp_server"
 
 module ClaudeSwarm
   class CLI < Thor
@@ -78,10 +77,12 @@ module ClaudeSwarm
                            desc: "System prompt for the instance"
     method_option :description, type: :string,
                                 desc: "Description of the instance's role"
-    method_option :tools, aliases: "-t", type: :array,
-                          desc: "Allowed tools for the instance"
+    method_option :allowed_tools, aliases: "-t", type: :array,
+                                  desc: "Allowed tools for the instance"
     method_option :disallowed_tools, type: :array,
                                      desc: "Disallowed tools for the instance"
+    method_option :connections, type: :array,
+                                desc: "Connections to other instances"
     method_option :mcp_config_path, type: :string,
                                     desc: "Path to MCP configuration file"
     method_option :debug, type: :boolean, default: false,
@@ -103,8 +104,9 @@ module ClaudeSwarm
         model: options[:model],
         prompt: options[:prompt],
         description: options[:description],
-        tools: options[:tools] || [],
+        allowed_tools: options[:allowed_tools] || [],
         disallowed_tools: options[:disallowed_tools] || [],
+        connections: options[:connections] || [],
         mcp_config_path: options[:mcp_config_path],
         vibe: options[:vibe],
         instance_id: options[:instance_id],
@@ -265,22 +267,6 @@ module ClaudeSwarm
       say "  claude-swarm --session-id <session-id>", :cyan
     end
 
-    desc "tools-mcp", "Start a permission management MCP server for tool access control"
-    method_option :allowed_tools, aliases: "-t", type: :string,
-                                  desc: "Comma-separated list of allowed tool patterns (supports wildcards)"
-    method_option :disallowed_tools, type: :string,
-                                     desc: "Comma-separated list of disallowed tool patterns (supports wildcards)"
-    method_option :debug, type: :boolean, default: false,
-                          desc: "Enable debug output"
-    def tools_mcp
-      server = PermissionMcpServer.new(allowed_tools: options[:allowed_tools], disallowed_tools: options[:disallowed_tools])
-      server.start
-    rescue StandardError => e
-      error "Error starting permission MCP server: #{e.message}"
-      error e.backtrace.join("\n") if options[:debug]
-      exit 1
-    end
-
     default_task :start
 
     private

data/lib/claude_swarm/mcp_generator.rb

@@ -68,9 +68,6 @@ module ClaudeSwarm
         )
       end
 
-      # Add permission MCP server if not in vibe mode (global or instance-specific)
-      mcp_servers["permissions"] = build_permission_mcp_config(instance[:tools], instance[:disallowed_tools]) unless @vibe || instance[:vibe]
-
       config = {
         "instance_id" => @instance_ids[name],
         "instance_name" => name,
@@ -115,10 +112,12 @@ module ClaudeSwarm
 
       args.push("--description", instance[:description]) if instance[:description]
 
-      args.push("--tools", instance[:tools].join(",")) if instance[:tools] && !instance[:tools].empty?
+      args.push("--allowed-tools", instance[:allowed_tools].join(",")) if instance[:allowed_tools] && !instance[:allowed_tools].empty?
 
       args.push("--disallowed-tools", instance[:disallowed_tools].join(",")) if instance[:disallowed_tools] && !instance[:disallowed_tools].empty?
 
+      args.push("--connections", instance[:connections].join(",")) if instance[:connections] && !instance[:connections].empty?
+
       args.push("--mcp-config-path", mcp_config_path(name))
 
       args.push("--calling-instance", calling_instance) if calling_instance
@@ -162,23 +161,5 @@ module ClaudeSwarm
         # Skip invalid state files
       end
     end
-
-    def build_permission_mcp_config(allowed_tools, disallowed_tools)
-      exe_path = "claude-swarm"
-
-      args = ["tools-mcp"]
-
-      # Add allowed tools if specified
-      args.push("--allowed-tools", allowed_tools.join(",")) if allowed_tools && !allowed_tools.empty?
-
-      # Add disallowed tools if specified
-      args.push("--disallowed-tools", disallowed_tools.join(",")) if disallowed_tools && !disallowed_tools.empty?
-
-      {
-        "type" => "stdio",
-        "command" => exe_path,
-        "args" => args
-      }
-    end
   end
 end

data/lib/claude_swarm/orchestrator.rb

@@ -91,7 +91,7 @@ module ClaudeSwarm
         puts "🚀 Launching main instance: #{@config.main_instance}"
         puts "   Model: #{main_instance[:model]}"
         puts "   Directory: #{main_instance[:directory]}"
-        puts "   Allowed tools: #{main_instance[:tools].join(", ")}" if main_instance[:tools].any?
+        puts "   Allowed tools: #{main_instance[:allowed_tools].join(", ")}" if main_instance[:allowed_tools].any?
         puts "   Disallowed tools: #{main_instance[:disallowed_tools].join(", ")}" if main_instance[:disallowed_tools]&.any?
         puts "   Connections: #{main_instance[:connections].join(", ")}" if main_instance[:connections].any?
         puts "   😎 Vibe mode ON for this instance" if main_instance[:vibe]
@@ -208,9 +208,17 @@ module ClaudeSwarm
       if @vibe || instance[:vibe]
         parts << "--dangerously-skip-permissions"
       else
+        # Build allowed tools list including MCP connections
+        allowed_tools = instance[:allowed_tools].dup
+
+        # Add mcp__instance_name for each connection
+        instance[:connections].each do |connection_name|
+          allowed_tools << "mcp__#{connection_name}"
+        end
+
         # Add allowed tools if any
-        if instance[:tools].any?
-          tools_str = instance[:tools].join(",")
+        if allowed_tools.any?
+          tools_str = allowed_tools.join(",")
           parts << "--allowedTools"
           parts << tools_str
         end
@@ -221,10 +229,6 @@ module ClaudeSwarm
           parts << "--disallowedTools"
           parts << disallowed_tools_str
         end
-
-        # Add permission prompt tool unless in vibe mode
-        parts << "--permission-prompt-tool"
-        parts << "mcp__permissions__check_permission"
       end
 
       if instance[:prompt]

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(read_only_hint: true, open_world_hint: false, destructive_hint: false)
 
     arguments do
       required(:prompt).filled(:string).description("The task or question for the agent")
@@ -21,11 +22,14 @@ module ClaudeSwarm
       }
 
       # Add allowed tools from instance config
-      options[:allowed_tools] = instance_config[:tools] if instance_config[:tools]&.any?
+      options[:allowed_tools] = instance_config[:allowed_tools] if instance_config[:allowed_tools]&.any?
 
       # Add disallowed tools from instance config
       options[:disallowed_tools] = instance_config[:disallowed_tools] if instance_config[:disallowed_tools]&.any?
 
+      # Add connections from instance config
+      options[:connections] = instance_config[:connections] if instance_config[:connections]&.any?
+
       response = executor.execute(prompt, options)
 
       # Return just the result text as expected by MCP

data/lib/claude_swarm/version.rb

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

data/lib/claude_swarm.rb

@@ -7,8 +7,6 @@ require_relative "claude_swarm/mcp_generator"
 require_relative "claude_swarm/orchestrator"
 require_relative "claude_swarm/claude_code_executor"
 require_relative "claude_swarm/claude_mcp_server"
-require_relative "claude_swarm/permission_tool"
-require_relative "claude_swarm/permission_mcp_server"
 require_relative "claude_swarm/session_path"
 require_relative "claude_swarm/session_info_tool"
 require_relative "claude_swarm/reset_session_tool"

data/llms.txt

@@ -0,0 +1,383 @@
+# 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
+**"Tool not allowed"**
+- Check `allowed_tools` includes the tool
+- Check `disallowed_tools` doesn't block it
+- Use `vibe: true` to skip all checks (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 through configuration
+- Vibe mode bypasses ALL restrictions - use carefully
+- Session files may contain sensitive data
+- Each instance runs with its directory context
+- MCP servers inherit instance tool configurations
+## 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.16
 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,10 +54,12 @@ files:
 - ".ruby-version"
 - CHANGELOG.md
 - CLAUDE.md
+- EXAMPLES.md
 - LICENSE
 - README.md
 - RELEASING.md
 - Rakefile
+- claude-sdk-docs.md
 - claude-swarm.yml
 - example/claude-swarm.yml
 - example/microservices-team.yml
@@ -71,15 +73,13 @@ files:
 - lib/claude_swarm/configuration.rb
 - lib/claude_swarm/mcp_generator.rb
 - lib/claude_swarm/orchestrator.rb
-- lib/claude_swarm/permission_mcp_server.rb
-- lib/claude_swarm/permission_tool.rb
 - lib/claude_swarm/process_tracker.rb
 - lib/claude_swarm/reset_session_tool.rb
 - lib/claude_swarm/session_info_tool.rb
 - lib/claude_swarm/session_path.rb
 - lib/claude_swarm/task_tool.rb
 - lib/claude_swarm/version.rb
-- sdk-docs.md
+- llms.txt
 homepage: https://github.com/parruda/claude-swarm
 licenses: []
 metadata: