claude_swarm 0.3.7 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc0d22524516d5e0f2a76715c2a80b36d1a974a3ff7ba451c103c86cb4a36fd1
-  data.tar.gz: 4cebdba8032fc3dfe223033ba9b2890b5849dd5516a539ffdf57231bcec66c38
+  metadata.gz: a256a8d09a86290b06002437b38bc9092b7d83c1e4d1e0f4866b37cd1251bd99
+  data.tar.gz: d5eeec5e3a350dac2a04860c64c00043a8618fd29d40b9e1acf77e86b2f3fd49
 SHA512:
-  metadata.gz: e5ec9ed928d5e73d12eb1257571e3c2b45fc9db64dbd64e8f3186ea2df5f187927d4cc0a6e8eb9901cb8dbaf4679f442f340c85f6f6f728ca01f1d8b82db8bf8
-  data.tar.gz: 8fce151a6a47d68736fc62b6453515f46e12d293d2eee2f3e951f99510351941faf9f0b9c5f0497de37847fac282cc997ccebdbb11f477fc71b21b8514dd753d
+  metadata.gz: 3bb8119400be33d056b795aaea4f7f3d045d85a29d830cc42fe8c3dba0fd406100553b68740fe884e2e769e9685c439983d3a38ee52f55730f9f1ff7b40ddbff
+  data.tar.gz: a2dd8483358b673698e7ca3a71d1952fa0b2c85d0daf9cd2ff06c5f62d78f7ffebacc95a0e622cfb3f62f229e81c8177c5d6b263303b88c26c592ba53e7c7607

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [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

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

@@ -184,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
 

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"

data/lib/claude_swarm/orchestrator.rb

@@ -17,6 +17,7 @@ module ClaudeSwarm
       restore_session_path: nil, worktree: nil, session_id: nil)
       @config = configuration
       @generator = mcp_generator
+      @settings_generator = SettingsGenerator.new(configuration)
       @vibe = vibe
       @non_interactive_prompt = prompt
       @interactive_prompt = interactive_prompt
@@ -74,6 +75,12 @@ module ClaudeSwarm
         non_interactive_output do
           puts "✓ Regenerated MCP configurations with session IDs"
         end
+
+        # Generate settings files
+        @settings_generator.generate_all
+        non_interactive_output do
+          puts "✓ Generated settings files with hooks"
+        end
       else
         non_interactive_output do
           puts "🐝 Starting Claude Swarm: #{@config.swarm_name}"
@@ -127,6 +134,12 @@ module ClaudeSwarm
           puts "✓ Generated MCP configurations in session directory"
         end
 
+        # Generate settings files
+        @settings_generator.generate_all
+        non_interactive_output do
+          puts "✓ Generated settings files with hooks"
+        end
+
         # Save swarm config path for restoration
         save_swarm_config_path(session_path)
       end
@@ -488,6 +501,13 @@ module ClaudeSwarm
       parts << "--mcp-config"
       parts << mcp_config_path
 
+      # Add settings file if it exists for the main instance
+      settings_file = @settings_generator.settings_path(@config.main_instance)
+      if File.exist?(settings_file)
+        parts << "--settings"
+        parts << settings_file
+      end
+
       # Handle different modes
       if @non_interactive_prompt
         # Non-interactive mode with -p

data/lib/claude_swarm/settings_generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  class SettingsGenerator
+    def initialize(configuration)
+      @config = configuration
+    end
+
+    def generate_all
+      ensure_session_directory
+
+      @config.instances.each do |name, instance|
+        generate_settings(name, instance)
+      end
+    end
+
+    def settings_path(instance_name)
+      File.join(session_path, "#{instance_name}_settings.json")
+    end
+
+    private
+
+    def session_path
+      # In tests, use the session path from env if available, otherwise use a temp path
+      @session_path ||= if ENV["CLAUDE_SWARM_SESSION_PATH"]
+        SessionPath.from_env
+      else
+        # This should only happen in unit tests
+        Dir.pwd
+      end
+    end
+
+    def ensure_session_directory
+      # Session directory is already created by orchestrator
+      # Just ensure it exists
+      SessionPath.ensure_directory(session_path)
+    end
+
+    def generate_settings(name, instance)
+      settings = {}
+
+      # Add hooks if configured
+      if instance[:hooks] && !instance[:hooks].empty?
+        settings["hooks"] = instance[:hooks]
+      end
+
+      # Only write settings file if there are settings to write
+      return if settings.empty?
+
+      # Write settings file
+      File.write(settings_path(name), JSON.pretty_generate(settings))
+    end
+  end
+end

data/lib/claude_swarm/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.3.8
 platform: ruby
 authors:
 - Paulo Arruda
@@ -143,6 +143,7 @@ files:
 - examples/monitoring-demo.yml
 - examples/multi-directory.yml
 - examples/session-restoration-demo.yml
+- examples/simple-session-hook-swarm.yml
 - examples/test-generation.yml
 - examples/with-before-commands.yml
 - exe/claude-swarm
@@ -162,6 +163,7 @@ files:
 - lib/claude_swarm/process_tracker.rb
 - lib/claude_swarm/session_cost_calculator.rb
 - lib/claude_swarm/session_path.rb
+- lib/claude_swarm/settings_generator.rb
 - lib/claude_swarm/system_utils.rb
 - lib/claude_swarm/templates/generation_prompt.md.erb
 - lib/claude_swarm/tools/reset_session_tool.rb