claude_swarm 0.3.7 → 0.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc0d22524516d5e0f2a76715c2a80b36d1a974a3ff7ba451c103c86cb4a36fd1
-  data.tar.gz: 4cebdba8032fc3dfe223033ba9b2890b5849dd5516a539ffdf57231bcec66c38
+  metadata.gz: 55711fd9483c68d996c0a0e448c4d31135d7423269d1ed691bb3590db5487627
+  data.tar.gz: a84c0b4e1165057cbbe22bcd4d6c02c8fcdaedb5abb2f18e150b667ee0083385
 SHA512:
-  metadata.gz: e5ec9ed928d5e73d12eb1257571e3c2b45fc9db64dbd64e8f3186ea2df5f187927d4cc0a6e8eb9901cb8dbaf4679f442f340c85f6f6f728ca01f1d8b82db8bf8
-  data.tar.gz: 8fce151a6a47d68736fc62b6453515f46e12d293d2eee2f3e951f99510351941faf9f0b9c5f0497de37847fac282cc997ccebdbb11f477fc71b21b8514dd753d
+  metadata.gz: cc2808da58a6cb2b2ac545cfbe4803382602d4339017337d3af84b92274baab241952186f7de4e72adfbd413d0fcb448b955fb4cb7ebb5ebc014b90895988247
+  data.tar.gz: 2d58c3795f4ea80da550c6241ad7639ffa5d25fa868eb9af18bf58382961f8cad4fb930616c133197858193fb2f9627aead812bfd60a3565631ef38398351b16

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [0.3.9]
+
+### Added
+- **Main instance transcript integration**: Main Claude instance activity is now captured in session.log.json during interactive mode
+  - Automatically configures SessionStart hook for main instance to capture transcript path
+  - Background thread continuously tails transcript file and integrates entries into session.log.json
+  - Filters out summary entries to avoid duplicate conversation titles
+  - Uses file locking for thread-safe writes to maintain consistency
+  - Provides complete session history including main instance interactions
+
+## [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
+- **Persistent HTTP connections for OpenAI**: Added `faraday-net_http_persistent` dependency and configured OpenAI client to use persistent connections
+  - Improves performance when making multiple API requests by reusing HTTP connections
+  - Automatically configured for all OpenAI instances
+
+### Changed
+- **Improved OpenAI executor code organization**: Refactored internal methods for better maintainability
+  - Extracted configuration building and response handling into focused private methods
+  - Improved code readability with functional patterns
+
+### 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/cli.rb

@@ -693,7 +693,12 @@ module ClaudeSwarm
     def build_generation_prompt(readme_content, output_file)
       template_path = File.expand_path("templates/generation_prompt.md.erb", __dir__)
       template = File.read(template_path)
-      ERB.new(template, trim_mode: "-").result(binding)
+      <<~PROMPT
+        #{ERB.new(template, trim_mode: "-").result(binding)}
+
+        Start the conversation by greeting the user and asking: 'What kind of project would you like to create a Claude Swarm for?'
+        Say: 'I am ready to start'
+      PROMPT
     end
   end
 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/hooks/session_start_hook.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# This hook is called when Claude Code starts a session
+# It saves the transcript path for the main instance so the orchestrator can tail it
+
+require "json"
+require "fileutils"
+
+# Read input from stdin
+begin
+  stdin_data = $stdin.read
+  input = JSON.parse(stdin_data)
+rescue => e
+  # Return error response
+  puts JSON.generate({
+    "success" => false,
+    "error" => "Failed to read/parse input: #{e.message}",
+  })
+  exit(1)
+end
+
+# Get session path from command-line argument or environment
+session_path = ARGV[0] || ENV["CLAUDE_SWARM_SESSION_PATH"]
+
+if session_path && input["transcript_path"]
+  # Write the transcript path to a known location
+  path_file = File.join(session_path, "main_instance_transcript.path")
+  File.write(path_file, input["transcript_path"])
+
+  # Return success
+  puts JSON.generate({
+    "success" => true,
+  })
+else
+  # Return error if missing required data
+  puts JSON.generate({
+    "success" => false,
+    "error" => "Missing session path or transcript path",
+  })
+  exit(1)
+end

data/lib/claude_swarm/openai/executor.rb

@@ -1,8 +1,32 @@
 # frozen_string_literal: true
 
+require "openai"
+require "faraday/net_http_persistent"
+require "faraday/retry"
+
 module ClaudeSwarm
   module OpenAI
     class Executor < BaseExecutor
+      # Static configuration for Faraday retry middleware
+      FARADAY_RETRY_CONFIG = {
+        max: 3, # Maximum number of retries
+        interval: 0.5, # Initial delay between retries (in seconds)
+        interval_randomness: 0.5, # Randomness factor for retry intervals
+        backoff_factor: 2, # Exponential backoff factor
+        exceptions: [
+          Faraday::TimeoutError,
+          Faraday::ConnectionFailed,
+          Faraday::ServerError, # Retry on 5xx errors
+        ].freeze,
+        retry_statuses: [429, 500, 502, 503, 504].freeze, # HTTP status codes to retry
+      }.freeze
+
+      # Static configuration for OpenAI client
+      OPENAI_CLIENT_CONFIG = {
+        log_errors: true,
+        request_timeout: 1800, # 30 minutes
+      }.freeze
+
       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,
@@ -56,19 +80,8 @@ module ClaudeSwarm
         # Calculate duration
         duration_ms = ((Time.now - start_time) * 1000).round
 
-        # Format response similar to ClaudeCodeExecutor
-        response = {
-          "type" => "result",
-          "result" => result,
-          "duration_ms" => duration_ms,
-          "total_cost" => calculate_cost(result),
-          "session_id" => @session_id,
-        }
-
-        log_response(response)
-
-        @last_response = response
-        response
+        # Build and return response
+        build_response(result, duration_ms)
       rescue StandardError => e
         logger.error { "Unexpected error for #{@instance_name}: #{e.class} - #{e.message}" }
         logger.error { "Backtrace: #{e.backtrace.join("\n")}" }
@@ -92,35 +105,14 @@ module ClaudeSwarm
       private
 
       def setup_openai_client(token_env)
-        config = {
-          access_token: ENV.fetch(token_env),
-          log_errors: true,
-          request_timeout: 1800, # 30 minutes
-        }
-        config[:uri_base] = @base_url if @base_url
+        openai_client_config = build_openai_client_config(token_env)
+
+        @openai_client = ::OpenAI::Client.new(openai_client_config) do |faraday|
+          # Use persistent HTTP connections for better performance
+          faraday.adapter(:net_http_persistent)
 
-        @openai_client = ::OpenAI::Client.new(config) do |faraday|
           # Add retry middleware with custom configuration
-          faraday.request(
-            :retry,
-            max: 3, # Maximum number of retries
-            interval: 0.5, # Initial delay between retries (in seconds)
-            interval_randomness: 0.5, # Randomness factor for retry intervals
-            backoff_factor: 2, # Exponential backoff factor
-            exceptions: [
-              Faraday::TimeoutError,
-              Faraday::ConnectionFailed,
-              Faraday::ServerError, # Retry on 5xx errors
-            ],
-            retry_statuses: [429, 500, 502, 503, 504], # HTTP status codes to retry
-            retry_block: lambda do |env:, options:, retry_count:, exception:, will_retry:|
-              if will_retry
-                @logger.warn("Request failed (attempt #{retry_count}/#{options.max}): #{exception&.message || "HTTP #{env.status}"}. Retrying in #{options.interval * (options.backoff_factor**(retry_count - 1))} seconds...")
-              else
-                @logger.warn("Request failed after #{retry_count} attempts: #{exception&.message || "HTTP #{env.status}"}. Giving up.")
-              end
-            end,
-          )
+          faraday.request(:retry, **build_faraday_retry_config)
         end
       rescue KeyError
         raise ExecutionError, "OpenAI API key not found in environment variable: #{token_env}"
@@ -132,49 +124,21 @@ module ClaudeSwarm
         # Read MCP config to find MCP servers
         mcp_data = JSON.parse(File.read(@mcp_config))
 
-        # Create MCP client with all MCP servers from the config
-        if mcp_data["mcpServers"] && !mcp_data["mcpServers"].empty?
-          mcp_configs = []
-
-          mcp_data["mcpServers"].each do |name, server_config|
-            case server_config["type"]
-            when "stdio"
-              # Combine command and args into a single array
-              command_array = [server_config["command"]]
-              command_array.concat(server_config["args"] || [])
-
-              stdio_config = MCPClient.stdio_config(
-                command: command_array,
-                name: name,
-              )
-              stdio_config[:read_timeout] = 1800
-              mcp_configs << stdio_config
-            when "sse"
-              logger.warn { "SSE MCP servers not yet supported for OpenAI instances: #{name}" }
-              # TODO: Add SSE support when available in ruby-mcp-client
-            end
-          end
+        # Build MCP configurations from servers
+        mcp_configs = build_mcp_configs(mcp_data["mcpServers"])
+        return if mcp_configs.empty?
+
+        # Create MCP client with unbundled environment to avoid bundler conflicts
+        # This ensures MCP servers run in a clean environment without inheriting
+        # Claude Swarm's BUNDLE_* environment variables
+        Bundler.with_unbundled_env do
+          @mcp_client = MCPClient.create_client(
+            mcp_server_configs: mcp_configs,
+            logger: @logger,
+          )
 
-          if mcp_configs.any?
-            # Create MCP client with unbundled environment to avoid bundler conflicts
-            # This ensures MCP servers run in a clean environment without inheriting
-            # Claude Swarm's BUNDLE_* environment variables
-            Bundler.with_unbundled_env do
-              @mcp_client = MCPClient.create_client(
-                mcp_server_configs: mcp_configs,
-                logger: @logger,
-              )
-
-              # List available tools from all MCP servers
-              begin
-                @available_tools = @mcp_client.list_tools
-                logger.info { "Loaded #{@available_tools.size} tools from #{mcp_configs.size} MCP server(s)" }
-              rescue StandardError => e
-                logger.error { "Failed to load MCP tools: #{e.message}" }
-                @available_tools = []
-              end
-            end
-          end
+          # List available tools from all MCP servers
+          load_mcp_tools(mcp_configs)
         end
       rescue StandardError => e
         logger.error { "Failed to setup MCP client: #{e.message}" }
@@ -211,6 +175,80 @@ module ClaudeSwarm
         # Log streaming content similar to ClaudeCodeExecutor
         logger.debug { "#{instance_info} streaming: #{content}" }
       end
+
+      def build_faraday_retry_config
+        FARADAY_RETRY_CONFIG.merge(
+          retry_block: method(:handle_retry_logging),
+        )
+      end
+
+      def handle_retry_logging(env:, options:, retry_count:, exception:, will_retry:)
+        retry_delay = options.interval * (options.backoff_factor**(retry_count - 1))
+        error_info = exception&.message || "HTTP #{env.status}"
+
+        message = if will_retry
+          "Request failed (attempt #{retry_count}/#{options.max}): #{error_info}. Retrying in #{retry_delay} seconds..."
+        else
+          "Request failed after #{retry_count} attempts: #{error_info}. Giving up."
+        end
+
+        @logger.warn(message)
+      end
+
+      def build_openai_client_config(token_env)
+        OPENAI_CLIENT_CONFIG.merge(access_token: ENV.fetch(token_env)).tap do |config|
+          config[:uri_base] = @base_url if @base_url
+        end
+      end
+
+      def build_stdio_config(name, server_config)
+        # Combine command and args into a single array
+        command_array = [server_config["command"]]
+        command_array.concat(server_config["args"] || [])
+
+        MCPClient.stdio_config(
+          command: command_array,
+          name: name,
+        ).tap do |config|
+          config[:read_timeout] = 1800
+        end
+      end
+
+      def build_mcp_configs(mcp_servers)
+        return [] if mcp_servers.nil? || mcp_servers.empty?
+
+        mcp_servers.filter_map do |name, server_config|
+          case server_config["type"]
+          when "stdio"
+            build_stdio_config(name, server_config)
+          when "sse"
+            logger.warn { "SSE MCP servers not yet supported for OpenAI instances: #{name}" }
+            # TODO: Add SSE support when available in ruby-mcp-client
+            nil
+          end
+        end
+      end
+
+      def load_mcp_tools(mcp_configs)
+        @available_tools = @mcp_client.list_tools
+        logger.info { "Loaded #{@available_tools.size} tools from #{mcp_configs.size} MCP server(s)" }
+      rescue StandardError => e
+        logger.error { "Failed to load MCP tools: #{e.message}" }
+        @available_tools = []
+      end
+
+      def build_response(result, duration_ms)
+        {
+          "type" => "result",
+          "result" => result,
+          "duration_ms" => duration_ms,
+          "total_cost" => calculate_cost(result),
+          "session_id" => @session_id,
+        }.tap do |response|
+          log_response(response)
+          @last_response = response
+        end
+      end
     end
   end
 end

data/lib/claude_swarm/orchestrator.rb

@@ -23,8 +23,6 @@ module ClaudeSwarm
       @stream_logs = stream_logs
       @debug = debug
       @restore_session_path = restore_session_path
-      @session_path = nil
-      @session_log_path = nil
       @provided_session_id = session_id
       # Store worktree option for later use
       @worktree_option = worktree
@@ -34,9 +32,41 @@ module ClaudeSwarm
       @modified_instances = nil
       # Track start time for runtime calculation
       @start_time = nil
+      # Track transcript tailing thread
+      @transcript_thread = nil
 
       # Set environment variable for prompt mode to suppress output
       ENV["CLAUDE_SWARM_PROMPT"] = "1" if @non_interactive_prompt
+
+      # Initialize session path
+      if @restore_session_path
+        # Use existing session path for restoration
+        @session_path = @restore_session_path
+        @session_log_path = File.join(@session_path, "session.log")
+      else
+        # Generate new session path
+        session_params = { working_dir: ClaudeSwarm.root_dir }
+        session_params[:session_id] = @provided_session_id if @provided_session_id
+        @session_path = SessionPath.generate(**session_params)
+        SessionPath.ensure_directory(@session_path)
+        @session_log_path = File.join(@session_path, "session.log")
+
+        # Extract session ID from path (the timestamp part)
+        @session_id = File.basename(@session_path)
+
+      end
+      ENV["CLAUDE_SWARM_SESSION_PATH"] = @session_path
+      ENV["CLAUDE_SWARM_ROOT_DIR"] = ClaudeSwarm.root_dir
+
+      # Initialize components that depend on session path
+      @process_tracker = ProcessTracker.new(@session_path)
+      @settings_generator = SettingsGenerator.new(@config)
+
+      # Initialize WorktreeManager if needed
+      if @needs_worktree_manager && !@restore_session_path
+        cli_option = @worktree_option.is_a?(String) && !@worktree_option.empty? ? @worktree_option : nil
+        @worktree_manager = WorktreeManager.new(cli_option, session_id: @session_id)
+      end
     end
 
     def start
@@ -49,65 +79,42 @@ module ClaudeSwarm
           puts "😎 Vibe mode ON" if @vibe
         end
 
-        # Use existing session path
-        session_path = @restore_session_path
-        @session_path = session_path
-        @session_log_path = File.join(@session_path, "session.log")
-        ENV["CLAUDE_SWARM_SESSION_PATH"] = session_path
-        ENV["CLAUDE_SWARM_ROOT_DIR"] = ClaudeSwarm.root_dir
-
         # Create run symlink for restored session
         create_run_symlink
 
         non_interactive_output do
-          puts "📝 Using existing session: #{session_path}/"
+          puts "📝 Using existing session: #{@session_path}/"
         end
 
-        # Initialize process tracker
-        @process_tracker = ProcessTracker.new(session_path)
-
         # Check if the original session used worktrees
-        restore_worktrees_if_needed(session_path)
+        restore_worktrees_if_needed(@session_path)
 
         # Regenerate MCP configurations with session IDs for restoration
         @generator.generate_all
         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}"
           puts "😎 Vibe mode ON" if @vibe
         end
 
-        # Generate and set session path for all instances
-        session_params = { working_dir: ClaudeSwarm.root_dir }
-        session_params[:session_id] = @provided_session_id if @provided_session_id
-        session_path = SessionPath.generate(**session_params)
-        SessionPath.ensure_directory(session_path)
-        @session_path = session_path
-        @session_log_path = File.join(@session_path, "session.log")
-
-        # Extract session ID from path (the timestamp part)
-        @session_id = File.basename(session_path)
-
-        ENV["CLAUDE_SWARM_SESSION_PATH"] = session_path
-        ENV["CLAUDE_SWARM_ROOT_DIR"] = ClaudeSwarm.root_dir
-
         # Create run symlink for new session
         create_run_symlink
 
         non_interactive_output do
-          puts "📝 Session files will be saved to: #{session_path}/"
+          puts "📝 Session files will be saved to: #{@session_path}/"
         end
 
-        # Initialize process tracker
-        @process_tracker = ProcessTracker.new(session_path)
-
-        # Create WorktreeManager if needed with session ID
-        if @needs_worktree_manager
-          cli_option = @worktree_option.is_a?(String) && !@worktree_option.empty? ? @worktree_option : nil
-          @worktree_manager = WorktreeManager.new(cli_option, session_id: @session_id)
+        # Setup worktrees if needed
+        if @worktree_manager
           non_interactive_output { print("🌳 Setting up Git worktrees...") }
 
           # Get all instances for worktree setup
@@ -127,8 +134,14 @@ 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)
+        save_swarm_config_path(@session_path)
       end
 
       # Launch the main instance (fetch after worktree setup to get modified paths)
@@ -159,6 +172,9 @@ module ClaudeSwarm
       log_thread = nil
       log_thread = start_log_streaming if @non_interactive_prompt && @stream_logs
 
+      # Start transcript tailing thread for main instance
+      @transcript_thread = start_transcript_tailing
+
       # Write the current process PID (orchestrator) to a file for easy access
       main_pid_file = File.join(@session_path, "main_pid")
       File.write(main_pid_file, Process.pid.to_s)
@@ -204,6 +220,9 @@ module ClaudeSwarm
         log_thread.join
       end
 
+      # Clean up transcript tailing thread
+      cleanup_transcript_thread
+
       # Display runtime and cost summary
       display_summary
 
@@ -276,6 +295,7 @@ module ClaudeSwarm
 
     def cleanup_processes
       @process_tracker.cleanup_all
+      cleanup_transcript_thread
       puts "✓ Cleanup complete"
     rescue StandardError => e
       puts "⚠️  Error during cleanup: #{e.message}"
@@ -488,6 +508,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
@@ -556,6 +583,86 @@ module ClaudeSwarm
       end
     end
 
+    def start_transcript_tailing
+      Thread.new do
+        path_file = File.join(@session_path, "main_instance_transcript.path")
+
+        # Wait for path file to exist (created by SessionStart hook)
+        sleep(0.5) until File.exist?(path_file)
+
+        # Read the transcript path
+        transcript_path = File.read(path_file).strip
+
+        # Wait for transcript file to exist
+        sleep(0.5) until File.exist?(transcript_path)
+
+        # Tail the transcript file continuously (like tail -f)
+        File.open(transcript_path, "r") do |file|
+          # Start from the beginning to capture all entries
+          file.seek(0, IO::SEEK_SET) # Start at beginning of file
+
+          loop do
+            line = file.gets
+            if line
+              begin
+                # Parse JSONL entry
+                transcript_entry = JSON.parse(line)
+
+                # Skip summary entries - these are just conversation titles
+                next if transcript_entry["type"] == "summary"
+
+                # Convert to session.log.json format
+                session_entry = convert_transcript_to_session_format(transcript_entry)
+
+                # Write with file locking (same pattern as BaseExecutor)
+                session_json_path = File.join(@session_path, "session.log.json")
+                File.open(session_json_path, File::WRONLY | File::APPEND | File::CREAT) do |log_file|
+                  log_file.flock(File::LOCK_EX)
+                  log_file.puts(session_entry.to_json)
+                  log_file.flock(File::LOCK_UN)
+                end
+              rescue JSON::ParserError
+                # Silently skip unparseable lines
+              rescue StandardError
+                # Silently handle other errors to keep thread running
+              end
+            else
+              # No new data, sleep briefly
+              sleep(0.1)
+            end
+          end
+        end
+      rescue StandardError
+        # Silently handle thread errors
+      end
+    end
+
+    def convert_transcript_to_session_format(transcript_entry)
+      {
+        instance: @config.main_instance,
+        instance_id: "main",
+        timestamp: transcript_entry["timestamp"] || Time.now.iso8601,
+        event: {
+          type: "transcript",
+          source: "main_instance",
+          data: transcript_entry,
+        },
+      }
+    end
+
+    def cleanup_transcript_thread
+      return unless @transcript_thread
+
+      @transcript_thread.terminate if @transcript_thread.alive?
+      @transcript_thread.join(1) # Wait up to 1 second for thread to finish
+    rescue StandardError => e
+      logger.error { "Error cleaning up transcript thread: #{e.message}" }
+    end
+
+    def logger
+      @logger ||= Logger.new(File.join(@session_path, "session.log"), level: :info, progname: "orchestrator")
+    end
+
     def execute_commands(commands, phase:, fail_fast:)
       all_succeeded = true
 

data/lib/claude_swarm/settings_generator.rb

@@ -0,0 +1,77 @@
+# 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
+      @session_path ||= SessionPath.from_env
+    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
+
+      # Add SessionStart hook for main instance to capture transcript path
+      if name == @config.main_instance
+        session_start_hook = build_session_start_hook
+
+        # Initialize hooks if not present
+        settings["hooks"] ||= {}
+        settings["hooks"]["SessionStart"] ||= []
+
+        # Add our hook to the SessionStart hooks
+        settings["hooks"]["SessionStart"] << session_start_hook
+      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
+
+    def build_session_start_hook
+      hook_script_path = File.expand_path("hooks/session_start_hook.rb", __dir__)
+      # Pass session path as an argument since ENV may not be inherited
+      session_path_arg = session_path
+
+      {
+        "matcher" => "startup",
+        "hooks" => [
+          {
+            "type" => "command",
+            "command" => "ruby #{hook_script_path} '#{session_path_arg}'",
+            "timeout" => 5,
+          },
+        ],
+      }
+    end
+  end
+end

data/lib/claude_swarm/templates/generation_prompt.md.erb

@@ -1,4 +1,4 @@
-You are a Claude Swarm configuration generator assistant. Your role is to help the user create a well-structured claude-swarm.yml file through an interactive conversation.
+You are a Claude Swarm configuration generator assistant. Your role is to help the user create a well-structured swarm YAML file through an interactive conversation.
 
 ## Claude Swarm Overview
 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).
@@ -10,6 +10,7 @@ Key capabilities:
 - Run instances in different directories or Git worktrees
 - Support for custom system prompts per instance
 - Choose appropriate models (opus for complex tasks, sonnet for simpler ones)
+- Support for OpenAI instances
 
 ## Your Task
 1. Start by asking about the user's project structure and development needs
@@ -43,7 +44,7 @@ swarm:
     instance_name:
       description: "Clear description of role and responsibilities"
       directory: ./path/to/directory
-      model: sonnet  # or opus for complex tasks
+      model: opus
       allowed_tools: [Read, Edit, Write, Bash]
       connections: [other_instance_names]  # Optional
       prompt: |
@@ -57,7 +58,7 @@ swarm:
 - Write clear descriptions explaining each instance's responsibilities
 - Choose opus model for complex architectural or algorithmic tasks and routine development.
 - Choose sonnet model for simpler tasks
-- Set up logical connections (e.g., lead → team members, architect → implementers), but avoid circular dependencies.
+- Set up logical connections (e.g., lead → team members, architect → implementers), but do not create circular dependencies.
 - Always add this to the end of every prompt: `For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.`
 - Select tools based on each instance's actual needs:
   - Read: For code review and analysis roles
@@ -72,7 +73,6 @@ swarm:
 
 ## Interactive Questions to Ask
 - What type of project are you working on?
-- What's your project's directory structure?
 - What are the main technologies/frameworks you're using?
 - What development tasks do you need help with?
 - Do you need specialized roles (testing, DevOps, documentation)?
@@ -225,6 +225,3 @@ The more precisely you explain what you want, the better Claude's response will
 * **Provide instructions as sequential steps:** Use numbered lists or bullet points to better ensure that Claude carries out the task the exact way you want it to.
 
 </prompt_best_practices>
-
-Start the conversation by greeting the user and asking: "What kind of project would you like to create a Claude Swarm for?"
-Say: I am ready to start

data/lib/claude_swarm/version.rb

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

data/lib/claude_swarm.rb

@@ -23,9 +23,7 @@ require "yaml"
 # External dependencies
 require "claude_sdk"
 require "fast_mcp_annotations"
-require "faraday/retry"
 require "mcp_client"
-require "openai"
 require "thor"
 
 # Zeitwerk setup

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.3.9
 platform: ruby
 authors:
 - Paulo Arruda
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http_persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: faraday-retry
   requirement: !ruby/object:Gem::Requirement
@@ -143,6 +157,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
@@ -154,6 +169,7 @@ files:
 - lib/claude_swarm/commands/ps.rb
 - lib/claude_swarm/commands/show.rb
 - lib/claude_swarm/configuration.rb
+- lib/claude_swarm/hooks/session_start_hook.rb
 - lib/claude_swarm/mcp_generator.rb
 - lib/claude_swarm/openai/chat_completion.rb
 - lib/claude_swarm/openai/executor.rb
@@ -162,6 +178,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