claude_swarm 0.1.17 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f0ab99665f31bddf2d3641525481ce2df55e910950af03290137246847bf70d
-  data.tar.gz: 2435170f5b61604c3131b1680f60ed8727795c58432806d9b61007813d4f5ce3
+  metadata.gz: 1aaf0eadabd67afb0bd79738de8c7fcbfb65887d477a2c0c002017cff9de15ec
+  data.tar.gz: 777f04c044a2204477d1328dc31b0b5361fa0007d0cf637254d3531260e3149d
 SHA512:
-  metadata.gz: ee74c188f6cc7fd31bb8705661f0913674bb687fd1eae6c2973728d2418f62bbad86054a89bd150965f39ec0bbd37ac04b2413dd22340311afd03cd5ec9d5424
-  data.tar.gz: a6c5fb7db4a8659619c9c7b5de000303ce91b046b85d635381f437adc92b4fd739e8d2142f0e65323346d1ba4d2607bf2b90c7d76fcf7c119bf6b9d5c431a7fc
+  metadata.gz: cb39225f7a1f4cfd7c0d7e0e3068ad5527473a04744ed0d18525b37452e7b7d4fe67c83f03fbb5c662591e51ed9c10a2360c5943676dc944ea83680652c977b7
+  data.tar.gz: 807b10f87678f4f49df363fbcc53bf3a71d14848adf2ebbad1d701737aad8f9ce6b894ebe7f6e84c45234a1f414ec1c1d171b79189090b6d6de2a71df00e05a7

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [0.1.18]
+
+### Added
+- **Before commands**: Execute setup commands before launching the swarm
+  - New `before` field in swarm configuration accepts an array of commands
+  - Commands are executed in sequence before any Claude instances are launched
+  - All commands must succeed (exit code 0) for the swarm to launch
+  - Commands are only executed on initial launch, not when restoring sessions
+  - Output is logged to the session log file
+  - Useful for installing dependencies, starting services, or running setup scripts
+  - Example: `before: ["npm install", "docker-compose up -d"]`
+
+- **Git worktree support**: Run instances in isolated Git worktrees
+  - New `--worktree [NAME]` CLI option creates worktrees for all instances
+  - Worktrees are created inside each repository at `.worktrees/NAME`
+  - Each worktree gets its own branch (not detached HEAD) for proper Git operations
+  - Auto-generated names use session ID: `worktree-SESSION_ID`
+  - Per-instance worktree configuration in YAML:
+    - `worktree: true` - Use shared worktree name
+    - `worktree: false` - Disable worktree for this instance
+    - `worktree: "branch-name"` - Use custom worktree name
+  - Session restoration automatically restores worktrees
+  - Cleanup preserves worktrees with uncommitted changes or unpushed commits
+  - Warnings displayed when worktrees are preserved: "⚠️ Warning: Worktree has uncommitted changes"
+  - Multiple directories per instance work seamlessly with worktrees
+  - `.gitignore` automatically created in `.worktrees/` directory
+  - Example: `claude-swarm --worktree feature-branch`
+
 ## [0.1.17]
 
 ### Added

data/CLAUDE.md

@@ -39,6 +39,47 @@ bundle exec rake release    # Release gem to RubyGems.org
 rake                  # Runs both tests and RuboCop
 ```
 
+## Git Worktree Support
+
+Claude Swarm supports launching instances in Git worktrees to isolate changes:
+
+### CLI Usage
+```bash
+# Create worktrees with custom name
+claude-swarm --worktree feature-branch
+
+# Create worktrees with auto-generated name (worktree-SESSION_ID)
+claude-swarm --worktree
+
+# Short form
+claude-swarm -w feature-x
+```
+
+### Per-Instance Configuration
+Instances can have individual worktree settings that override CLI behavior:
+
+```yaml
+instances:
+  main:
+    worktree: true         # Use shared worktree name (from CLI or auto-generated)
+  testing:
+    worktree: false        # Don't use worktree for this instance
+  feature:
+    worktree: "feature-x"  # Use specific worktree name
+  default:
+    # No worktree field - follows CLI behavior
+```
+
+### Worktree Behavior
+- Worktrees are created inside each repository in a `.worktrees/` directory
+- A `.gitignore` file is automatically created inside `.worktrees/` to ignore all contents
+- Each unique Git repository gets its own worktree with the same name
+- All instance directories are mapped to their worktree equivalents
+- Worktrees are automatically cleaned up when the swarm exits
+- Session metadata tracks worktree information for restoration
+- Non-Git directories are used as-is without creating worktrees
+- Existing worktrees with the same name are reused
+
 ## Architecture
 
 The gem is fully implemented with the following components:
@@ -49,6 +90,7 @@ The gem is fully implemented with the following components:
 - **ClaudeSwarm::Configuration** (`lib/claude_swarm/configuration.rb`): YAML parser and validator for swarm configurations
 - **ClaudeSwarm::McpGenerator** (`lib/claude_swarm/mcp_generator.rb`): Generates MCP JSON configurations for each instance
 - **ClaudeSwarm::Orchestrator** (`lib/claude_swarm/orchestrator.rb`): Launches the main Claude instance with proper configuration
+- **ClaudeSwarm::WorktreeManager** (`lib/claude_swarm/worktree_manager.rb`): Manages Git worktrees for isolated development
 
 ### Key Features
 
@@ -58,6 +100,7 @@ The gem is fully implemented with the following components:
 4. **Multiple MCP Types**: Supports both stdio and SSE MCP server types
 5. **Automatic MCP Generation**: Creates `.claude-swarm/` directory with MCP configs
 6. **Custom System Prompts**: Each instance can have a custom prompt via `--append-system-prompt`
+7. **Git Worktree Support**: Run instances in isolated Git worktrees with per-instance configuration
 
 ### How It Works
 
@@ -77,16 +120,20 @@ swarm:
   main: lead
   instances:
     lead:
+      description: "Lead developer coordinating the team"
       directory: .
       model: opus
       connections: [frontend, backend]
       prompt: "You are the lead developer coordinating the team"
       tools: [Read, Edit, Bash]
+      worktree: true  # Optional: use worktree for this instance
     frontend:
+      description: "Frontend developer specializing in React"
       directory: ./frontend
       model: sonnet
       prompt: "You specialize in frontend development with React"
       tools: [Edit, Write, Bash]
+      worktree: false  # Optional: disable worktree for this instance
 ```
 
 ## Testing
@@ -98,6 +145,7 @@ The gem includes comprehensive tests covering:
 - CLI command functionality
 - Session restoration
 - Vibe mode behavior
+- Worktree management and per-instance configuration
 
 ## Dependencies
 

data/README.md

@@ -1,10 +1,30 @@
 # Claude Swarm
 
-[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=0.1.15)](https://badge.fury.io/rb/claude_swarm)
+[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=0.1.17)](https://badge.fury.io/rb/claude_swarm)
 [![CI](https://github.com/parruda/claude-swarm/actions/workflows/ci.yml/badge.svg)](https://github.com/parruda/claude-swarm/actions/workflows/ci.yml)
 
 Claude Swarm 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) in a tree-like hierarchy. Define your swarm topology in simple YAML and let Claude instances delegate tasks through connected instances. Perfect for complex projects requiring specialized AI agents for frontend, backend, testing, DevOps, or research tasks.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Prerequisites](#prerequisites)
+- [Usage](#usage)
+  - [Quick Start](#quick-start)
+  - [Configuration Format](#configuration-format)
+  - [MCP Server Types](#mcp-server-types)
+  - [Tools](#tools)
+  - [Examples](#examples)
+  - [Command Line Options](#command-line-options)
+  - [Session Monitoring](#session-monitoring)
+  - [Session Management and Restoration](#session-management-and-restoration-experimental)
+- [How It Works](#how-it-works)
+- [Troubleshooting](#troubleshooting)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Install the gem by executing:
@@ -191,6 +211,10 @@ version: 1  # Required, currently only version 1 is supported
 swarm:
   name: "Swarm Name"  # Display name for your swarm
   main: instance_key  # Which instance to launch as the main interface
+  before:  # Optional: commands to run before launching the swarm
+    - "echo 'Setting up environment...'"
+    - "npm install"
+    - "docker-compose up -d"
   instances:
     # Instance definitions...
 ```
@@ -211,6 +235,7 @@ Each instance can have:
 - **mcps**: Array of additional MCP servers to connect
 - **prompt**: Custom system prompt to append to the instance
 - **vibe**: Enable vibe mode (--dangerously-skip-permissions) for this instance (default: false)
+- **worktree**: Configure Git worktree usage for this instance (true/false/string)
 
 ```yaml
 instance_name:
@@ -428,6 +453,42 @@ When using multiple directories:
 - Additional directories are accessible via the `--add-dir` flag in Claude
 - All directories must exist or the configuration will fail validation
 
+#### Before Commands
+
+You can specify commands to run before launching the swarm using the `before` field:
+
+```yaml
+version: 1
+swarm:
+  name: "Development Environment"
+  main: lead_developer
+  before:
+    - "echo '🚀 Setting up development environment...'"
+    - "npm install"
+    - "docker-compose up -d"
+    - "bundle install"
+  instances:
+    lead_developer:
+      description: "Lead developer coordinating the team"
+      directory: .
+      model: opus
+      allowed_tools: [Read, Edit, Write, Bash]
+```
+
+The `before` commands:
+- Are executed in sequence before launching any Claude instances
+- Must all succeed for the swarm to launch (exit code 0)
+- Are only executed on initial swarm launch, not when restoring sessions
+- Have their output logged to the session log file
+- Will abort the swarm launch if any command fails
+
+This is useful for:
+- Installing dependencies
+- Starting required services (databases, Docker containers, etc.)
+- Setting up the development environment
+- Running any prerequisite setup scripts
+
+
 #### Mixed Permission Modes
 
 You can have different permission modes for different instances:
@@ -459,6 +520,72 @@ swarm:
       allowed_tools: []  # Tools list ignored when vibe: true
 ```
 
+#### Git Worktrees
+
+Claude Swarm supports running instances in Git worktrees, allowing isolated work without affecting your main repository state. Worktrees are created inside each repository in a `.worktrees/` directory following Git best practices.
+
+**Example Structure:**
+```
+my-repo/
+├── .git/
+├── .worktrees/        (created by Claude Swarm)
+│   ├── .gitignore     (auto-created, contains "*")
+│   └── feature-x/     (worktree for feature-x branch)
+├── src/
+└── tests/
+```
+
+**CLI Option:**
+```bash
+# Create worktrees with auto-generated name (worktree-SESSION_ID)
+claude-swarm --worktree
+
+# Create worktrees with custom name
+claude-swarm --worktree feature-branch
+
+# Short form
+claude-swarm -w
+```
+
+**Per-Instance Configuration:**
+```yaml
+version: 1
+swarm:
+  name: "Worktree Example"
+  main: lead
+  instances:
+    lead:
+      description: "Lead developer"
+      directory: .
+      worktree: true  # Use shared worktree name from CLI (or auto-generate)
+      
+    testing:
+      description: "Test developer"  
+      directory: ./tests
+      worktree: false  # Don't use worktree for this instance
+      
+    feature_dev:
+      description: "Feature developer"
+      directory: ./features
+      worktree: "feature-x"  # Use specific worktree name
+```
+
+**Worktree Behavior:**
+- `worktree: true` - Uses the shared worktree name (from CLI or auto-generated)
+- `worktree: false` - Disables worktree for this instance
+- `worktree: "name"` - Uses a specific worktree name
+- Omitted - Follows CLI behavior (use worktree if `--worktree` is specified)
+
+**Notes:**
+- Worktrees are created inside each repository in a `.worktrees/` directory
+- Auto-generated worktree names use the session ID (e.g., `worktree-20241206_143022`)
+- This makes it easy to correlate worktrees with their Claude Swarm sessions
+- A `.gitignore` file is automatically created inside `.worktrees/` to ignore all worktree contents
+- All worktrees are automatically cleaned up when the swarm exits
+- Worktrees with the same name across different repositories share that name
+- Non-Git directories are unaffected by worktree settings
+- Existing worktrees with the same name are reused
+
 ### Command Line Options
 
 ```bash
@@ -480,6 +607,11 @@ claude-swarm --prompt "Fix the bug in the payment module"
 claude-swarm --session-id 20241206_143022
 claude-swarm --session-id ~/path/to/session
 
+# Run all instances in Git worktrees
+claude-swarm --worktree                  # Auto-generated name (worktree-SESSION_ID)
+claude-swarm --worktree feature-branch   # Custom worktree name
+claude-swarm -w                          # Short form
+
 # Show version
 claude-swarm version
 

data/claude-swarm.yml

@@ -5,22 +5,10 @@ swarm:
   instances:
     claude_swarm_architect:
       description: "Lead architect"
-      directory:
-        - .
-        - /Users/paulo/src/github.com/shopify-playground/claudeception
+      directory: .
       model: opus
       prompt: "You are an expert in Claude swarm architecture"
       vibe: true
       connections: [claudeception_architect]
 
-    # Example instances (uncomment and modify as needed):
-
-    claudeception_architect:
-      description: "You are an expert in Claudeception architecture"
-      directory:
-        - .
-        - /Users/paulo/src/github.com/shopify-playground/claudeception
-      model: opus
-      prompt: "You are an expert in Claudeception architecture"
-      vibe: true
-
+    

data/examples/with-before-commands.yml

@@ -0,0 +1,30 @@
+version: 1
+swarm:
+  name: "Development Environment"
+  main: lead_developer
+  before:
+    - "echo '🚀 Setting up development environment...'"
+    - "echo '📦 Installing dependencies...'"
+    - "echo '🐳 Starting Docker containers...'"
+  instances:
+    lead_developer:
+      description: "Lead developer who coordinates the team"
+      directory: .
+      model: sonnet
+      prompt: "You are the lead developer coordinating the team"
+      allowed_tools: [Read, Edit, Bash, Write]
+      connections: [frontend_dev, backend_dev]
+    
+    frontend_dev:
+      description: "Frontend developer specializing in React"
+      directory: ./frontend
+      model: sonnet
+      prompt: "You specialize in frontend development with React"
+      allowed_tools: [Read, Edit, Write]
+    
+    backend_dev:
+      description: "Backend developer focusing on APIs"
+      directory: ./backend
+      model: sonnet
+      prompt: "You specialize in backend development and APIs"
+      allowed_tools: [Read, Edit, Write, Bash]

data/lib/claude_swarm/cli.rb

@@ -26,6 +26,9 @@ module ClaudeSwarm
                           desc: "Enable debug output"
     method_option :session_id, type: :string,
                                desc: "Resume a previous session by ID or path"
+    method_option :worktree, type: :string, aliases: "-w",
+                             desc: "Create instances in Git worktrees with the given name (auto-generated if true)",
+                             banner: "[NAME]"
     def start(config_file = nil)
       # Handle session restoration
       if options[:session_id]
@@ -54,7 +57,8 @@ module ClaudeSwarm
                                         vibe: options[:vibe],
                                         prompt: options[:prompt],
                                         stream_logs: options[:stream_logs],
-                                        debug: options[:debug])
+                                        debug: options[:debug],
+                                        worktree: options[:worktree])
         orchestrator.start
       rescue Error => e
         error e.message
@@ -147,6 +151,10 @@ module ClaudeSwarm
         swarm:
           name: "Swarm Name"
           main: lead_developer
+          # before:  # Optional: commands to run before launching swarm (executed in sequence)
+          #   - "echo 'Setting up environment...'"
+          #   - "npm install"
+          #   - "docker-compose up -d"
           instances:
             lead_developer:
               description: "Lead developer who coordinates the team and makes architectural decisions"
@@ -241,7 +249,7 @@ module ClaudeSwarm
         end
       end
 
-      say "Cleaned #{cleaned} stale session#{cleaned == 1 ? "" : "s"}", :green
+      say "Cleaned #{cleaned} stale session#{"s" unless cleaned == 1}", :green
     end
 
     desc "watch SESSION_ID", "Watch session logs"
@@ -395,6 +403,17 @@ module ClaudeSwarm
 
         config = Configuration.new(config_file, base_dir: Dir.pwd)
 
+        # Load session metadata if it exists to check for worktree info
+        session_metadata_file = File.join(session_path, "session_metadata.json")
+        worktree_name = nil
+        if File.exist?(session_metadata_file)
+          metadata = JSON.parse(File.read(session_metadata_file))
+          if metadata["worktree"] && metadata["worktree"]["enabled"]
+            worktree_name = metadata["worktree"]["name"]
+            say "Restoring with worktree: #{worktree_name}", :green unless options[:prompt]
+          end
+        end
+
         # Create orchestrator with restoration mode
         generator = McpGenerator.new(config, vibe: options[:vibe], restore_session_path: session_path)
         orchestrator = Orchestrator.new(config, generator,
@@ -402,7 +421,8 @@ module ClaudeSwarm
                                         prompt: options[:prompt],
                                         stream_logs: options[:stream_logs],
                                         debug: options[:debug],
-                                        restore_session_path: session_path)
+                                        restore_session_path: session_path,
+                                        worktree: worktree_name)
         orchestrator.start
       rescue StandardError => e
         error "Failed to restore session: #{e.message}"

data/lib/claude_swarm/configuration.rb

@@ -26,6 +26,10 @@ module ClaudeSwarm
       instances[instance_name][:connections] || []
     end
 
+    def before_commands
+      @swarm["before"] || []
+    end
+
     private
 
     def load_and_validate
@@ -101,7 +105,8 @@ module ClaudeSwarm
         mcps: parse_mcps(config["mcps"] || []),
         prompt: config["prompt"],
         description: config["description"],
-        vibe: config["vibe"] || false
+        vibe: config["vibe"] || false,
+        worktree: parse_worktree_value(config["worktree"])
       }
     end
 
@@ -188,5 +193,13 @@ module ClaudeSwarm
     def expand_path(path)
       Pathname.new(path).expand_path(@base_dir).to_s
     end
+
+    def parse_worktree_value(value)
+      return nil if value.nil? # Omitted means follow CLI behavior
+      return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      return value.to_s if value.is_a?(String) && !value.empty?
+
+      raise Error, "Invalid worktree value: #{value.inspect}. Must be true, false, or a non-empty string"
+    end
   end
 end

data/lib/claude_swarm/orchestrator.rb

@@ -1,17 +1,19 @@
 # frozen_string_literal: true
 
+require "English"
 require "shellwords"
 require "json"
 require "fileutils"
 require_relative "session_path"
 require_relative "process_tracker"
+require_relative "worktree_manager"
 
 module ClaudeSwarm
   class Orchestrator
     RUN_DIR = File.expand_path("~/.claude-swarm/run")
 
     def initialize(configuration, mcp_generator, vibe: false, prompt: nil, stream_logs: false, debug: false,
-                   restore_session_path: nil)
+                   restore_session_path: nil, worktree: nil)
       @config = configuration
       @generator = mcp_generator
       @vibe = vibe
@@ -20,6 +22,15 @@ module ClaudeSwarm
       @debug = debug
       @restore_session_path = restore_session_path
       @session_path = nil
+      # Store worktree option for later use
+      @worktree_option = worktree
+      @needs_worktree_manager = worktree.is_a?(String) || worktree == "" ||
+                                configuration.instances.values.any? { |inst| !inst[:worktree].nil? }
+      # Store modified instances after worktree setup
+      @modified_instances = nil
+
+      # Set environment variable for prompt mode to suppress output
+      ENV["CLAUDE_SWARM_PROMPT"] = "1" if @prompt
     end
 
     def start
@@ -50,6 +61,9 @@ module ClaudeSwarm
         # Set up signal handlers to clean up child processes
         setup_signal_handlers
 
+        # Check if the original session used worktrees
+        restore_worktrees_if_needed(session_path)
+
         # Regenerate MCP configurations with session IDs for restoration
         @generator.generate_all
         unless @prompt
@@ -68,6 +82,9 @@ module ClaudeSwarm
         SessionPath.ensure_directory(session_path)
         @session_path = session_path
 
+        # Extract session ID from path (the timestamp part)
+        @session_id = File.basename(session_path)
+
         ENV["CLAUDE_SWARM_SESSION_PATH"] = session_path
         ENV["CLAUDE_SWARM_START_DIR"] = Dir.pwd
 
@@ -85,6 +102,24 @@ module ClaudeSwarm
         # Set up signal handlers to clean up child processes
         setup_signal_handlers
 
+        # 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)
+          puts "🌳 Setting up Git worktrees..." unless @prompt
+
+          # Get all instances for worktree setup
+          # Note: instances.values already includes the main instance
+          all_instances = @config.instances.values
+
+          @worktree_manager.setup_worktrees(all_instances)
+
+          unless @prompt
+            puts "✓ Worktrees created with branch: #{@worktree_manager.worktree_name}"
+            puts
+          end
+        end
+
         # Generate all MCP configuration files
         @generator.generate_all
         unless @prompt
@@ -96,7 +131,30 @@ module ClaudeSwarm
         save_swarm_config_path(session_path)
       end
 
-      # Launch the main instance
+      # Execute before commands if specified
+      before_commands = @config.before_commands
+      if before_commands.any? && !@restore_session_path
+        unless @prompt
+          puts "⚙️  Executing before commands..."
+          puts
+        end
+
+        success = execute_before_commands(before_commands)
+        unless success
+          puts "❌ Before commands failed. Aborting swarm launch." unless @prompt
+          cleanup_processes
+          cleanup_run_symlink
+          cleanup_worktrees
+          exit 1
+        end
+
+        unless @prompt
+          puts "✓ Before commands completed successfully"
+          puts
+        end
+      end
+
+      # Launch the main instance (fetch after worktree setup to get modified paths)
       main_instance = @config.main_instance_config
       unless @prompt
         puts "🚀 Launching main instance: #{@config.main_instance}"
@@ -138,10 +196,66 @@ module ClaudeSwarm
       # Clean up child processes and run symlink
       cleanup_processes
       cleanup_run_symlink
+      cleanup_worktrees
     end
 
     private
 
+    def execute_before_commands(commands)
+      log_file = File.join(@session_path, "session.log") if @session_path
+
+      commands.each_with_index do |command, index|
+        # Log the command execution to session log
+        if @session_path
+          File.open(log_file, "a") do |f|
+            f.puts "[#{Time.now.strftime("%Y-%m-%d %H:%M:%S")}] Executing before command #{index + 1}/#{commands.size}: #{command}"
+          end
+        end
+
+        # Execute the command and capture output
+        begin
+          puts "Debug: Executing command #{index + 1}/#{commands.size}: #{command}" if @debug && !@prompt
+
+          # Use system with output capture
+          output = `#{command} 2>&1`
+          success = $CHILD_STATUS.success?
+
+          # Log the output
+          if @session_path
+            File.open(log_file, "a") do |f|
+              f.puts "Command output:"
+              f.puts output
+              f.puts "Exit status: #{$CHILD_STATUS.exitstatus}"
+              f.puts "-" * 80
+            end
+          end
+
+          # Show output if in debug mode or if command failed
+          if (@debug || !success) && !@prompt
+            puts "Command #{index + 1} output:"
+            puts output
+            puts "Exit status: #{$CHILD_STATUS.exitstatus}"
+          end
+
+          unless success
+            puts "❌ Before command #{index + 1} failed: #{command}" unless @prompt
+            return false
+          end
+        rescue StandardError => e
+          puts "Error executing before command #{index + 1}: #{e.message}" unless @prompt
+          if @session_path
+            File.open(log_file, "a") do |f|
+              f.puts "Error: #{e.message}"
+              f.puts "-" * 80
+            end
+          end
+          return false
+        end
+      end
+
+      true
+    end
+
     def save_swarm_config_path(session_path)
       # Copy the YAML config file to the session directory
       config_copy_path = File.join(session_path, "config.yml")
@@ -150,6 +264,20 @@ module ClaudeSwarm
       # Save the original working directory
       start_dir_file = File.join(session_path, "start_directory")
       File.write(start_dir_file, Dir.pwd)
+
+      # Save session metadata
+      metadata = {
+        "start_directory" => Dir.pwd,
+        "timestamp" => Time.now.utc.iso8601,
+        "swarm_name" => @config.swarm_name,
+        "claude_swarm_version" => VERSION
+      }
+
+      # Add worktree info if applicable
+      metadata["worktree"] = @worktree_manager.session_metadata if @worktree_manager
+
+      metadata_file = File.join(session_path, "session_metadata.json")
+      File.write(metadata_file, JSON.pretty_generate(metadata))
     end
 
     def setup_signal_handlers
@@ -158,6 +286,7 @@ module ClaudeSwarm
           puts "\n🛑 Received #{signal} signal, cleaning up..."
           cleanup_processes
           cleanup_run_symlink
+          cleanup_worktrees
           exit
         end
       end
@@ -170,6 +299,14 @@ module ClaudeSwarm
       puts "⚠️  Error during cleanup: #{e.message}"
     end
 
+    def cleanup_worktrees
+      return unless @worktree_manager
+
+      @worktree_manager.cleanup_worktrees
+    rescue StandardError => e
+      puts "⚠️  Error during worktree cleanup: #{e.message}"
+    end
+
     def create_run_symlink
       return unless @session_path
 
@@ -304,5 +441,31 @@ module ClaudeSwarm
         parts << "#{instance[:prompt]}\n\nNow just say 'I am ready to start'"
       end
     end
+
+    def restore_worktrees_if_needed(session_path)
+      metadata_file = File.join(session_path, "session_metadata.json")
+      return unless File.exist?(metadata_file)
+
+      metadata = JSON.parse(File.read(metadata_file))
+      worktree_data = metadata["worktree"]
+      return unless worktree_data && worktree_data["enabled"]
+
+      unless @prompt
+        puts "🌳 Restoring Git worktrees..."
+        puts
+      end
+
+      # Restore worktrees using the saved configuration
+      @worktree_manager = WorktreeManager.new(worktree_data["shared_name"])
+
+      # Get all instances and restore their worktree paths
+      all_instances = @config.instances.values
+      @worktree_manager.setup_worktrees(all_instances)
+
+      return if @prompt
+
+      puts "✓ Worktrees restored with branch: #{@worktree_manager.worktree_name}"
+      puts
+    end
   end
 end

data/lib/claude_swarm/version.rb

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

data/lib/claude_swarm/worktree_manager.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+require "open3"
+require "fileutils"
+require "json"
+require "pathname"
+require "securerandom"
+
+module ClaudeSwarm
+  class WorktreeManager
+    attr_reader :shared_worktree_name, :created_worktrees
+
+    def initialize(cli_worktree_option = nil, session_id: nil)
+      @cli_worktree_option = cli_worktree_option
+      @session_id = session_id
+      # Generate a name based on session ID if no option given, empty string, or default "worktree" from Thor
+      @shared_worktree_name = if cli_worktree_option.nil? || cli_worktree_option.empty? || cli_worktree_option == "worktree"
+                                generate_worktree_name
+                              else
+                                cli_worktree_option
+                              end
+      @created_worktrees = {} # Maps "repo_root:worktree_name" to worktree_path
+      @instance_worktree_configs = {} # Stores per-instance worktree settings
+    end
+
+    def setup_worktrees(instances)
+      # First pass: determine worktree configuration for each instance
+      instances.each do |instance|
+        worktree_config = determine_worktree_config(instance)
+        @instance_worktree_configs[instance[:name]] = worktree_config
+      end
+
+      # Second pass: create necessary worktrees
+      worktrees_to_create = collect_worktrees_to_create(instances)
+      worktrees_to_create.each do |repo_root, worktree_name|
+        create_worktree(repo_root, worktree_name)
+      end
+
+      # Third pass: map instance directories to worktree paths
+      instances.each do |instance|
+        worktree_config = @instance_worktree_configs[instance[:name]]
+
+        if ENV["CLAUDE_SWARM_DEBUG"]
+          puts "Debug [WorktreeManager]: Processing instance #{instance[:name]}"
+          puts "Debug [WorktreeManager]: Worktree config: #{worktree_config.inspect}"
+        end
+
+        next if worktree_config[:skip]
+
+        worktree_name = worktree_config[:name]
+        original_dirs = instance[:directories] || [instance[:directory]]
+        mapped_dirs = original_dirs.map { |dir| map_to_worktree_path(dir, worktree_name) }
+
+        if ENV["CLAUDE_SWARM_DEBUG"]
+          puts "Debug [WorktreeManager]: Original dirs: #{original_dirs.inspect}"
+          puts "Debug [WorktreeManager]: Mapped dirs: #{mapped_dirs.inspect}"
+        end
+
+        if instance[:directories]
+          instance[:directories] = mapped_dirs
+          # Also update the single directory field for backward compatibility
+          instance[:directory] = mapped_dirs.first
+        else
+          instance[:directory] = mapped_dirs.first
+        end
+
+        puts "Debug [WorktreeManager]: Updated instance[:directory] to: #{instance[:directory]}" if ENV["CLAUDE_SWARM_DEBUG"]
+      end
+    end
+
+    def map_to_worktree_path(original_path, worktree_name)
+      return original_path unless original_path
+
+      expanded_path = File.expand_path(original_path)
+      repo_root = find_git_root(expanded_path)
+
+      if ENV["CLAUDE_SWARM_DEBUG"]
+        puts "Debug [map_to_worktree_path]: Original path: #{original_path}"
+        puts "Debug [map_to_worktree_path]: Expanded path: #{expanded_path}"
+        puts "Debug [map_to_worktree_path]: Repo root: #{repo_root}"
+      end
+
+      return original_path unless repo_root
+
+      # Check if we have a worktree for this repo and name
+      worktree_key = "#{repo_root}:#{worktree_name}"
+      worktree_path = @created_worktrees[worktree_key]
+
+      if ENV["CLAUDE_SWARM_DEBUG"]
+        puts "Debug [map_to_worktree_path]: Worktree key: #{worktree_key}"
+        puts "Debug [map_to_worktree_path]: Worktree path: #{worktree_path}"
+        puts "Debug [map_to_worktree_path]: Created worktrees: #{@created_worktrees.inspect}"
+      end
+
+      return original_path unless worktree_path
+
+      # Calculate relative path from repo root
+      relative_path = Pathname.new(expanded_path).relative_path_from(Pathname.new(repo_root)).to_s
+
+      # Return the equivalent path in the worktree
+      result = if relative_path == "."
+                 worktree_path
+               else
+                 File.join(worktree_path, relative_path)
+               end
+
+      puts "Debug [map_to_worktree_path]: Result: #{result}" if ENV["CLAUDE_SWARM_DEBUG"]
+
+      result
+    end
+
+    def cleanup_worktrees
+      @created_worktrees.each do |worktree_key, worktree_path|
+        repo_root = worktree_key.split(":", 2).first
+        next unless File.exist?(worktree_path)
+
+        # Check for uncommitted changes
+        if has_uncommitted_changes?(worktree_path)
+          puts "⚠️  Warning: Worktree has uncommitted changes, skipping cleanup: #{worktree_path}" unless ENV["CLAUDE_SWARM_PROMPT"]
+          next
+        end
+
+        # Check for unpushed commits
+        if has_unpushed_commits?(worktree_path)
+          puts "⚠️  Warning: Worktree has unpushed commits, skipping cleanup: #{worktree_path}" unless ENV["CLAUDE_SWARM_PROMPT"]
+          next
+        end
+
+        puts "Removing worktree: #{worktree_path}" unless ENV["CLAUDE_SWARM_PROMPT"]
+
+        # Remove the worktree
+        output, status = Open3.capture2e("git", "-C", repo_root, "worktree", "remove", worktree_path)
+        next if status.success?
+
+        puts "Warning: Failed to remove worktree: #{output}"
+        # Try force remove
+        output, status = Open3.capture2e("git", "-C", repo_root, "worktree", "remove", "--force", worktree_path)
+        puts "Force remove result: #{output}" unless status.success?
+      end
+    rescue StandardError => e
+      puts "Error during worktree cleanup: #{e.message}"
+    end
+
+    def session_metadata
+      {
+        enabled: true,
+        shared_name: @shared_worktree_name,
+        created_paths: @created_worktrees.dup,
+        instance_configs: @instance_worktree_configs.dup
+      }
+    end
+
+    # Deprecated method for backward compatibility
+    def worktree_name
+      @shared_worktree_name
+    end
+
+    private
+
+    def generate_worktree_name
+      # Use session ID if available, otherwise generate a random suffix
+      if @session_id
+        "worktree-#{@session_id}"
+      else
+        # Fallback to random suffix for tests or when session ID is not available
+        random_suffix = SecureRandom.alphanumeric(5).downcase
+        "worktree-#{random_suffix}"
+      end
+    end
+
+    def determine_worktree_config(instance)
+      # Check instance-level worktree setting
+      instance_worktree = instance[:worktree]
+
+      if instance_worktree.nil?
+        # No instance-level setting, follow CLI behavior
+        if @cli_worktree_option.nil?
+          { skip: true }
+        else
+          { skip: false, name: @shared_worktree_name }
+        end
+      elsif instance_worktree == false
+        # Explicitly disabled for this instance
+        { skip: true }
+      elsif instance_worktree == true
+        # Use shared worktree (either from CLI or auto-generated)
+        { skip: false, name: @shared_worktree_name }
+      elsif instance_worktree.is_a?(String)
+        # Use custom worktree name
+        { skip: false, name: instance_worktree }
+      else
+        raise Error, "Invalid worktree configuration for instance '#{instance[:name]}': #{instance_worktree.inspect}"
+      end
+    end
+
+    def collect_worktrees_to_create(instances)
+      worktrees_needed = {}
+
+      instances.each do |instance|
+        worktree_config = @instance_worktree_configs[instance[:name]]
+        next if worktree_config[:skip]
+
+        worktree_name = worktree_config[:name]
+        directories = instance[:directories] || [instance[:directory]]
+
+        directories.each do |dir|
+          next unless dir
+
+          expanded_dir = File.expand_path(dir)
+          repo_root = find_git_root(expanded_dir)
+          next unless repo_root
+
+          # Track unique repo_root:worktree_name combinations
+          worktrees_needed[repo_root] ||= Set.new
+          worktrees_needed[repo_root].add(worktree_name)
+        end
+      end
+
+      # Convert to array of [repo_root, worktree_name] pairs
+      result = []
+      worktrees_needed.each do |repo_root, worktree_names|
+        worktree_names.each do |worktree_name|
+          result << [repo_root, worktree_name]
+        end
+      end
+      result
+    end
+
+    def find_git_root(path)
+      current = File.expand_path(path)
+
+      while current != "/"
+        return current if File.exist?(File.join(current, ".git"))
+
+        current = File.dirname(current)
+      end
+
+      nil
+    end
+
+    def create_worktree(repo_root, worktree_name)
+      worktree_key = "#{repo_root}:#{worktree_name}"
+      # Create worktrees inside the repository in a .worktrees directory
+      worktree_base_dir = File.join(repo_root, ".worktrees")
+      worktree_path = File.join(worktree_base_dir, worktree_name)
+
+      # Check if worktree already exists
+      if File.exist?(worktree_path)
+        puts "Using existing worktree: #{worktree_path}" unless ENV["CLAUDE_SWARM_PROMPT"]
+        @created_worktrees[worktree_key] = worktree_path
+        return
+      end
+
+      # Ensure .worktrees directory exists
+      FileUtils.mkdir_p(worktree_base_dir)
+
+      # Create .gitignore inside .worktrees to ignore all contents
+      gitignore_path = File.join(worktree_base_dir, ".gitignore")
+      File.write(gitignore_path, "# Ignore all worktree contents\n*\n") unless File.exist?(gitignore_path)
+
+      # Get current branch
+      output, status = Open3.capture2e("git", "-C", repo_root, "rev-parse", "--abbrev-ref", "HEAD")
+      raise Error, "Failed to get current branch in #{repo_root}: #{output}" unless status.success?
+
+      current_branch = output.strip
+
+      # Create worktree with a new branch based on current branch
+      branch_name = worktree_name
+      puts "Creating worktree: #{worktree_path} with branch: #{branch_name}" unless ENV["CLAUDE_SWARM_PROMPT"]
+
+      # Create worktree with a new branch
+      output, status = Open3.capture2e("git", "-C", repo_root, "worktree", "add", "-b", branch_name, worktree_path, current_branch)
+
+      # If branch already exists, try without -b flag
+      if !status.success? && output.include?("already exists")
+        puts "Branch #{branch_name} already exists, using existing branch" unless ENV["CLAUDE_SWARM_PROMPT"]
+        output, status = Open3.capture2e("git", "-C", repo_root, "worktree", "add", worktree_path, branch_name)
+      end
+
+      raise Error, "Failed to create worktree: #{output}" unless status.success?
+
+      @created_worktrees[worktree_key] = worktree_path
+    end
+
+    def has_uncommitted_changes?(worktree_path)
+      # Check if there are any uncommitted changes (staged or unstaged)
+      output, status = Open3.capture2e("git", "-C", worktree_path, "status", "--porcelain")
+      return false unless status.success?
+
+      # If output is not empty, there are changes
+      !output.strip.empty?
+    end
+
+    def has_unpushed_commits?(worktree_path)
+      # Get the current branch
+      branch_output, branch_status = Open3.capture2e("git", "-C", worktree_path, "rev-parse", "--abbrev-ref", "HEAD")
+      return false unless branch_status.success?
+
+      current_branch = branch_output.strip
+
+      # Check if the branch has an upstream
+      _, upstream_status = Open3.capture2e("git", "-C", worktree_path, "rev-parse", "--abbrev-ref", "#{current_branch}@{upstream}")
+
+      # If no upstream, check if there are any commits on this branch
+      unless upstream_status.success?
+        # Get the base branch (usually main or master)
+        base_branch = find_base_branch(worktree_path)
+
+        # If we can't find a base branch or this IS the base branch, check if there are any commits at all
+        if base_branch.nil? || current_branch == base_branch
+          # Check if this branch has any commits
+          commits_output, commits_status = Open3.capture2e("git", "-C", worktree_path, "rev-list", "--count", "HEAD")
+          return false unless commits_status.success?
+
+          # If there's more than 0 commits and no upstream, they're unpushed
+          return commits_output.strip.to_i.positive?
+        end
+
+        # Check if this branch has any commits not on the base branch
+        commits_output, commits_status = Open3.capture2e("git", "-C", worktree_path, "rev-list", "HEAD", "^#{base_branch}")
+        return false unless commits_status.success?
+
+        # If there are commits, they're unpushed (no upstream set)
+        return !commits_output.strip.empty?
+      end
+
+      # Check for unpushed commits
+      unpushed_output, unpushed_status = Open3.capture2e("git", "-C", worktree_path, "rev-list", "HEAD", "^#{current_branch}@{upstream}")
+      return false unless unpushed_status.success?
+
+      # If output is not empty, there are unpushed commits
+      !unpushed_output.strip.empty?
+    end
+
+    def find_base_branch(repo_path)
+      # Try to find the base branch - check for main, master, or the default branch
+      %w[main master].each do |branch|
+        _, status = Open3.capture2e("git", "-C", repo_path, "rev-parse", "--verify", "refs/heads/#{branch}")
+        return branch if status.success?
+      end
+
+      # Try to get the default branch from HEAD
+      output, status = Open3.capture2e("git", "-C", repo_path, "symbolic-ref", "refs/remotes/origin/HEAD")
+      if status.success?
+        # Extract branch name from refs/remotes/origin/main
+        branch_match = output.strip.match(%r{refs/remotes/origin/(.+)$})
+        return branch_match[1] if branch_match
+      end
+
+      nil
+    end
+  end
+end

data/llms.txt

@@ -57,7 +57,7 @@ A collection of Claude instances (agents) working together. One instance is desi
 An individual Claude Code agent with:
 - **description** (required): Role and responsibilities
 - **directory**: Working directory context
-- **model**: Claude model (opus/sonnet/haiku)
+- **model**: Claude model (opus/sonnet/claude-3-5-haiku-20241022)
 - **connections**: Other instances it can delegate to
 - **allowed_tools**: Tools this instance can use
 - **disallowed_tools**: Explicitly denied tools (override allowed)
@@ -79,7 +79,7 @@ swarm:
     instance_name:
       description: "Agent role description"  # REQUIRED
       directory: ~/path/to/dir              # Working directory
-      model: opus                           # opus/sonnet/haiku
+      model: opus                           # opus/sonnet/claude-3-5-haiku-20241022
       connections: [other1, other2]         # Connected instances
       prompt: "Custom system prompt"        # Additional instructions
       vibe: false                          # Skip permissions (default: false)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  version: 0.1.18
 platform: ruby
 authors:
 - Paulo Arruda
@@ -67,6 +67,7 @@ files:
 - example/test-generation.yml
 - examples/monitoring-demo.yml
 - examples/multi-directory.yml
+- examples/with-before-commands.yml
 - exe/claude-swarm
 - lib/claude_swarm.rb
 - lib/claude_swarm/claude_code_executor.rb
@@ -83,6 +84,7 @@ files:
 - lib/claude_swarm/session_path.rb
 - lib/claude_swarm/task_tool.rb
 - lib/claude_swarm/version.rb
+- lib/claude_swarm/worktree_manager.rb
 - llms.txt
 homepage: https://github.com/parruda/claude-swarm
 licenses: []