claude_swarm 0.3.6 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b13f053c52c3e4ff662746f5027fcc6005be35ab6621c827b5fac205bb69b917
-  data.tar.gz: 70d1fbedfa25a81060259f37b4de2d47c740d8719171ce956a5462ce022359d2
+  metadata.gz: a256a8d09a86290b06002437b38bc9092b7d83c1e4d1e0f4866b37cd1251bd99
+  data.tar.gz: d5eeec5e3a350dac2a04860c64c00043a8618fd29d40b9e1acf77e86b2f3fd49
 SHA512:
-  metadata.gz: 60b9dbc2a41ae296a4a4d844c5dbf1195e26a38a4ce90aeb72a23f86467e94bc803e5b7488f8189829ad5a898a0887d1a639dc888adf24af87c4d391346709ac
-  data.tar.gz: 4935a7b7001b78d0a8ae1f4f732f61aed8d4fc35859478615f035edd2411ea5f9b5df3be1e26f910ad8ce8943c750d3b51f22adf3c105bbd97c5a36b17b072e9
+  metadata.gz: 3bb8119400be33d056b795aaea4f7f3d045d85a29d830cc42fe8c3dba0fd406100553b68740fe884e2e769e9685c439983d3a38ee52f55730f9f1ff7b40ddbff
+  data.tar.gz: a2dd8483358b673698e7ca3a71d1952fa0b2c85d0daf9cd2ff06c5f62d78f7ffebacc95a0e622cfb3f62f229e81c8177c5d6b263303b88c26c592ba53e7c7607

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [0.3.8]
+
+### Added
+- **Hooks support**: Claude Swarm now supports configuring Claude Code hooks for each instance
+  - Configure hooks directly in the YAML configuration file using Claude Code's format
+  - Each instance can have its own hooks configuration (PreToolUse, PostToolUse, UserPromptSubmit, etc.)
+  - Automatically generates `settings.json` files in the session directory when hooks are configured
+  - Main instance receives hooks via `--settings` CLI flag
+  - Connected instances receive hooks via SDK's `settings` attribute
+  - Full environment variable interpolation support in hook configurations
+  - See README.md "Hooks Configuration" section for usage examples
+
+### Fixed
+- **Settings integration**: Fixed passing settings to Claude instances
+  - Corrected SDK attribute name from `settings_path` to `settings`
+  - Added missing `--settings` flag for main instance CLI command
+
+## [0.3.7]
+
+### Added
+- **Main instance logging**: Captures main Claude instance output in `session.log` with prettified JSON format
+
+### Changed
+- **Updated claude-code-sdk-ruby dependency**: Bumped from 0.1.4 to 0.1.6
+  - Includes latest SDK improvements and bug fixes
+
 ## [0.3.6]
 
 ### Added

data/CLAUDE.md

@@ -130,9 +130,10 @@ The gem is fully implemented with the following components:
 1. User creates a `claude-swarm.yml` file defining the swarm topology
 2. Running `claude-swarm` parses the configuration and validates it
 3. MCP configuration files are generated for each instance in a session directory
-4. The main instance is launched with `exec`, replacing the current process
-5. Connected instances are available as MCP servers to the main instance
-6. When an instance has connections, those connections are automatically added to its allowed tools as `mcp__<connection_name>`
+4. Settings files (with hooks) are generated for each instance if hooks are configured
+5. The main instance is launched with `exec`, replacing the current process
+6. Connected instances are available as MCP servers to the main instance
+7. When an instance has connections, those connections are automatically added to its allowed tools as `mcp__<connection_name>`
 
 ### Configuration Example
 
@@ -159,6 +160,52 @@ swarm:
       worktree: false  # Optional: disable worktree for this instance
 ```
 
+### Hooks Support
+
+Claude Swarm supports configuring [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) for each instance. This allows you to run custom scripts before/after tools, on prompt submission, and more.
+
+#### Configuration Example with Hooks
+
+```yaml
+version: 1
+swarm:
+  name: "Dev Team"
+  main: lead
+  instances:
+    lead:
+      description: "Lead developer"
+      directory: .
+      model: opus
+      # Hooks configuration follows Claude Code's format exactly
+      hooks:
+        PreToolUse:
+          - matcher: "Write|Edit"
+            hooks:
+              - type: "command"
+                command: "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-code.py"
+                timeout: 10
+        PostToolUse:
+          - matcher: "Bash"
+            hooks:
+              - type: "command"
+                command: "echo 'Command executed by lead' >> /tmp/lead.log"
+        UserPromptSubmit:
+          - hooks:
+              - type: "command"
+                command: "$CLAUDE_PROJECT_DIR/.claude/hooks/add-context.py"
+    frontend:
+      description: "Frontend developer"
+      directory: ./frontend
+      hooks:
+        PreToolUse:
+          - matcher: "Write"
+            hooks:
+              - type: "command"
+                command: "npm run lint"
+```
+
+The hooks configuration is passed directly to Claude Code via a generated settings.json file in the session directory. Each instance gets its own settings file with its specific hooks.
+
 ## Testing
 
 The gem includes comprehensive tests covering:

data/README.md

@@ -303,6 +303,7 @@ Each instance can have:
 - **vibe**: Enable vibe mode (--dangerously-skip-permissions) for this instance (default: false)
 - **worktree**: Configure Git worktree usage for this instance (true/false/string)
 - **provider**: AI provider to use - "claude" (default) or "openai"
+- **hooks**: Configure Claude Code hooks for this instance (see Hooks Configuration section below)
 
 #### OpenAI Provider Configuration
 
@@ -394,6 +395,69 @@ mcps:
       X-Custom-Header: "value"
 ```
 
+### Hooks Configuration
+
+Claude Swarm supports configuring [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) for each instance. Hooks allow you to run custom scripts before/after tools, on prompt submission, and more. Each instance can have its own hooks configuration.
+
+#### Supported Hook Events
+
+- **PreToolUse**: Run before a tool is executed
+- **PostToolUse**: Run after a tool completes
+- **UserPromptSubmit**: Run when a user prompt is submitted
+- **Stop**: Run when the Claude instance stops
+- **SessionStart**: Run when a session starts
+- **And more...** (see Claude Code hooks documentation)
+
+#### Configuration Example
+
+```yaml
+instances:
+  lead:
+    description: "Lead developer"
+    directory: .
+    # Hooks configuration follows Claude Code's format exactly
+    hooks:
+      PreToolUse:
+        - matcher: "Write|Edit"
+          hooks:
+            - type: "command"
+              command: "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-code.py"
+              timeout: 10
+      PostToolUse:
+        - matcher: "Bash"
+          hooks:
+            - type: "command"
+              command: "echo 'Bash executed by ${INSTANCE_NAME}' >> ${LOG_DIR}/commands.log"
+      UserPromptSubmit:
+        - hooks:
+            - type: "command"
+              command: "${HOOKS_DIR:=$CLAUDE_PROJECT_DIR/.claude/hooks}/add-context.py"
+  frontend:
+    description: "Frontend developer"
+    directory: ./frontend
+    hooks:
+      PreToolUse:
+        - matcher: "Write"
+          hooks:
+            - type: "command"
+              command: "npm run lint"
+              timeout: 5
+```
+
+#### How It Works
+
+1. Define hooks in your instance configuration using the exact format expected by Claude Code
+2. Claude Swarm generates a `settings.json` file for each instance with hooks
+3. The settings file is passed to Claude Code SDK via the `--settings` parameter
+4. Each instance runs with its own hooks configuration
+
+#### Environment Variables in Hooks
+
+Hooks have access to standard Claude Code environment variables plus:
+- `$CLAUDE_PROJECT_DIR` - The project directory
+- `$CLAUDE_SWARM_SESSION_DIR` - The swarm session directory
+- `$CLAUDE_SWARM_INSTANCE_NAME` - The name of the current instance
+
 ### Tools
 
 Specify which tools each instance can use:

data/examples/simple-session-hook-swarm.yml

@@ -0,0 +1,37 @@
+version: 1
+swarm:
+  name: "Simple Session Hook Swarm"
+  main: developer
+  instances:
+    developer:
+      description: "Main developer instance"
+      directory: .
+      model: sonnet
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+        - Bash
+      connections: [session_tracker]
+      prompt: |
+        You are the main developer. You can delegate session tracking tasks to the session_tracker instance.
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    
+    session_tracker:
+      description: "Session tracking specialist that monitors and logs session information"
+      directory: .
+      model: sonnet
+      allowed_tools:
+        - Write
+        - Bash
+      hooks:
+        SessionStart:
+          - hooks:
+              - type: "command"
+                command: "cat > session_id.txt"
+                timeout: 5
+      prompt: |
+        You specialize in session tracking and monitoring. You automatically create session tracking files when you start.
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.

data/lib/claude_swarm/base_executor.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  class BaseExecutor
+    attr_reader :session_id, :last_response, :working_directory, :logger, :session_path, :session_json_path, :instance_info
+
+    def initialize(working_directory: Dir.pwd, model: nil, mcp_config: nil, vibe: false,
+      instance_name: nil, instance_id: nil, calling_instance: nil, calling_instance_id: nil,
+      claude_session_id: nil, additional_directories: [], debug: false)
+      @working_directory = working_directory
+      @additional_directories = additional_directories
+      @model = model
+      @mcp_config = mcp_config
+      @vibe = vibe
+      @session_id = claude_session_id
+      @last_response = nil
+      @instance_name = instance_name
+      @instance_id = instance_id
+      @calling_instance = calling_instance
+      @calling_instance_id = calling_instance_id
+      @debug = debug
+
+      # Setup static info strings for logging
+      @instance_info = build_info(@instance_name, @instance_id)
+      @caller_info = build_info(@calling_instance, @calling_instance_id)
+      @caller_to_instance = "#{@caller_info} -> #{instance_info}:"
+      @instance_to_caller = "#{instance_info} -> #{@caller_info}:"
+
+      # Setup logging
+      setup_logging
+
+      # Setup static event templates
+      setup_event_templates
+    end
+
+    def execute(_prompt, _options = {})
+      raise NotImplementedError, "Subclasses must implement the execute method"
+    end
+
+    def reset_session
+      @session_id = nil
+      @last_response = nil
+    end
+
+    def has_session?
+      !@session_id.nil?
+    end
+
+    protected
+
+    def build_info(name, id)
+      return name unless id
+
+      "#{name} (#{id})"
+    end
+
+    def setup_logging
+      # Use session path from environment (required)
+      @session_path = SessionPath.from_env
+      SessionPath.ensure_directory(@session_path)
+
+      # Initialize session JSON path
+      @session_json_path = File.join(@session_path, "session.log.json")
+
+      # Create logger with session.log filename
+      log_filename = "session.log"
+      log_path = File.join(@session_path, log_filename)
+      log_level = @debug ? :debug : :info
+      @logger = Logger.new(log_path, level: log_level, progname: @instance_name)
+
+      logger.info { "Started #{self.class.name} for instance: #{instance_info}" }
+    end
+
+    def setup_event_templates
+      @log_request_event_template = {
+        type: "request",
+        from_instance: @calling_instance,
+        from_instance_id: @calling_instance_id,
+        to_instance: @instance_name,
+        to_instance_id: @instance_id,
+      }.freeze
+
+      @session_json_entry_template = {
+        instance: @instance_name,
+        instance_id: @instance_id,
+        calling_instance: @calling_instance,
+        calling_instance_id: @calling_instance_id,
+      }.freeze
+    end
+
+    def log_request(prompt)
+      logger.info { "#{@caller_to_instance} \n---\n#{prompt}\n---" }
+
+      # Merge dynamic data with static template
+      event = @log_request_event_template.merge(
+        prompt: prompt,
+        timestamp: Time.now.iso8601,
+      )
+
+      append_to_session_json(event)
+    end
+
+    def log_response(response)
+      logger.info do
+        "($#{response["total_cost"]} - #{response["duration_ms"]}ms) #{@instance_to_caller} \n---\n#{response["result"]}\n---"
+      end
+    end
+
+    def append_to_session_json(event)
+      # Use file locking to ensure thread-safe writes
+      File.open(@session_json_path, File::WRONLY | File::APPEND | File::CREAT) do |file|
+        file.flock(File::LOCK_EX)
+
+        # Merge dynamic data with static template
+        entry = @session_json_entry_template.merge(
+          timestamp: Time.now.iso8601,
+          event: event,
+        )
+
+        # Write as single line JSON (JSONL format)
+        file.puts(entry.to_json)
+
+        file.flock(File::LOCK_UN)
+      end
+    rescue StandardError => e
+      logger.error { "Failed to append to session JSON: #{e.message}" }
+      raise
+    end
+
+    class ExecutionError < StandardError; end
+    class ParseError < StandardError; end
+  end
+end

data/lib/claude_swarm/claude_code_executor.rb

@@ -1,28 +1,7 @@
 # frozen_string_literal: true
 
 module ClaudeSwarm
-  class ClaudeCodeExecutor
-    attr_reader :session_id, :last_response, :working_directory, :logger, :session_path
-
-    def initialize(working_directory: Dir.pwd, model: nil, mcp_config: nil, vibe: false,
-      instance_name: nil, instance_id: nil, calling_instance: nil, calling_instance_id: nil,
-      claude_session_id: nil, additional_directories: [])
-      @working_directory = working_directory
-      @additional_directories = additional_directories
-      @model = model
-      @mcp_config = mcp_config
-      @vibe = vibe
-      @session_id = claude_session_id
-      @last_response = nil
-      @instance_name = instance_name
-      @instance_id = instance_id
-      @calling_instance = calling_instance
-      @calling_instance_id = calling_instance_id
-
-      # Setup logging
-      setup_logging
-    end
-
+  class ClaudeCodeExecutor < BaseExecutor
     def execute(prompt, options = {})
       # Log the request
       log_request(prompt)
@@ -75,8 +54,8 @@ module ClaudeSwarm
           end
         end
       rescue StandardError => e
-        @logger.error("Execution error for #{@instance_name}: #{e.class} - #{e.message}")
-        @logger.error("Backtrace: #{e.backtrace.join("\n")}")
+        logger.error { "Execution error for #{@instance_name}: #{e.class} - #{e.message}" }
+        logger.error { "Backtrace: #{e.backtrace.join("\n")}" }
         raise ExecutionError, "Claude Code execution failed: #{e.message}"
       end
 
@@ -90,20 +69,11 @@ module ClaudeSwarm
 
       result_response
     rescue StandardError => e
-      @logger.error("Unexpected error for #{@instance_name}: #{e.class} - #{e.message}")
-      @logger.error("Backtrace: #{e.backtrace.join("\n")}")
+      logger.error { "Unexpected error for #{@instance_name}: #{e.class} - #{e.message}" }
+      logger.error { "Backtrace: #{e.backtrace.join("\n")}" }
       raise
     end
 
-    def reset_session
-      @session_id = nil
-      @last_response = nil
-    end
-
-    def has_session?
-      !@session_id.nil?
-    end
-
     private
 
     def write_instance_state
@@ -122,63 +92,9 @@ module ClaudeSwarm
       }
 
       File.write(state_file, JSON.pretty_generate(state_data))
-      @logger.info("Wrote instance state for #{@instance_name} (#{@instance_id}) with session ID: #{@session_id}")
+      logger.info { "Wrote instance state for #{@instance_name} (#{@instance_id}) with session ID: #{@session_id}" }
     rescue StandardError => e
-      @logger.error("Failed to write instance state for #{@instance_name} (#{@instance_id}): #{e.message}")
-    end
-
-    def setup_logging
-      # Use session path from environment (required)
-      @session_path = SessionPath.from_env
-      SessionPath.ensure_directory(@session_path)
-
-      # Create logger with session.log filename
-      log_filename = "session.log"
-      log_path = File.join(@session_path, log_filename)
-      @logger = Logger.new(log_path)
-      @logger.level = Logger::INFO
-
-      # Custom formatter for better readability
-      @logger.formatter = proc do |severity, datetime, _progname, msg|
-        "[#{datetime.strftime("%Y-%m-%d %H:%M:%S.%L")}] [#{severity}] #{msg}\n"
-      end
-
-      return unless @instance_name
-
-      instance_info = @instance_name
-      instance_info += " (#{@instance_id})" if @instance_id
-      @logger.info("Started Claude Code executor for instance: #{instance_info}")
-    end
-
-    def log_request(prompt)
-      caller_info = @calling_instance
-      caller_info += " (#{@calling_instance_id})" if @calling_instance_id
-      instance_info = @instance_name
-      instance_info += " (#{@instance_id})" if @instance_id
-      @logger.info("#{caller_info} -> #{instance_info}: \n---\n#{prompt}\n---")
-
-      # Build event hash for JSON logging
-      event = {
-        type: "request",
-        from_instance: @calling_instance,
-        from_instance_id: @calling_instance_id,
-        to_instance: @instance_name,
-        to_instance_id: @instance_id,
-        prompt: prompt,
-        timestamp: Time.now.iso8601,
-      }
-
-      append_to_session_json(event)
-    end
-
-    def log_response(response)
-      caller_info = @calling_instance
-      caller_info += " (#{@calling_instance_id})" if @calling_instance_id
-      instance_info = @instance_name
-      instance_info += " (#{@instance_id})" if @instance_id
-      @logger.info(
-        "($#{response["total_cost"]} - #{response["duration_ms"]}ms) #{instance_info} -> #{caller_info}: \n---\n#{response["result"]}\n---",
-      )
+      logger.error { "Failed to write instance state for #{@instance_name} (#{@instance_id}): #{e.message}" }
     end
 
     def log_streaming_event(event)
@@ -198,13 +114,13 @@ module ClaudeSwarm
     end
 
     def log_system_message(event)
-      @logger.debug("SYSTEM: #{JSON.pretty_generate(event)}")
+      logger.debug { "SYSTEM: #{JSON.pretty_generate(event)}" }
     end
 
     def log_assistant_message(msg)
       # Assistant messages don't have stop_reason in SDK - they only have content
       content = msg["content"]
-      @logger.debug("ASSISTANT: #{JSON.pretty_generate(content)}") if content
+      logger.debug { "ASSISTANT: #{JSON.pretty_generate(content)}" } if content
 
       # Log tool calls
       tool_calls = content&.select { |c| c["type"] == "tool_use" } || []
@@ -212,52 +128,20 @@ module ClaudeSwarm
         arguments = tool_call["input"].to_json
         arguments = "#{arguments[0..300]} ...}" if arguments.length > 300
 
-        instance_info = @instance_name
-        instance_info += " (#{@instance_id})" if @instance_id
-        @logger.info(
-          "Tool call from #{instance_info} -> Tool: #{tool_call["name"]}, ID: #{tool_call["id"]}, Arguments: #{arguments}",
-        )
+        logger.info do
+          "Tool call from #{instance_info} -> Tool: #{tool_call["name"]}, ID: #{tool_call["id"]}, Arguments: #{arguments}"
+        end
       end
 
       # Log thinking text
       text = content&.select { |c| c["type"] == "text" } || []
       text.each do |t|
-        instance_info = @instance_name
-        instance_info += " (#{@instance_id})" if @instance_id
-        @logger.info("#{instance_info} is thinking:\n---\n#{t["text"]}\n---")
+        logger.info { "#{instance_info} is thinking:\n---\n#{t["text"]}\n---" }
       end
     end
 
     def log_user_message(content)
-      @logger.debug("USER: #{JSON.pretty_generate(content)}")
-    end
-
-    def append_to_session_json(event)
-      json_filename = "session.log.json"
-      json_path = File.join(@session_path, json_filename)
-
-      # Use file locking to ensure thread-safe writes
-      File.open(json_path, File::WRONLY | File::APPEND | File::CREAT) do |file|
-        file.flock(File::LOCK_EX)
-
-        # Create entry with metadata
-        entry = {
-          instance: @instance_name,
-          instance_id: @instance_id,
-          calling_instance: @calling_instance,
-          calling_instance_id: @calling_instance_id,
-          timestamp: Time.now.iso8601,
-          event: event,
-        }
-
-        # Write as single line JSON (JSONL format)
-        file.puts(entry.to_json)
-
-        file.flock(File::LOCK_UN)
-      end
-    rescue StandardError => e
-      @logger.error("Failed to append to session JSON: #{e.message}")
-      raise
+      logger.debug { "USER: #{JSON.pretty_generate(content)}" }
     end
 
     def build_sdk_options(prompt, options)
@@ -300,6 +184,10 @@ module ClaudeSwarm
         setup_additional_directories_mcp(sdk_options)
       end
 
+      # Add settings file path if it exists
+      settings_file = File.join(@session_path, "#{@instance_name}_settings.json")
+      sdk_options.settings = settings_file if File.exist?(settings_file)
+
       sdk_options
     end
 
@@ -329,14 +217,14 @@ module ClaudeSwarm
             headers: server_config["headers"] || {},
           )
         else
-          @logger.warn("Unsupported MCP server type: #{server_type} for server: #{name}")
+          logger.warn { "Unsupported MCP server type: #{server_type} for server: #{name}" }
           nil
         end
       end
 
       mcp_servers.compact
     rescue StandardError => e
-      @logger.error("Failed to parse MCP config: #{e.message}")
+      logger.error { "Failed to parse MCP config: #{e.message}" }
       {}
     end
 
@@ -347,7 +235,7 @@ module ClaudeSwarm
       @additional_directories.each do |dir|
         # This is a placeholder - the SDK doesn't directly support file system servers
         # You would need to implement a proper MCP server that provides file access
-        @logger.warn("Additional directories not fully supported: #{dir}")
+        logger.warn { "Additional directories not fully supported: #{dir}" }
       end
     end
 
@@ -452,8 +340,5 @@ module ClaudeSwarm
         end
       end
     end
-
-    class ExecutionError < StandardError; end
-    class ParseError < StandardError; end
   end
 end

data/lib/claude_swarm/claude_mcp_server.rb

@@ -7,7 +7,7 @@ module ClaudeSwarm
       attr_accessor :executor, :instance_config, :logger, :session_path, :calling_instance, :calling_instance_id
     end
 
-    def initialize(instance_config, calling_instance:, calling_instance_id: nil)
+    def initialize(instance_config, calling_instance:, calling_instance_id: nil, debug: false)
       @instance_config = instance_config
       @calling_instance = calling_instance
       @calling_instance_id = calling_instance_id
@@ -24,6 +24,7 @@ module ClaudeSwarm
         calling_instance_id: calling_instance_id,
         claude_session_id: instance_config[:claude_session_id],
         additional_directories: instance_config[:directories][1..] || [],
+        debug: debug,
       }
 
       @executor = if instance_config[:provider] == "openai"

data/lib/claude_swarm/cli.rb

@@ -230,6 +230,7 @@ module ClaudeSwarm
           instance_config,
           calling_instance: options[:calling_instance],
           calling_instance_id: options[:calling_instance_id],
+          debug: options[:debug],
         )
         server.start
       rescue StandardError => e

data/lib/claude_swarm/configuration.rb

@@ -200,6 +200,7 @@ module ClaudeSwarm
         vibe: config["vibe"],
         worktree: parse_worktree_value(config["worktree"]),
         provider: provider, # nil means Claude (default)
+        hooks: config["hooks"], # Pass hooks configuration as-is
       }
 
       # Add OpenAI-specific fields only when provider is "openai"