claude_swarm 0.1.19 → 0.1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecbec0c31b9252f826e28978e871cdc0003644d691a541906a8c36ae60c717f6
-  data.tar.gz: 9d88ab7118d614108adcd2995b270f3c223e08a0a7ccd8768136f362f9f002d6
+  metadata.gz: fdad008c72dacb5ca491dc7c6b912c4bc8d46c7f2b578b3762ed7b5e09b4e3f4
+  data.tar.gz: a426057ff0bb859cd56a0bec71e80d02c1232fe6eb69a74e47ed3044f7121a58
 SHA512:
-  metadata.gz: 66783c2bc619846d7ce78b33e290d34b414946a5e66714f0528ef312a1e641cc9c6950e30d492e1f428374da391f39e11556bffaa68ced4b4cda726987ea4a8c
-  data.tar.gz: f04e7f694fb8f151c5ccfa4bd145a2184cb7674b78a1c3af414704664b6efadd5887d9f78e3ad8da4d7f41a25bdfb8e23d355eb79c4bb7675aebb79424995a59
+  metadata.gz: b7fb86ea647403073665b860dde694ef2ae0c983f8fc011189d999f97d57e8b80f552b9e736b1f46cb888ac3c4877666dac060e1335db39bd2719f120ad35937
+  data.tar.gz: f1670e4c35e9681054dbe5ab2bcc87d7ef24a6ad4f33a21d3e445c32cb1e917eedbc2984c483b06750469fa08e8256109693a121f337ff813a8ff1944ecc42f1

data/.rubocop.yml

@@ -37,6 +37,9 @@ Naming/AccessorMethodName:
 Metrics/BlockLength:
   Enabled: false
 
+Metrics/BlockNesting:
+  Enabled: false  
+
 Metrics/ClassLength:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.1.20]
+
+### Added
+- **External worktree directory**: Git worktrees are now created in `~/.claude-swarm/worktrees/` for better isolation from the main repository
+  - Prevents conflicts with bundler and other tools
+  - Each unique Git repository gets its own worktree with the same name
+  - Session metadata tracks worktree information for restoration
+- **Zeitwerk autoloading**: Implemented Zeitwerk for better code organization and loading
+
+### Changed
+- **Improved team coordination**: Removed circular dependencies in team configurations
+- **Better code organization**: Refactored code structure to work with Zeitwerk autoloading
+
+### Internal
+- Updated Gemfile.lock to include zeitwerk dependency
+- Added prompt best practices documentation
+
 ## [0.1.19]
 
 ### Added

data/CLAUDE.md

@@ -71,14 +71,15 @@ instances:
 ```
 
 ### Worktree Behavior
-- Worktrees are created inside each repository in a `.worktrees/` directory
-- A `.gitignore` file is automatically created inside `.worktrees/` to ignore all contents
+- Worktrees are created in external directory: `~/.claude-swarm/worktrees/[session_id]/[repo_name-hash]/[worktree_name]`
+- This ensures proper isolation from the main repository and avoids conflicts with bundler and other tools
 - 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
+- The `claude-swarm clean` command removes orphaned worktrees
 
 ## Architecture
 

data/README.md

@@ -27,7 +27,13 @@ Claude Swarm orchestrates multiple Claude Code instances as a collaborative AI d
 
 ## Installation
 
-Install the gem by executing:
+Install [Claude CLI](https://docs.anthropic.com/en/docs/claude-code/overview) if you haven't already:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+Install this gem by executing:
 
 ```bash
 gem install claude_swarm
@@ -522,17 +528,16 @@ swarm:
 
 #### 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.
+Claude Swarm supports running instances in Git worktrees, allowing isolated work without affecting your main repository state. Worktrees are created in an external directory (`~/.claude-swarm/worktrees/`) to ensure proper isolation from the main repository and avoid conflicts with bundler and other tools.
 
 **Example Structure:**
 ```
-my-repo/
-├── .git/
-├── .worktrees/        (created by Claude Swarm)
-│   ├── .gitignore     (auto-created, contains "*")
-│   └── feature-x/     (worktree for feature-x branch)
-├── src/
-└── tests/
+~/.claude-swarm/worktrees/
+└── [session_id]/
+    ├── my-repo-[hash]/
+    │   └── feature-x/     (worktree for feature-x branch)
+    └── other-repo-[hash]/
+        └── feature-x/     (worktree for feature-x branch)
 ```
 
 **CLI Option:**
@@ -577,14 +582,14 @@ swarm:
 - 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
+- Worktrees are stored externally in `~/.claude-swarm/worktrees/[session_id]/`
 - 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
+- The `claude-swarm clean` command also removes orphaned worktrees
 
 ### Command Line Options
 
@@ -652,10 +657,10 @@ claude-swarm watch 20250617_235233 -n 50
 claude-swarm list-sessions
 claude-swarm list-sessions --limit 20
 
-# Clean up stale session symlinks
+# Clean up stale session symlinks and orphaned worktrees
 claude-swarm clean
 
-# Remove sessions older than 30 days
+# Remove sessions and worktrees older than 30 days
 claude-swarm clean --days 30
 ```
 

data/examples/monitoring-demo.yml

@@ -6,7 +6,7 @@ swarm:
     coordinator:
       description: "Main coordinator managing the team"
       directory: .
-      model: haiku
+      model: sonnet
       connections: [analyzer, reporter]
       prompt: "You coordinate analysis and reporting tasks"
       allowed_tools: [Read, Edit]
@@ -14,13 +14,13 @@ swarm:
     analyzer:
       description: "Data analyzer processing information"
       directory: ./data
-      model: haiku  
+      model: sonnet  
       prompt: "You analyze data and provide insights"
       allowed_tools: [Read, Bash]
     
     reporter:
       description: "Report generator creating summaries"
       directory: ./reports
-      model: haiku
+      model: sonnet
       prompt: "You generate reports from analysis"
-      allowed_tools: [Write, Edit]
+      allowed_tools: [Write, Edit]

data/lib/claude_swarm/claude_code_executor.rb

@@ -4,7 +4,6 @@ require "json"
 require "open3"
 require "logger"
 require "fileutils"
-require_relative "session_path"
 
 module ClaudeSwarm
   class ClaudeCodeExecutor

data/lib/claude_swarm/claude_mcp_server.rb

@@ -2,11 +2,6 @@
 
 require "fast_mcp_annotations"
 require "json"
-require_relative "claude_code_executor"
-require_relative "task_tool"
-require_relative "session_info_tool"
-require_relative "reset_session_tool"
-require_relative "process_tracker"
 
 module ClaudeSwarm
   class ClaudeMcpServer

data/lib/claude_swarm/cli.rb

@@ -2,13 +2,11 @@
 
 require "thor"
 require "json"
-require_relative "configuration"
-require_relative "mcp_generator"
-require_relative "orchestrator"
-require_relative "claude_mcp_server"
+require "erb"
 
 module ClaudeSwarm
   class CLI < Thor
+    include SystemUtils
     def self.exit_on_failure?
       true
     end
@@ -207,7 +205,9 @@ module ClaudeSwarm
                           desc: "Claude model to use for generation"
     def generate
       # Check if claude command exists
-      unless system("which claude > /dev/null 2>&1")
+      begin
+        system!("command -v claude > /dev/null 2>&1")
+      rescue Error
         error "Claude CLI is not installed or not in PATH"
         say "To install Claude CLI, visit: https://docs.anthropic.com/en/docs/claude-code"
         exit 1
@@ -238,49 +238,30 @@ module ClaudeSwarm
 
     desc "ps", "List running Claude Swarm sessions"
     def ps
-      require_relative "commands/ps"
       Commands::Ps.new.execute
     end
 
     desc "show SESSION_ID", "Show detailed session information"
     def show(session_id)
-      require_relative "commands/show"
       Commands::Show.new.execute(session_id)
     end
 
-    desc "clean", "Remove stale session symlinks"
+    desc "clean", "Remove stale session symlinks and orphaned worktrees"
     method_option :days, aliases: "-d", type: :numeric, default: 7,
                          desc: "Remove sessions older than N days"
     def clean
-      run_dir = File.expand_path("~/.claude-swarm/run")
-      unless Dir.exist?(run_dir)
-        say "No run directory found", :yellow
-        return
-      end
+      # Clean stale symlinks
+      cleaned_symlinks = clean_stale_symlinks(options[:days])
 
-      cleaned = 0
-      Dir.glob("#{run_dir}/*").each do |symlink|
-        next unless File.symlink?(symlink)
+      # Clean orphaned worktrees
+      cleaned_worktrees = clean_orphaned_worktrees(options[:days])
 
-        begin
-          # Remove if target doesn't exist (stale)
-          unless File.exist?(File.readlink(symlink))
-            File.unlink(symlink)
-            cleaned += 1
-            next
-          end
-
-          # Remove if older than specified days
-          if File.stat(symlink).mtime < Time.now - (options[:days] * 86_400)
-            File.unlink(symlink)
-            cleaned += 1
-          end
-        rescue StandardError
-          # Skip problematic symlinks
-        end
+      if cleaned_symlinks.positive? || cleaned_worktrees.positive?
+        say "Cleaned #{cleaned_symlinks} stale symlink#{"s" unless cleaned_symlinks == 1}", :green
+        say "Cleaned #{cleaned_worktrees} orphaned worktree#{"s" unless cleaned_worktrees == 1}", :green
+      else
+        say "No cleanup needed", :green
       end
-
-      say "Cleaned #{cleaned} stale session#{"s" unless cleaned == 1}", :green
     end
 
     desc "watch SESSION_ID", "Watch session logs"
@@ -477,81 +458,91 @@ module ClaudeSwarm
       nil
     end
 
+    def clean_stale_symlinks(days)
+      run_dir = File.expand_path("~/.claude-swarm/run")
+      return 0 unless Dir.exist?(run_dir)
+
+      cleaned = 0
+      Dir.glob("#{run_dir}/*").each do |symlink|
+        next unless File.symlink?(symlink)
+
+        begin
+          # Remove if target doesn't exist (stale)
+          unless File.exist?(File.readlink(symlink))
+            File.unlink(symlink)
+            cleaned += 1
+            next
+          end
+
+          # Remove if older than specified days
+          if File.stat(symlink).mtime < Time.now - (days * 86_400)
+            File.unlink(symlink)
+            cleaned += 1
+          end
+        rescue StandardError
+          # Skip problematic symlinks
+        end
+      end
+
+      cleaned
+    end
+
+    def clean_orphaned_worktrees(days)
+      worktrees_dir = File.expand_path("~/.claude-swarm/worktrees")
+      return 0 unless Dir.exist?(worktrees_dir)
+
+      sessions_dir = File.expand_path("~/.claude-swarm/sessions")
+      cleaned = 0
+
+      Dir.glob("#{worktrees_dir}/*").each do |session_worktree_dir|
+        session_id = File.basename(session_worktree_dir)
+
+        # Skip if session still exists
+        next if Dir.glob("#{sessions_dir}/*/#{session_id}").any? { |path| File.exist?(File.join(path, "config.yml")) }
+
+        # Check age of worktree directory
+        begin
+          if File.stat(session_worktree_dir).mtime < Time.now - (days * 86_400)
+            # Remove all git worktrees in this session directory
+            Dir.glob("#{session_worktree_dir}/*/*").each do |worktree_path|
+              next unless File.directory?(worktree_path)
+
+              # Try to find the git repo and remove the worktree properly
+              git_dir = File.join(worktree_path, ".git")
+              if File.exist?(git_dir)
+                # Read the gitdir file to find the repo
+                gitdir_content = File.read(git_dir).strip
+                if gitdir_content.start_with?("gitdir:")
+                  repo_git_path = gitdir_content.sub("gitdir: ", "")
+                  # Extract repo path from .git/worktrees path
+                  repo_path = repo_git_path.split("/.git/worktrees/").first
+
+                  # Try to remove worktree via git
+                  system!("git", "-C", repo_path, "worktree", "remove", worktree_path, "--force",
+                          out: File::NULL, err: File::NULL)
+                end
+              end
+
+              # Force remove directory if it still exists
+              FileUtils.rm_rf(worktree_path)
+            end
+
+            # Remove the session worktree directory
+            FileUtils.rm_rf(session_worktree_dir)
+            cleaned += 1
+          end
+        rescue StandardError => e
+          say "Warning: Failed to clean worktree directory #{session_worktree_dir}: #{e.message}", :yellow if options[:debug]
+        end
+      end
+
+      cleaned
+    end
+
     def build_generation_prompt(readme_content, output_file)
-      <<~PROMPT
-        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.
-
-        ## 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).
-
-        Key capabilities:
-        - Define multiple AI instances with different roles and specializations
-        - Set up connections between instances for collaboration
-        - Restrict tools based on each instance's responsibilities
-        - 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)
-
-        ## Your Task
-        1. Start by asking about the user's project structure and development needs
-        2. Understand what kind of team they need (roles, specializations)
-        3. Suggest an appropriate swarm topology based on their needs
-        4. Help them refine and customize the configuration
-        5. Generate the final claude-swarm.yml content
-        6. When the configuration is complete, save it to: #{output_file || "a descriptive filename based on the swarm's function"}
-
-        ## File Naming Convention
-        #{output_file ? "The user has specified the output file: #{output_file}" : "Since no output file was specified, name the file based on the swarm's function. Examples:\n        - web-dev-swarm.yml for full-stack web development teams\n        - data-pipeline-swarm.yml for data processing teams\n        - microservices-swarm.yml for microservice architectures\n        - mobile-app-swarm.yml for mobile development teams\n        - ml-research-swarm.yml for machine learning teams\n        - devops-swarm.yml for infrastructure and deployment teams\n        Use descriptive names that clearly indicate the swarm's purpose."}
-
-        ## Configuration Structure
-        ```yaml
-        version: 1
-        swarm:
-          name: "Descriptive Swarm Name"
-          main: main_instance_name
-          instances:
-            instance_name:
-              description: "Clear description of role and responsibilities"
-              directory: ./path/to/directory
-              model: sonnet  # or opus for complex tasks
-              prompt: "Custom system prompt for specialization"
-              allowed_tools: [Read, Edit, Write, Bash]
-              connections: [other_instance_names]  # Optional
-        ```
-
-        ## Best Practices to Follow
-        - Use descriptive, role-based instance names (e.g., frontend_dev, api_architect)
-        - 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.
-        - 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
-          - Edit: For active development roles
-          - Write: For creating new files
-          - Bash: For running commands, tests, builds
-          - MultiEdit: For editing multiple files at once
-          - WebFetch: For fetching information from the web
-          - WebSearch: For searching the web
-        - Use custom prompts to specialize each instance's expertise
-        - Organize directories to match project structure
-
-        ## 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)?
-        - Are there specific areas that need focused attention?
-        - Do you have multiple repositories or services to coordinate?
-
-        <full_readme>
-        #{readme_content}
-        </full_readme>
-
-        Start the conversation by greeting the user and asking: "What kind of project would you like to create a Claude Swarm for?"
-      PROMPT
+      template_path = File.expand_path("templates/generation_prompt.md.erb", __dir__)
+      template = File.read(template_path)
+      ERB.new(template, trim_mode: "-").result(binding)
     end
   end
 end

data/lib/claude_swarm/mcp_generator.rb

@@ -4,7 +4,6 @@ require "json"
 require "fileutils"
 require "shellwords"
 require "securerandom"
-require_relative "session_path"
 
 module ClaudeSwarm
   class McpGenerator

data/lib/claude_swarm/orchestrator.rb

@@ -4,12 +4,10 @@ require "English"
 require "shellwords"
 require "json"
 require "fileutils"
-require_relative "session_path"
-require_relative "process_tracker"
-require_relative "worktree_manager"
 
 module ClaudeSwarm
   class Orchestrator
+    include SystemUtils
     RUN_DIR = File.expand_path("~/.claude-swarm/run")
 
     def initialize(configuration, mcp_generator, vibe: false, prompt: nil, stream_logs: false, debug: false,
@@ -174,7 +172,7 @@ module ClaudeSwarm
 
       command = build_main_command(main_instance)
       if @debug && !@prompt
-        puts "Running: #{command}"
+        puts "🏃 Running: #{format_command_for_display(command)}"
         puts
       end
 
@@ -184,7 +182,7 @@ module ClaudeSwarm
 
       # Execute the main instance - this will cascade to other instances via MCP
       Dir.chdir(main_instance[:directory]) do
-        system(*command)
+        system!(*command)
       end
 
       # Clean up log streaming thread
@@ -362,6 +360,16 @@ module ClaudeSwarm
       end
     end
 
+    def format_command_for_display(command)
+      command.map do |part|
+        if part.match?(/\s|'|"/)
+          "'#{part.gsub("'", "'\\\\''")}'"
+        else
+          part
+        end
+      end.join(" ")
+    end
+
     def build_main_command(instance)
       parts = [
         "claude",
@@ -456,7 +464,9 @@ module ClaudeSwarm
       end
 
       # Restore worktrees using the saved configuration
-      @worktree_manager = WorktreeManager.new(worktree_data["shared_name"])
+      # Extract session ID from the session path
+      session_id = File.basename(session_path)
+      @worktree_manager = WorktreeManager.new(worktree_data["shared_name"], session_id: session_id)
 
       # Get all instances and restore their worktree paths
       all_instances = @config.instances.values

data/lib/claude_swarm/system_utils.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "English"
+
+module ClaudeSwarm
+  module SystemUtils
+    def system!(*args)
+      success = system(*args)
+      unless success
+        exit_status = $CHILD_STATUS&.exitstatus || 1
+        command_str = args.size == 1 ? args.first : args.join(" ")
+        warn "❌ Command failed with exit status: #{exit_status}"
+        raise Error, "Command failed with exit status #{exit_status}: #{command_str}"
+      end
+      success
+    end
+  end
+end