claude_swarm 1.0.0 → 1.0.2

data/examples/v2/swarm.yml

@@ -0,0 +1,71 @@
+version: 2
+
+swarm:
+  name: "Simple Swarm"
+  # all_agents:
+  #   permissions:
+  #     Bash:
+  #       denied_commands: ["^ls.*"]
+  #       allowed_paths: ["tmp/LOL/**/*"]
+  #     Read:
+  #       denied_paths: ["lib/**/*"]
+  lead: coordinator
+
+  agents:
+    # Coordinator agent - orchestrates file operations and delegates to worker
+    coordinator:
+      description: "A helpful assistant"
+      model: claude-sonnet-4-5-20250929
+      provider: openai
+      parameters:
+        temperature: 1.0
+      mcp_servers:
+      - name: filesystem
+        type: stdio
+        command: npx
+        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        env: {}
+        timeout: 30  # seconds
+      # api_version: "v1/responses"
+
+      # Coordinator has read-only tools plus ability to delegate
+      # TodoWrite helps track progress on complex multi-step tasks
+      tools:
+        - Bash
+        # - Write
+
+      # Can delegate work to the worker agent
+      delegates_to:
+        - worker
+
+      directory: .
+
+      system_prompt: |
+       You are a helpful assistant.
+
+    # Worker agent - performs file write/edit operations in tmp/ directory only
+    worker:
+      description: "A helpful assistant"
+      model: claude-sonnet-4-5-20250929
+      provider: openai
+      # api_version: "v1/responses"
+
+      # Worker has all tools including Write and Edit
+      # TodoWrite helps track progress, MultiEdit enables multiple replacements
+      tools:
+        - Read
+        # - Write
+        # - Edit
+        # - MultiEdit
+        - Grep
+        - Glob
+        - TodoWrite
+
+      # Worker doesn't delegate - it's a leaf node
+      delegates_to: []
+
+      directory: .
+
+      system_prompt: |
+        You are a helpful assistant.
+

data/examples/v2/swarm_with_hooks.yml

@@ -0,0 +1,61 @@
+# SwarmSDK Example: YAML Hooks Feature
+#
+# This example demonstrates YAML hooks that execute shell commands at various
+# lifecycle points. Both YAML and Ruby DSL support hooks using the same terminology.
+#
+# YAML hooks: Shell commands defined in YAML files
+# DSL hooks: Ruby blocks defined in code
+#
+# Setup: export OPENAI_API_KEY=your-api-key
+# Run: swarm run lib/swarm_sdk/examples/swarm_with_hooks.yml -p "your prompt"
+#
+# Or programmatically:
+#   swarm = SwarmSDK::Swarm.load("lib/swarm_sdk/examples/swarm_with_hooks.yml")
+#   result = swarm.execute("your prompt")
+
+version: 2
+
+swarm:
+  name: "Development Team with Hooks"
+  lead: backend
+
+  # Swarm-level hooks (only swarm_start and swarm_stop)
+  # These run at swarm lifecycle events
+  hooks:
+    swarm_start:
+      - type: command
+        command: "echo 'Swarm starting: Development Team' > tmp/log.txt"
+        timeout: 5
+
+    swarm_stop:
+      - type: command
+        command: "echo 'Swarm completed successfully' >> tmp/log.txt"
+        timeout: 5
+
+  agents:
+    backend:
+      description: "Backend developer with custom hooks"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a backend developer. Build APIs and databases."
+      tools:
+        - Read
+        - Glob
+      hooks:
+        user_prompt:
+          - type: command
+            command: "echo 'Cannot proceed with this prompt' >&2;exit 2"
+            timeout: 10
+        pre_tool_use:
+          - matcher: "Read"
+            type: command
+            command: "echo \"you can't read files\" >&2; echo \"Can't read files!\" >> tmp/log.txt; exit 2"
+            timeout: 10
+          - matcher: "Glob"
+            type: command
+            command: "echo \"you can't use Glob, not authorized\" >&2; echo cannot use Glob, not authorized >> tmp/log.txt; exit 2"
+            timeout: 10
+          - matcher: "Grep"
+            type: command
+            command: "echo \"you can't use Grep, not authorized\" >&2; echo cannot use Grep, not authorized >> tmp/log.txt; exit 2"
+            timeout: 10

data/examples/v2/swarm_with_hooks_simple.yml

@@ -0,0 +1,25 @@
+version: 2
+
+swarm:
+  name: "Simple Hooks Test"
+  lead: backend
+
+  hooks:
+    swarm_start:
+      - type: command
+        command: "echo 'Swarm starting' >&2"
+
+  agents:
+    backend:
+      description: "Backend developer"
+      model: gpt-5
+      system_prompt: "You are a backend developer."
+      tools:
+        - Read
+        - Bash
+
+      hooks:
+        pre_tool_use:
+          - matcher: "Bash"
+            type: command
+            command: "python3 lib/swarm_sdk/examples/hooks/validate_bash.py"

data/examples/v2/think_tool_demo.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Think Tool Demonstration
+#
+# This example demonstrates how to use the Think tool for explicit reasoning.
+# The Think tool allows agents to "think out loud" by recording thoughts that
+# become part of the conversation context, leading to better reasoning and
+# problem-solving outcomes.
+#
+# Usage:
+#   swarm run examples/v2/think_tool_demo.rb
+#   swarm run examples/v2/think_tool_demo.rb "Calculate the optimal caching strategy for this API"
+#   swarm run examples/v2/think_tool_demo.rb -p "Design a database schema for an e-commerce system"
+
+SwarmSDK.build do
+  name "Think Tool Demo"
+  lead :problem_solver
+
+  # Problem solver agent that uses the Think tool frequently
+  agent :problem_solver do
+    coding_agent(true)
+    description "Problem solver who thinks through solutions step-by-step"
+    model "gpt-5-mini"
+    provider "openai"
+
+    system_prompt <<~PROMPT
+      You are a thoughtful problem solver who uses explicit reasoning to tackle complex tasks.
+
+      **IMPORTANT: Use the Think tool frequently throughout your work!**
+
+      The Think tool allows you to write down your thoughts, plans, and intermediate
+      calculations. This leads to significantly better outcomes because:
+
+      1. It helps you break down complex problems into manageable steps
+      2. It allows you to track your progress and plan next actions
+      3. It helps with arithmetic and calculations
+      4. It maintains context across multiple steps
+
+      **Recommended usage pattern:**
+      1. THINK before starting any task - understand the problem and create a plan
+      2. THINK after reading files or getting information - process what you learned
+      3. THINK between steps - track progress and decide next actions
+      4. THINK when doing calculations - work through math step by step
+      5. THINK when encountering complexity - break down the problem
+
+      Example workflow for a coding task:
+      1. Think: "User wants X. Let me break this into: 1) Read code, 2) Identify changes, 3) Implement, 4) Test"
+      2. Read relevant files
+      3. Think: "I see the structure. Key files are A, B. I need to modify B's function foo()"
+      4. Make changes
+      5. Think: "Changes made. Next: verify the tests pass"
+      6. Run tests
+      7. Think: "Tests pass. Task complete."
+
+      For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+
+      Remember: Successful agents use Think 5-10 times per task on average!
+    PROMPT
+
+    tools :Think, :Read, :Write, :Edit, :Bash, :Grep, :Glob
+  end
+end

data/exe/swarm

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "swarm_cli"
+
+SwarmCLI::CLI.start(ARGV)

data/lib/claude_swarm/claude_mcp_server.rb

@@ -52,12 +52,6 @@ module ClaudeSwarm
     end
 
     def start
-      # Track this process
-      if @executor.session_path && File.exist?(@executor.session_path)
-        tracker = ProcessTracker.new(@executor.session_path)
-        tracker.track_pid(Process.pid, "mcp_#{@instance_config[:name]}")
-      end
-
       server = FastMcp::Server.new(
         name: @instance_config[:name],
         version: "1.0.0",

data/lib/claude_swarm/cli.rb

@@ -3,6 +3,7 @@
 module ClaudeSwarm
   class CLI < Thor
     include SystemUtils
+
     class << self
       def exit_on_failure?
         true
@@ -458,9 +459,15 @@ module ClaudeSwarm
         next unless File.exist?(config_file)
 
         # Load the config to get swarm info
-        config_data = YAML.load_file(config_file)
-        swarm_name = config_data.dig("swarm", "name") || "Unknown"
-        main_instance = config_data.dig("swarm", "main") || "Unknown"
+        begin
+          config_data = YamlLoader.load_config_file(config_file)
+          swarm_name = config_data.dig("swarm", "name") || "Unknown"
+          main_instance = config_data.dig("swarm", "main") || "Unknown"
+        rescue ClaudeSwarm::Error => e
+          # Warn about corrupted config files but continue
+          say_error("⚠️ Skipping session #{session_id} - #{e.message}")
+          next
+        end
 
         mcp_files = Dir.glob(File.join(session_path, "*.mcp.json"))
 

data/lib/claude_swarm/commands/ps.rb

@@ -10,22 +10,9 @@ module ClaudeSwarm
           return
         end
 
-        sessions = []
-
-        # Read all symlinks in run directory
-        Dir.glob("#{run_dir}/*").each do |symlink|
-          next unless File.symlink?(symlink)
-
-          begin
-            session_dir = File.readlink(symlink)
-            # Skip if target doesn't exist (stale symlink)
-            next unless Dir.exist?(session_dir)
-
-            session_info = parse_session_info(session_dir)
-            sessions << session_info if session_info
-          rescue StandardError
-            # Skip problematic symlinks
-          end
+        # Read all symlinks in run directory and process them
+        sessions = Dir.glob("#{run_dir}/*").filter_map do |symlink|
+          process_symlink(symlink)
         end
 
         if sessions.empty?
@@ -83,14 +70,28 @@ module ClaudeSwarm
 
       private
 
-      def parse_session_info(session_dir)
+      def process_symlink(symlink)
+        session_dir = File.readlink(symlink)
         session_id = File.basename(session_dir)
+        # Skip if target doesn't exist (stale symlink)
+        return unless Dir.exist?(session_dir)
 
+        parse_session_info(session_id, session_dir)
+      rescue Errno::EINVAL
+        # Not a symlink, skip it
+        nil
+      rescue StandardError => e
+        # Try to get session_id if we have session_dir
+        warn("⚠️  Skipping session #{session_id}: #{e.message}")
+        nil
+      end
+
+      def parse_session_info(session_id, session_dir)
         # Load config for swarm name and main directory
         config_file = File.join(session_dir, "config.yml")
         return unless File.exist?(config_file)
 
-        config = YAML.load_file(config_file)
+        config = YamlLoader.load_config_file(config_file)
         swarm_name = config.dig("swarm", "name") || "Unknown"
         main_instance = config.dig("swarm", "main")
 
@@ -139,8 +140,6 @@ module ClaudeSwarm
           directory: directories_str,
           start_time: start_time,
         }
-      rescue StandardError
-        nil
       end
 
       def get_start_time(session_dir)

data/lib/claude_swarm/commands/show.rb

@@ -11,7 +11,7 @@ module ClaudeSwarm
         end
 
         # Load config to get main instance name
-        config = YAML.load_file(File.join(session_path, "config.yml"))
+        config = YamlLoader.load_config_file(File.join(session_path, "config.yml"))
         main_instance_name = config.dig("swarm", "main")
 
         # Parse all events to build instance data

data/lib/claude_swarm/configuration.rb

@@ -11,14 +11,15 @@ module ClaudeSwarm
     # Regex patterns
     ENV_VAR_PATTERN = /\$\{([^}]+)\}/
     ENV_VAR_WITH_DEFAULT_PATTERN = /\$\{([^:}]+)(:=([^}]*))?\}/
-    O_SERIES_MODEL_PATTERN = /^o\d+(\s+(Preview|preview))?(-pro|-mini|-deep-research|-mini-deep-research)?$/
+    O_SERIES_MODEL_PATTERN = /^(o\d+(\s+(Preview|preview))?(-pro|-mini|-deep-research|-mini-deep-research)?|gpt-5(-mini|-nano)?)$/
 
-    attr_reader :config, :config_path, :swarm, :swarm_name, :main_instance, :instances
+    attr_reader :config, :config_path, :swarm, :swarm_name, :main_instance, :instances, :root_directory
 
     def initialize(config_path, base_dir: nil, options: {})
       @config_path = Pathname.new(config_path).expand_path
       @config_dir = @config_path.dirname
       @base_dir = base_dir || @config_dir
+      @root_directory = @base_dir
       @options = options
       load_and_validate
     end
@@ -59,7 +60,7 @@ module ClaudeSwarm
     end
 
     def load_and_validate
-      @config = YAML.load_file(@config_path, aliases: true)
+      @config = YamlLoader.load_config_file(@config_path)
       interpolate_env_vars!(@config)
       validate_version
       validate_swarm
@@ -67,10 +68,6 @@ module ClaudeSwarm
       # Skip directory validation if before commands are present
       # They might create the directories
       validate_directories unless has_before_commands?
-    rescue Errno::ENOENT
-      raise Error, "Configuration file not found: #{@config_path}"
-    rescue Psych::SyntaxError => e
-      raise Error, "Invalid YAML syntax: #{e.message}"
     end
 
     def interpolate_env_vars!(obj)
@@ -164,16 +161,16 @@ module ClaudeSwarm
           raise Error, "Instance '#{name}' has invalid reasoning_effort '#{config["reasoning_effort"]}'. Must be 'low', 'medium', or 'high'"
         end
 
-        # Validate it's only used with o-series models
-        # Support patterns like: o1, o1-mini, o1-pro, o1 Preview, o3-deep-research, o4-mini-deep-research, etc.
+        # Validate it's only used with o-series or gpt-5 models
+        # Support patterns like: o1, o1-mini, o1-pro, o1 Preview, o3-deep-research, o4-mini-deep-research, gpt-5, gpt-5-mini, gpt-5-nano, etc.
         unless model&.match?(O_SERIES_MODEL_PATTERN)
-          raise Error, "Instance '#{name}' has reasoning_effort but model '#{model}' is not an o-series model (o1, o1 Preview, o1-mini, o1-pro, o3, o3-mini, o3-pro, o3-deep-research, o4-mini, o4-mini-deep-research, etc.)"
+          raise Error, "Instance '#{name}' has reasoning_effort but model '#{model}' is not an o-series or gpt-5 model (o1, o1 Preview, o1-mini, o1-pro, o3, o3-mini, o3-pro, o3-deep-research, o4-mini, o4-mini-deep-research, gpt-5, gpt-5-mini, gpt-5-nano, etc.)"
         end
       end
 
-      # Validate temperature is not used with o-series models when provider is openai
+      # Validate temperature is not used with o-series or gpt-5 models when provider is openai
       if provider == "openai" && config["temperature"] && model&.match?(O_SERIES_MODEL_PATTERN)
-        raise Error, "Instance '#{name}' has temperature parameter but model '#{model}' is an o-series model. O-series models use deterministic reasoning and don't accept temperature settings"
+        raise Error, "Instance '#{name}' has temperature parameter but model '#{model}' is an o-series or gpt-5 model. O-series and gpt-5 models use deterministic reasoning and don't accept temperature settings"
       end
 
       # Validate OpenAI-specific fields only when provider is not "openai"
@@ -211,6 +208,7 @@ module ClaudeSwarm
         disallowed_tools: Array(config["disallowed_tools"]),
         mcps: parse_mcps(config["mcps"] || []),
         prompt: config["prompt"],
+        prompt_file: config["prompt_file"],
         description: config["description"],
         vibe: config["vibe"],
         worktree: parse_worktree_value(config["worktree"]),

data/lib/claude_swarm/mcp_generator.rb

@@ -134,7 +134,16 @@ module ClaudeSwarm
       args.push("--directories", *instance[:directories]) if instance[:directories] && instance[:directories].size > 1
 
       # Add optional arguments
-      args.push("--prompt", instance[:prompt]) if instance[:prompt]
+      # Handle prompt_file by reading the file contents
+      if instance[:prompt_file]
+        prompt_file_path = File.join(@config.root_directory, instance[:prompt_file])
+        if File.exist?(prompt_file_path)
+          prompt_content = File.read(prompt_file_path)
+          args.push("--prompt", prompt_content)
+        end
+      elsif instance[:prompt]
+        args.push("--prompt", instance[:prompt])
+      end
 
       args.push("--description", instance[:description]) if instance[:description]
 

data/lib/claude_swarm/orchestrator.rb

@@ -6,12 +6,6 @@ module ClaudeSwarm
 
     attr_reader :config, :session_path, :session_log_path
 
-    ["INT", "TERM", "QUIT"].each do |signal|
-      Signal.trap(signal) do
-        puts "\n🛑 Received #{signal} signal."
-      end
-    end
-
     def initialize(configuration, mcp_generator, vibe: false, prompt: nil, interactive_prompt: nil, stream_logs: false, debug: false,
       restore_session_path: nil, worktree: nil, session_id: nil)
       @config = configuration
@@ -72,19 +66,40 @@ module ClaudeSwarm
       # Track start time
       @start_time = Time.now
 
+      # Setup signal handlers for graceful shutdown
+      setup_signal_handlers do
+        @signal_received = true
+        cleanup_all
+      end
+
       begin
         start_internal
       rescue StandardError => e
         # Ensure cleanup happens even on unexpected errors
-        cleanup_processes
-        cleanup_run_symlink
-        cleanup_worktrees
+        cleanup_all
         raise e
       end
     end
 
     private
 
+    def cleanup_all
+      execute_after_commands_once
+      cleanup_processes
+      cleanup_run_symlink
+      cleanup_worktrees
+    end
+
+    def setup_signal_handlers(&cleanup_block)
+      ["INT", "TERM", "QUIT", "HUP"].each do |signal|
+        Signal.trap(signal) do
+          puts "\n🛑 Received #{signal} signal. Shutting down gracefully..."
+          cleanup_block&.call
+          exit(0)
+        end
+      end
+    end
+
     def start_internal
       if @restore_session_path
         non_interactive_output do
@@ -142,9 +157,7 @@ module ClaudeSwarm
             end
           rescue StandardError => e
             non_interactive_output { print("❌ Failed to setup worktrees: #{e.message}") }
-            cleanup_processes
-            cleanup_run_symlink
-            cleanup_worktrees
+            cleanup_all
             raise
           end
         end
@@ -226,9 +239,7 @@ module ClaudeSwarm
           success = execute_before_commands?(before_commands)
           unless success
             non_interactive_output { print("❌ Before commands failed. Aborting swarm launch.") }
-            cleanup_processes
-            cleanup_run_symlink
-            cleanup_worktrees
+            cleanup_all
             exit(1)
           end
         end
@@ -245,9 +256,7 @@ module ClaudeSwarm
           end
         rescue ClaudeSwarm::Error => e
           non_interactive_output { print("❌ Directory validation failed: #{e.message}") }
-          cleanup_processes
-          cleanup_run_symlink
-          cleanup_worktrees
+          cleanup_all
           exit(1)
         end
       end
@@ -261,7 +270,12 @@ module ClaudeSwarm
           if @non_interactive_prompt
             stream_to_session_log(*command)
           else
-            system!(*command)
+            system_with_pid!(*command) do |pid|
+              @process_tracker.track_pid(pid, "claude_#{@config.main_instance}")
+              non_interactive_output do
+                puts "✓ Claude instance started with PID: #{pid}"
+              end
+            end
           end
         end
       end
@@ -279,37 +293,10 @@ module ClaudeSwarm
       display_summary
 
       # Execute after commands if specified
-      # Use the same logic as before commands for consistency
-      after_commands = @config.after_commands
-      if after_commands.any? && !@restore_session_path
-        # Determine where to run after commands (same logic as before commands)
-        if File.exist?(main_instance[:directory])
-          # Directory exists, run commands in it
-          after_commands_dir = main_instance[:directory]
-        else
-          # Directory doesn't exist (shouldn't happen after main instance runs, but be safe)
-          parent_dir = File.dirname(File.expand_path(main_instance[:directory]))
-          after_commands_dir = parent_dir
-        end
-
-        Dir.chdir(after_commands_dir) do
-          non_interactive_output do
-            print("⚙️  Executing after commands...")
-          end
-
-          success = execute_after_commands?(after_commands)
-          unless success
-            non_interactive_output do
-              puts "⚠️  Some after commands failed"
-            end
-          end
-        end
-      end
+      execute_after_commands_once
 
       # Clean up child processes and run symlink
-      cleanup_processes
-      cleanup_run_symlink
-      cleanup_worktrees
+      cleanup_all
     end
 
     def non_interactive_output
@@ -327,6 +314,42 @@ module ClaudeSwarm
       execute_commands(commands, phase: "after", fail_fast: false)
     end
 
+    def execute_after_commands_once
+      # Ensure after commands are only executed once
+      return if @after_commands_executed
+
+      @after_commands_executed = true
+
+      # Use the same logic as before commands for consistency
+      after_commands = @config.after_commands
+      return if after_commands.empty? || @restore_session_path
+
+      main_instance = @config.main_instance_config
+
+      # Determine where to run after commands (same logic as before commands)
+      if File.exist?(main_instance[:directory])
+        # Directory exists, run commands in it
+        after_commands_dir = main_instance[:directory]
+      else
+        # Directory doesn't exist (shouldn't happen after main instance runs, but be safe)
+        parent_dir = File.dirname(File.expand_path(main_instance[:directory]))
+        after_commands_dir = parent_dir
+      end
+
+      Dir.chdir(after_commands_dir) do
+        non_interactive_output do
+          print("⚙️  Executing after commands...")
+        end
+
+        success = execute_after_commands?(after_commands)
+        unless success
+          non_interactive_output do
+            puts "⚠️  Some after commands failed"
+          end
+        end
+      end
+    end
+
     def save_swarm_config_path(session_path)
       # Copy the YAML config file to the session directory
       config_copy_path = File.join(session_path, "config.yml")
@@ -800,7 +823,8 @@ module ClaudeSwarm
       all_succeeded = true
 
       # Setup logger for session logging if we have a session path
-      logger = Logger.new(@session_log_path, level: :info)
+      log_dev = @signal_received ? nil : @session_log_path
+      logger = Logger.new(log_dev, level: :info)
 
       commands.each_with_index do |command, index|
         # Log the command execution to session log

data/lib/claude_swarm/system_utils.rb

@@ -3,18 +3,44 @@
 module ClaudeSwarm
   module SystemUtils
     def system!(*args)
-      success = system(*args)
-      unless success
-        exit_status = $CHILD_STATUS&.exitstatus || 1
-        command_str = args.size == 1 ? args.first : args.join(" ")
-        if exit_status == 143 # timeout command exit status = 128 + 15 (SIGTERM)
-          warn("⏱️ Command timeout: #{command_str}")
-        else
-          warn("❌ Command failed with exit status: #{exit_status}")
-          raise Error, "Command failed with exit status #{exit_status}: #{command_str}"
-        end
+      system(*args)
+      handle_command_failure(last_status, args)
+    end
+
+    def system_with_pid!(*args)
+      # Spawn the process - by default, inherits the parent's I/O
+      pid = Process.spawn(*args)
+
+      # Yield the PID to the block if given
+      yield(pid) if block_given?
+
+      # Wait for the process to complete
+      _, status = Process.wait2(pid)
+
+      # Check the exit status
+      handle_command_failure(status, args)
+    end
+
+    def last_status
+      $CHILD_STATUS
+    end
+
+    private
+
+    def handle_command_failure(status, args) # rubocop:disable Naming/PredicateMethod
+      return true if status&.success?
+
+      exit_status = status&.exitstatus || 1
+      command_str = args.size == 1 ? args.first : args.join(" ")
+
+      if exit_status == 143 # timeout command exit status = 128 + 15 (SIGTERM)
+        warn("⏱️ Command timeout: #{command_str}")
+      else
+        warn("❌ Command failed with exit status: #{exit_status}")
+        raise Error, "Command failed with exit status #{exit_status}: #{command_str}"
       end
-      success
+
+      false
     end
   end
 end