claude_swarm 1.0.1 → 1.0.2

data/lib/claude_swarm/version.rb

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

data/lib/claude_swarm/worktree_manager.rb

@@ -3,6 +3,7 @@
 module ClaudeSwarm
   class WorktreeManager
     include SystemUtils
+
     attr_reader :shared_worktree_name, :created_worktrees
 
     def initialize(cli_worktree_option = nil, session_id: nil)

data/lib/claude_swarm/yaml_loader.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  # Provides consistent YAML loading across the application
+  module YamlLoader
+    class << self
+      # Load a YAML configuration file (enables aliases for configuration flexibility)
+      # @param file_path [String] Path to the configuration file
+      # @return [Hash] The loaded configuration
+      # @raise [ClaudeSwarm::Error] Re-raises with a more descriptive error message
+      def load_config_file(file_path)
+        YAML.load_file(file_path, aliases: true)
+      rescue Errno::ENOENT
+        raise ClaudeSwarm::Error, "Configuration file not found: #{file_path}"
+      rescue Psych::SyntaxError => e
+        raise ClaudeSwarm::Error, "Invalid YAML syntax in #{file_path}: #{e.message}"
+      rescue Psych::BadAlias => e
+        raise ClaudeSwarm::Error, "Invalid YAML alias in #{file_path}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/claude_swarm.rb

@@ -28,13 +28,14 @@ require "thor"
 
 # Zeitwerk setup
 require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
+loader = Zeitwerk::Loader.new
+loader.tag = "claude_swarm"
+
 loader.ignore("#{__dir__}/claude_swarm/templates")
 loader.inflector.inflect(
   "cli" => "CLI",
   "openai" => "OpenAI",
 )
-loader.setup
 
 module ClaudeSwarm
   class Error < StandardError; end
@@ -65,3 +66,6 @@ module ClaudeSwarm
     end
   end
 end
+
+loader.push_dir("#{__dir__}/claude_swarm", namespace: ClaudeSwarm)
+loader.setup

data/lib/swarm_cli/cli.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  class CLI
+    class << self
+      def start(args)
+        new(args).run
+      end
+    end
+
+    def initialize(args)
+      @args = args
+    end
+
+    def run
+      # Handle special cases first
+      if @args.empty? || @args.include?("--help") || @args.include?("-h")
+        print_help
+        exit(0)
+      end
+
+      if @args.include?("--version") || @args.include?("-v")
+        print_version
+        exit(0)
+      end
+
+      # Extract command
+      command = @args.first
+
+      # Route to command
+      case command
+      when "run"
+        run_command(@args[1..])
+      when "mcp"
+        mcp_command(@args[1..])
+      when "migrate"
+        migrate_command(@args[1..])
+      else
+        # Check if it's an extension command
+        if CommandRegistry.registered?(command)
+          extension_command(command, @args[1..])
+        else
+          $stderr.puts "Unknown command: #{command}"
+          $stderr.puts
+          print_help
+          exit(1)
+        end
+      end
+    rescue StandardError => e
+      $stderr.puts "Fatal error: #{e.message}"
+      exit(1)
+    end
+
+    private
+
+    def mcp_command(args)
+      # MCP has subcommands
+      subcommand = args.first
+
+      case subcommand
+      when "serve"
+        mcp_serve_command(args[1..])
+      when "tools"
+        mcp_tools_command(args[1..])
+      else
+        $stderr.puts "Unknown mcp subcommand: #{subcommand}"
+        $stderr.puts
+        $stderr.puts "Available mcp subcommands:"
+        $stderr.puts "  serve     Start an MCP server exposing swarm lead agent"
+        $stderr.puts "  tools     Start an MCP server exposing SwarmSDK tools"
+        exit(1)
+      end
+    end
+
+    def mcp_serve_command(args)
+      # Parse options
+      options = McpServeOptions.new
+      options.parse(args)
+
+      # Execute mcp serve command
+      Commands::McpServe.new(options).execute
+    rescue TTY::Option::InvalidParameter, TTY::Option::InvalidArgument => e
+      $stderr.puts "Error: #{e.message}"
+      $stderr.puts
+      $stderr.puts options.help
+      exit(1)
+    end
+
+    def mcp_tools_command(args)
+      # Parse options
+      options = McpToolsOptions.new
+      options.parse(args)
+
+      # Execute mcp tools command
+      Commands::McpTools.new(options).execute
+    rescue TTY::Option::InvalidParameter, TTY::Option::InvalidArgument => e
+      $stderr.puts "Error: #{e.message}"
+      $stderr.puts
+      $stderr.puts options.help
+      exit(1)
+    end
+
+    def run_command(args)
+      # Parse options
+      options = Options.new
+      options.parse(args)
+
+      # Execute run command
+      Commands::Run.new(options).execute
+    rescue TTY::Option::InvalidParameter, TTY::Option::InvalidArgument => e
+      $stderr.puts "Error: #{e.message}"
+      $stderr.puts
+      $stderr.puts options.help
+      exit(1)
+    end
+
+    def migrate_command(args)
+      # Parse options
+      options = MigrateOptions.new
+      options.parse(args)
+
+      # Execute migrate command
+      Commands::Migrate.new(options).execute
+    rescue TTY::Option::InvalidParameter, TTY::Option::InvalidArgument => e
+      $stderr.puts "Error: #{e.message}"
+      $stderr.puts
+      $stderr.puts options.help
+      exit(1)
+    end
+
+    def extension_command(command_name, args)
+      # Get extension command class from registry
+      command_class = CommandRegistry.get(command_name)
+
+      # Execute extension command
+      command_class.execute(args)
+    end
+
+    def print_help
+      puts
+      puts "SwarmCLI v#{VERSION} - AI Agent Orchestration"
+      puts
+      puts "Usage:"
+      puts "  swarm run CONFIG_FILE -p PROMPT [options]"
+      puts "  swarm migrate INPUT_FILE [--output OUTPUT_FILE]"
+      puts "  swarm mcp serve CONFIG_FILE"
+      puts "  swarm mcp tools [TOOL_NAMES...]"
+
+      # Show extension commands dynamically
+      CommandRegistry.commands.each do |cmd|
+        puts "  swarm #{cmd} ..."
+      end
+
+      puts
+      puts "Commands:"
+      puts "  run           Execute a swarm with AI agents"
+      puts "  migrate       Migrate Claude Swarm v1 config to SwarmSDK v2 format"
+      puts "  mcp serve     Start an MCP server exposing swarm lead agent"
+      puts "  mcp tools     Start an MCP server exposing SwarmSDK tools"
+
+      # Show extension command descriptions (if registered)
+      if CommandRegistry.registered?("memory")
+        puts "  memory        Manage SwarmMemory embeddings"
+      end
+
+      puts
+      puts "Options:"
+      puts "  -p, --prompt PROMPT          Task prompt for the swarm"
+      puts "  -o, --output FILE            Output file for migrated config (default: stdout)"
+      puts "  --output-format FORMAT       Output format: 'human' or 'json' (default: human)"
+      puts "  -q, --quiet                  Suppress progress output (human format only)"
+      puts "  --truncate                   Truncate long outputs for concise view"
+      puts "  --verbose                    Show system reminders and additional debug information"
+      puts "  -h, --help                   Print help"
+      puts "  -v, --version                Print version"
+      puts
+      puts "Examples:"
+      puts "  swarm run team.yml -p 'Build a REST API'"
+      puts "  echo 'Build a REST API' | swarm run team.yml"
+      puts "  swarm run team.yml -p 'Refactor code' --output-format json"
+      puts "  swarm migrate old-config.yml"
+      puts "  swarm migrate old-config.yml --output new-config.yml"
+      puts "  swarm mcp serve team.yml"
+      puts "  swarm mcp tools                              # Expose all SwarmSDK tools"
+      puts "  swarm mcp tools Bash Grep Read               # Space-separated tools"
+      puts "  swarm mcp tools ScratchpadWrite,ScratchpadRead  # Comma-separated tools"
+
+      # Show extension command examples dynamically
+      if CommandRegistry.registered?("memory")
+        puts "  swarm memory setup                           # Setup embeddings (download model)"
+        puts "  swarm memory status                          # Check embedding status"
+      end
+
+      puts
+    end
+
+    def print_version
+      puts "SwarmCLI v#{VERSION}"
+    end
+  end
+end

data/lib/swarm_cli/command_registry.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  # Registry for CLI command extensions
+  #
+  # Allows gems (like swarm_memory) to register additional CLI commands
+  # that integrate seamlessly with the main swarm CLI.
+  #
+  # @example
+  #   # In swarm_memory gem
+  #   SwarmCLI::CommandRegistry.register(:memory, MyMemoryCommand)
+  #
+  #   # User runs:
+  #   swarm memory status
+  #
+  #   # SwarmCLI routes to MyMemoryCommand.execute(["status"])
+  class CommandRegistry
+    @extensions = {}
+
+    class << self
+      # Register a command extension
+      #
+      # @param command_name [Symbol, String] Command name (e.g., :memory)
+      # @param command_class [Class] Command class with execute(args) method
+      # @return [void]
+      #
+      # @example
+      #   CommandRegistry.register(:memory, SwarmMemory::CLI::Commands)
+      def register(command_name, command_class)
+        @extensions ||= {}
+        @extensions[command_name.to_s] = command_class
+      end
+
+      # Get command class by name
+      #
+      # @param command_name [String] Command name
+      # @return [Class, nil] Command class or nil if not found
+      def get(command_name)
+        @extensions ||= {}
+        @extensions[command_name.to_s]
+      end
+
+      # Check if a command is registered
+      #
+      # @param command_name [String] Command name
+      # @return [Boolean] True if command exists
+      def registered?(command_name)
+        @extensions ||= {}
+        @extensions.key?(command_name.to_s)
+      end
+
+      # Get all registered command names
+      #
+      # @return [Array<String>] Command names
+      def commands
+        @extensions ||= {}
+        @extensions.keys
+      end
+    end
+  end
+end

data/lib/swarm_cli/commands/mcp_serve.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  module Commands
+    # McpServe command starts an MCP server that exposes the swarm's lead agent as a tool.
+    #
+    # Usage:
+    #   swarm mcp serve config.yml
+    #
+    # The server uses stdio transport and exposes a "swarm" tool that executes tasks
+    # through the configured lead agent.
+    class McpServe
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+      end
+
+      def execute
+        # Validate options
+        options.validate!
+
+        # Load swarm configuration to validate it
+        config_path = options.config_file
+        unless File.exist?(config_path)
+          $stderr.puts "Error: Configuration file not found: #{config_path}"
+          exit(1)
+        end
+
+        # Validate the swarm configuration
+        begin
+          SwarmSDK::Swarm.load(config_path)
+        rescue SwarmSDK::ConfigurationError => e
+          $stderr.puts "Error: Invalid swarm configuration: #{e.message}"
+          exit(1)
+        end
+
+        # MCP servers should be quiet - stdout is reserved for MCP protocol
+        # Errors will still be logged to stderr
+
+        # Start the MCP server
+        start_mcp_server(config_path)
+      rescue Interrupt
+        # User cancelled (Ctrl+C) - silent exit
+        exit(130)
+      rescue StandardError => e
+        # Unexpected errors - always log to stderr
+        $stderr.puts "Fatal error: #{e.message}"
+        $stderr.puts e.backtrace.first(5).join("\n") if ENV["DEBUG"]
+        exit(1)
+      end
+
+      private
+
+      def start_mcp_server(config_path)
+        require "fast_mcp"
+
+        # Create the server
+        server = FastMcp::Server.new(
+          name: "swarm-mcp-server",
+          version: SwarmCLI::VERSION,
+        )
+
+        # Register the swarm tool
+        tool_class = create_swarm_tool_class(config_path)
+        server.register_tool(tool_class)
+
+        # Start with stdio transport (default)
+        server.start
+      end
+
+      def create_swarm_tool_class(config_path)
+        # Create a tool class dynamically with the config path bound
+        Class.new(FastMcp::Tool) do
+          # Explicit tool name required for anonymous classes
+          tool_name "task"
+
+          description "Execute tasks through the SwarmSDK lead agent"
+
+          arguments do
+            required(:task).filled(:string).description("The task or prompt to execute")
+            optional(:description).filled(:string).description("Brief description of the task")
+            optional(:thinking_budget).filled(:string, included_in?: ["think", "think hard", "think harder", "ultrathink"]).description("Thinking budget level")
+          end
+
+          # Store config path as class variable
+          @config_path = config_path
+
+          class << self
+            attr_accessor :config_path
+          end
+
+          define_method(:call) do |task:, description: nil, thinking_budget: nil|
+            # Load swarm for each execution (ensures fresh state)
+            swarm = SwarmSDK::Swarm.load(self.class.config_path)
+
+            # Build prompt with thinking budget if provided
+            prompt = task
+            if thinking_budget
+              prompt = "<thinking_budget>#{thinking_budget}</thinking_budget>\n\n#{task}"
+            end
+
+            # Execute the task (description is metadata only, not passed to execute)
+            result = swarm.execute(prompt)
+
+            # Check for errors
+            if result.failure?
+              {
+                success: false,
+                error: result.error.message,
+                task: task,
+                description: description,
+              }
+            else
+              # On success, return just the content string
+              result.content
+            end
+          rescue StandardError => e
+            {
+              success: false,
+              error: e.message,
+              task: task,
+              description: description,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_cli/commands/mcp_tools.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  module Commands
+    # McpTools command starts an MCP server that exposes SwarmSDK tools.
+    #
+    # Usage:
+    #   swarm mcp tools              # Expose all available tools
+    #   swarm mcp tools Bash Grep    # Expose only Bash and Grep
+    #
+    # The server uses stdio transport and exposes SwarmSDK tools as MCP tools.
+    class McpTools
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+        # Create scratchpad with persistence for MCP server
+        scratchpad_path = File.join(Dir.pwd, ".swarm", "scratchpad.json")
+        @scratchpad = SwarmSDK::Scratchpad.new(persist_to: scratchpad_path)
+      end
+
+      def execute
+        # Validate options
+        options.validate!
+
+        # Determine which tools to expose
+        tools_to_expose = determine_tools
+
+        if tools_to_expose.empty?
+          $stderr.puts "Error: No tools available to expose"
+          exit(1)
+        end
+
+        # Start the MCP server
+        start_mcp_server(tools_to_expose)
+      rescue Interrupt
+        # User cancelled (Ctrl+C) - silent exit
+        exit(130)
+      rescue StandardError => e
+        # Unexpected errors - always log to stderr
+        $stderr.puts "Fatal error: #{e.message}"
+        $stderr.puts e.backtrace.first(5).join("\n") if ENV["DEBUG"]
+        exit(1)
+      end
+
+      private
+
+      def determine_tools
+        if options.tool_names.any?
+          # Use specified tools
+          options.tool_names.map(&:to_sym)
+        else
+          # Default: expose all available tools
+          SwarmSDK::Tools::Registry.available_names
+        end
+      end
+
+      def start_mcp_server(tool_names)
+        require "fast_mcp"
+
+        # Create the server
+        server = FastMcp::Server.new(
+          name: "swarm-tools-server",
+          version: SwarmCLI::VERSION,
+        )
+
+        # Register each tool
+        tool_names.each do |tool_name|
+          tool_class = create_mcp_tool_wrapper(tool_name)
+          server.register_tool(tool_class)
+        end
+
+        # Start with stdio transport (default)
+        server.start
+      end
+
+      def create_special_tool_instance(tool_name)
+        case tool_name
+        when :Read
+          SwarmSDK::Tools::Read.create_for_agent(:mcp)
+        when :Write
+          SwarmSDK::Tools::Write.create_for_agent(:mcp)
+        when :Edit
+          SwarmSDK::Tools::Edit.create_for_agent(:mcp)
+        when :MultiEdit
+          SwarmSDK::Tools::MultiEdit.create_for_agent(:mcp)
+        when :TodoWrite
+          SwarmSDK::Tools::TodoWrite.create_for_agent(:mcp)
+        when :ScratchpadWrite
+          SwarmSDK::Tools::ScratchpadWrite.create_for_scratchpad(@scratchpad)
+        when :ScratchpadRead
+          SwarmSDK::Tools::ScratchpadRead.create_for_scratchpad(@scratchpad)
+        when :ScratchpadList
+          SwarmSDK::Tools::ScratchpadList.create_for_scratchpad(@scratchpad)
+        else
+          raise "Unknown special tool: #{tool_name}"
+        end
+      end
+
+      def create_mcp_tool_wrapper(tool_name)
+        sdk_tool_class_or_special = SwarmSDK::Tools::Registry.get(tool_name)
+
+        # Get the actual tool instance for special tools
+        sdk_tool = if sdk_tool_class_or_special == :special
+          create_special_tool_instance(tool_name)
+        else
+          sdk_tool_class_or_special.new
+        end
+
+        # Get tool metadata
+        tool_description = sdk_tool.respond_to?(:description) ? sdk_tool.description : "SwarmSDK #{tool_name} tool"
+        tool_params = sdk_tool.class.respond_to?(:parameters) ? sdk_tool.class.parameters : {}
+
+        # Create an MCP tool wrapper
+        Class.new(FastMcp::Tool) do
+          tool_name tool_name.to_s
+          description tool_description
+
+          # Map RubyLLM parameters to fast-mcp arguments
+          arguments do
+            tool_params.each do |param_name, param_obj|
+              param_type = param_obj.type == "integer" ? :integer : :string
+              if param_obj.required
+                required(param_name).filled(param_type).description(param_obj.description || "")
+              else
+                optional(param_name).filled(param_type).description(param_obj.description || "")
+              end
+            end
+          end
+
+          # Capture sdk_tool in closure
+          define_method(:call) do |**kwargs|
+            result = sdk_tool.execute(**kwargs)
+
+            # Return string output for MCP
+            if result.is_a?(Hash)
+              result[:output] || result[:content] || result[:files]&.join("\n") || result.to_s
+            else
+              result.to_s
+            end
+          rescue StandardError => e
+            "Error: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_cli/commands/migrate.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  module Commands
+    # Migrate command converts Claude Swarm v1 configurations to SwarmSDK v2 format.
+    #
+    # Usage:
+    #   swarm migrate old-config.yml
+    #   swarm migrate old-config.yml --output new-config.yml
+    #
+    class Migrate
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+      end
+
+      def execute
+        # Validate options
+        options.validate!
+
+        # Create migrator
+        migrator = Migrator.new(options.input_file)
+
+        # Perform migration
+        migrated_yaml = migrator.migrate
+
+        # Write to output file or stdout
+        if options.output
+          File.write(options.output, migrated_yaml)
+          $stderr.puts "✓ Migration complete! Converted configuration saved to: #{options.output}"
+        else
+          puts migrated_yaml
+        end
+
+        exit(0)
+      rescue SwarmCLI::ExecutionError => e
+        handle_error(e)
+        exit(1)
+      rescue Interrupt
+        $stderr.puts "\n\nMigration cancelled by user"
+        exit(130)
+      rescue StandardError => e
+        handle_error(e)
+        exit(1)
+      end
+
+      private
+
+      def handle_error(error)
+        $stderr.puts "Error: #{error.message}"
+      end
+    end
+  end
+end