claude_swarm 0.1.19 → 0.1.20

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

@@ -0,0 +1,230 @@
+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
+<% if output_file %>
+The user has specified the output file: <%= output_file %>
+<% else %>
+Since no output file was specified, name the file based on the swarm's function. Examples:
+        - web-dev-swarm.yml for full-stack web development teams
+        - data-pipeline-swarm.yml for data processing teams
+        - microservices-swarm.yml for microservice architectures
+        - mobile-app-swarm.yml for mobile development teams
+        - ml-research-swarm.yml for machine learning teams
+        - devops-swarm.yml for infrastructure and deployment teams
+        Use descriptive names that clearly indicate the swarm's purpose.
+<% end %>
+
+## 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
+      allowed_tools: [Read, Edit, Write, Bash]
+      connections: [other_instance_names]  # Optional
+      prompt: |
+        Custom system prompt for specialization
+
+```
+
+## Best Practices to Follow
+- Use descriptive, role-based instance names (e.g., frontend_dev, api_architect)
+- Write prompts using multi-line strings to make them more readable.
+- 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>
+
+<prompt_best_practices>
+# Claude 4 prompt engineering best practices
+
+This guide provides specific prompt engineering techniques for Claude 4 models (Opus 4 and Sonnet 4) to help you achieve optimal results in your applications. These models have been trained for more precise instruction following than previous generations of Claude models.
+
+## General principles
+
+### Be explicit with your instructions
+
+Claude 4 models respond well to clear, explicit instructions. Being specific about your desired output can help enhance results. Customers who desire the "above and beyond" behavior from previous Claude models might need to more explicitly request these behaviors with Claude 4.
+
+**Less effective:**
+
+```text
+Create an analytics dashboard
+```
+
+**More effective:**
+
+```text
+Create an analytics dashboard. Include as many relevant features and interactions as possible. Go beyond the basics to create a fully-featured implementation.
+```
+
+### Add context to improve performance
+
+Providing context or motivation behind your instructions, such as explaining to Claude why such behavior is important, can help Claude 4 better understand your goals and deliver more targeted responses.
+
+**Less effective:**
+
+```text
+NEVER use ellipses
+```
+
+**More effective:**
+
+```text
+Your response will be read aloud by a text-to-speech engine, so never use ellipses since the text-to-speech engine will not know how to pronounce them.
+```
+
+Claude is smart enough to generalize from the explanation.
+
+### Be vigilant with examples & details
+
+Claude 4 models pay attention to details and examples as part of instruction following. Ensure that your examples align with the behaviors you want to encourage and minimize behaviors you want to avoid.
+
+## Guidance for specific situations
+
+### Control the format of responses
+
+There are a few ways that we have found to be particularly effective in seering output formatting in Claude 4 models:
+
+1. **Tell Claude what to do instead of what not to do**
+
+  * Instead of: "Do not use markdown in your response"
+  * Try: "Your response should be composed of smoothly flowing prose paragraphs."
+
+2. **Use XML format indicators**
+
+  * Try: "Write the prose sections of your response in <smoothly_flowing_prose_paragraphs> tags."
+
+3. **Match your prompt style to the desired output**
+
+  The formatting style used in your prompt may influence Claude's response style. If you are still experiencing steerability issues with output formatting, we recommend as best as you can matching your prompt style to your desired output style. For exmaple, removing markdown from your prompt can reduce the volume of markdown in the output.
+
+### Leverage thinking & interleaved thinking capabilities
+
+Claude 4 offers thinking capabilities that can be especially helpful for tasks involving reflection after tool use or complex multi-step reasoning. You can guide its initial or interleaved thinking for better results.
+
+```text Example prompt
+After receiving tool results, carefully reflect on their quality and determine optimal next steps before proceeding. Use your thinking to plan and iterate based on this new information, and then take the best next action.
+```
+
+### Optimize parallel tool calling
+
+Claude 4 models excel at parallel tool execution. They have a high success rate in using parallel tool calling without any prompting to do so, but some minor prompting can boost this behavior to ~100% parallel tool use success rate. We have found this prompt to be most effective:
+
+```text Sample prompt for agents
+For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+```
+
+### Reduce file creation in agentic coding
+
+Claude 4 models may sometimes create new files for testing and iteration purposes, particularly when working with code. This approach allows Claude to use files, especially python scripts, as a 'temporary scratchpad' before saving its final output. Using temporary files can improve outcomes particularly for agentic coding use cases.
+
+If you'd prefer to minimize net new file creation, you can instruct Claude to clean up after itself:
+
+```text Sample prompt
+If you create any temporary new files, scripts, or helper files for iteration, clean up these files by removing them at the end of the task.
+```
+
+### Enhance visual and frontend code generation
+
+For frontend code generation, you can steer Claude 4 models to create complex, detailed, and interactive designs by providing explicit encouragement:
+
+```text Sample prompt
+Don't hold back. Give it your all.
+```
+
+You can also improve Claude's frontend performance in specific areas by providing additional modifiers and details on what to focus on:
+
+* "Include as many relevant features and interactions as possible"
+* "Add thoughtful details like hover states, transitions, and micro-interactions"
+* "Create an impressive demonstration showcasing web development capabilities"
+* "Apply design principles: hierarchy, contrast, balance, and movement"
+
+### Avoid focusing on passing tests and hard-coding
+
+Frontier language models can sometimes focus too heavily on making tests pass at the expense of more general solutions. To prevent this behavior and ensure robust, generalizable solutions:
+
+```text
+Please write a high quality, general purpose solution. Implement a solution that works correctly for all valid inputs, not just the test cases. Do not hard-code values or create solutions that only work for specific test inputs. Instead, implement the actual logic that solves the problem generally.
+
+Focus on understanding the problem requirements and implementing the correct algorithm. Tests are there to verify correctness, not to define the solution. Provide a principled implementation that follows best practices and software design principles.
+
+If the task is unreasonable or infeasible, or if any of the tests are incorrect, please tell me. The solution should be robust, maintainable, and extendable.
+```
+
+1. **Be specific about desired behavior**: Consider describing exactly what you'd like to see in the output.
+
+2. **Frame your instructions with modifiers**: Adding modifiers that encourage Claude to increase the quality and detail of its output can help better shape Claude's performance. For example, instead of "Create an analytics dashboard", use "Create an analytics dashboard. Include as many relevant features and interactions as possible. Go beyond the basics to create a fully-featured implementation."
+
+3. **Request specific features explicitly**: Animations and interactive elements should be requested explicitly when desired.
+
+
+# Be clear, direct, and detailed
+
+When interacting with Claude, think of it as a brilliant but very new employee (with amnesia) who needs explicit instructions. Like any new employee, Claude does not have context on your norms, styles, guidelines, or preferred ways of working.
+The more precisely you explain what you want, the better Claude's response will be.
+
+**The golden rule of clear prompting:** Show your prompt to a colleague, ideally someone who has minimal context on the task, and ask them to follow the instructions. If they're confused, Claude will likely be too.
+
+## How to be clear, contextual, and specific
+
+* **Give Claude contextual information:** Just like you might be able to better perform on a task if you knew more context, Claude will perform better if it has more contextual information. Some examples of contextual information:
+  * What the task results will be used for
+  * What audience the output is meant for
+  * What workflow the task is a part of, and where this task belongs in that workflow
+  * The end goal of the task, or what a successful task completion looks like
+* **Be specific about what you want Claude to do:** For example, if you want Claude to output only code and nothing else, say so.
+* **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.1.19"
+  VERSION = "0.1.20"
 end

data/lib/claude_swarm/worktree_manager.rb

@@ -5,9 +5,11 @@ require "fileutils"
 require "json"
 require "pathname"
 require "securerandom"
+require "digest"
 
 module ClaudeSwarm
   class WorktreeManager
+    include SystemUtils
     attr_reader :shared_worktree_name, :created_worktrees
 
     def initialize(cli_worktree_option = nil, session_id: nil)
@@ -121,7 +123,9 @@ module ClaudeSwarm
         end
 
         # Check for unpushed commits
-        if has_unpushed_commits?(worktree_path)
+        has_unpushed = has_unpushed_commits?(worktree_path)
+
+        if has_unpushed
           puts "⚠️  Warning: Worktree has unpushed commits, skipping cleanup: #{worktree_path}" unless ENV["CLAUDE_SWARM_PROMPT"]
           next
         end
@@ -137,10 +141,37 @@ module ClaudeSwarm
         output, status = Open3.capture2e("git", "-C", repo_root, "worktree", "remove", "--force", worktree_path)
         puts "Force remove result: #{output}" unless status.success?
       end
+
+      # Clean up external worktree directories
+      cleanup_external_directories
     rescue StandardError => e
       puts "Error during worktree cleanup: #{e.message}"
     end
 
+    def cleanup_external_directories
+      # Remove session-specific worktree directory if it exists and is empty
+      return unless @session_id
+
+      session_worktree_dir = File.join(File.expand_path("~/.claude-swarm/worktrees"), @session_id)
+      return unless File.exist?(session_worktree_dir)
+
+      # Try to remove the directory tree
+      begin
+        # Remove all empty directories recursively
+        Dir.glob(File.join(session_worktree_dir, "**/*"), File::FNM_DOTMATCH).reverse_each do |path|
+          next if path.end_with?("/.", "/..")
+
+          FileUtils.rmdir(path) if File.directory?(path) && Dir.empty?(path)
+        end
+        # Finally try to remove the session directory itself
+        FileUtils.rmdir(session_worktree_dir) if Dir.empty?(session_worktree_dir)
+      rescue Errno::ENOTEMPTY
+        puts "Note: Session worktree directory not empty, leaving in place: #{session_worktree_dir}" unless ENV["CLAUDE_SWARM_PROMPT"]
+      rescue StandardError => e
+        puts "Warning: Error cleaning up worktree directories: #{e.message}" unless ENV["CLAUDE_SWARM_PROMPT"]
+      end
+    end
+
     def session_metadata
       {
         enabled: true,
@@ -157,6 +188,35 @@ module ClaudeSwarm
 
     private
 
+    def external_worktree_path(repo_root, worktree_name)
+      # Get repository name from path
+      repo_name = sanitize_repo_name(File.basename(repo_root))
+
+      # Add a short hash of the full path to handle multiple repos with same name
+      path_hash = Digest::SHA256.hexdigest(repo_root)[0..7]
+      unique_repo_name = "#{repo_name}-#{path_hash}"
+
+      # Build external path: ~/.claude-swarm/worktrees/[session_id]/[repo_name-hash]/[worktree_name]
+      base_dir = File.expand_path("~/.claude-swarm/worktrees")
+
+      # Validate base directory is accessible
+      begin
+        FileUtils.mkdir_p(base_dir)
+      rescue Errno::EACCES
+        # Fall back to temp directory if home is not writable
+        base_dir = File.join(Dir.tmpdir, ".claude-swarm", "worktrees")
+        FileUtils.mkdir_p(base_dir)
+      end
+
+      session_dir = @session_id || "default"
+      File.join(base_dir, session_dir, unique_repo_name, worktree_name)
+    end
+
+    def sanitize_repo_name(name)
+      # Replace problematic characters with underscores
+      name.gsub(/[^a-zA-Z0-9._-]/, "_")
+    end
+
     def generate_worktree_name
       # Use session ID if available, otherwise generate a random suffix
       if @session_id
@@ -240,9 +300,8 @@ module ClaudeSwarm
 
     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)
+      # Create worktrees in external directory
+      worktree_path = external_worktree_path(repo_root, worktree_name)
 
       # Check if worktree already exists
       if File.exist?(worktree_path)
@@ -251,12 +310,16 @@ module ClaudeSwarm
         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)
+      # Ensure parent directory exists with proper error handling
+      begin
+        FileUtils.mkdir_p(File.dirname(worktree_path))
+      rescue Errno::EACCES => e
+        raise Error, "Permission denied creating worktree directory: #{e.message}"
+      rescue Errno::ENOSPC => e
+        raise Error, "Not enough disk space for worktree: #{e.message}"
+      rescue StandardError => e
+        raise Error, "Failed to create worktree directory: #{e.message}"
+      end
 
       # Get current branch
       output, status = Open3.capture2e("git", "-C", repo_root, "rev-parse", "--abbrev-ref", "HEAD")
@@ -277,6 +340,26 @@ module ClaudeSwarm
         output, status = Open3.capture2e("git", "-C", repo_root, "worktree", "add", worktree_path, branch_name)
       end
 
+      # If worktree path is already in use, it might be from a previous run
+      if !status.success? && output.include?("is already used by worktree")
+        puts "Worktree path already in use, checking if it's valid" unless ENV["CLAUDE_SWARM_PROMPT"]
+        # Check if the worktree actually exists at that path
+        if File.exist?(File.join(worktree_path, ".git"))
+          puts "Using existing worktree: #{worktree_path}" unless ENV["CLAUDE_SWARM_PROMPT"]
+          @created_worktrees[worktree_key] = worktree_path
+          return
+        else
+          # The worktree is registered but the directory doesn't exist, prune and retry
+          puts "Pruning stale worktree references" unless ENV["CLAUDE_SWARM_PROMPT"]
+          begin
+            system!("git", "-C", repo_root, "worktree", "prune")
+          rescue Error
+            # Ignore errors when pruning
+          end
+          output, status = Open3.capture2e("git", "-C", repo_root, "worktree", "add", worktree_path, branch_name)
+        end
+      end
+
       raise Error, "Failed to create worktree: #{output}" unless status.success?
 
       @created_worktrees[worktree_key] = worktree_path
@@ -301,35 +384,56 @@ module ClaudeSwarm
       # 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 branch has upstream, check against it
+      if upstream_status.success?
+        # Check for unpushed commits against upstream
+        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
+        return !unpushed_output.strip.empty?
+      end
 
-        # 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?
+      # No upstream - this is likely a new branch created by the worktree
+      # The key insight: when git worktree add -b creates a branch, it creates it in BOTH
+      # the worktree AND the main repository. So we need to check the reflog in the worktree
+      # to see if any NEW commits were made after the worktree was created.
 
-          # If there's more than 0 commits and no upstream, they're unpushed
-          return commits_output.strip.to_i.positive?
-        end
+      # Use reflog to check if any commits were made in this worktree
+      reflog_output, reflog_status = Open3.capture2e("git", "-C", worktree_path, "reflog", "--format=%H %gs", current_branch)
 
-        # 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 reflog_status.success? && !reflog_output.strip.empty?
+        reflog_lines = reflog_output.strip.split("\n")
 
-        # If there are commits, they're unpushed (no upstream set)
-        return !commits_output.strip.empty?
+        # Look for commit entries (not branch creation)
+        commit_entries = reflog_lines.select { |line| line.include?(" commit:") || line.include?(" commit (amend):") }
+
+        # If there are commit entries in the reflog, there are unpushed commits
+        return !commit_entries.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?
+      # As a fallback, assume no unpushed commits
+      false
+    end
+
+    def find_original_repo_for_worktree(worktree_path)
+      # Get the git directory for this worktree
+      _, git_dir_status = Open3.capture2e("git", "-C", worktree_path, "rev-parse", "--git-dir")
+      return nil unless git_dir_status.success?
+
+      # Read the gitdir file to find the main repository
+      # Worktree .git files contain: gitdir: /path/to/main/repo/.git/worktrees/worktree-name
+      if File.file?(File.join(worktree_path, ".git"))
+        gitdir_content = File.read(File.join(worktree_path, ".git")).strip
+        if gitdir_content =~ /^gitdir: (.+)$/
+          git_path = $1
+          # Extract the main repo path from the worktree git path
+          # Format: /path/to/repo/.git/worktrees/worktree-name
+          return $1 if git_path =~ %r{^(.+)/\.git/worktrees/[^/]+$}
+        end
+      end
 
-      # If output is not empty, there are unpushed commits
-      !unpushed_output.strip.empty?
+      nil
     end
 
     def find_base_branch(repo_path)

data/lib/claude_swarm.rb

@@ -1,17 +1,26 @@
 # frozen_string_literal: true
 
-require_relative "claude_swarm/version"
-require_relative "claude_swarm/cli"
-require_relative "claude_swarm/configuration"
-require_relative "claude_swarm/mcp_generator"
-require_relative "claude_swarm/orchestrator"
-require_relative "claude_swarm/claude_code_executor"
-require_relative "claude_swarm/claude_mcp_server"
-require_relative "claude_swarm/session_path"
-require_relative "claude_swarm/session_info_tool"
-require_relative "claude_swarm/reset_session_tool"
-require_relative "claude_swarm/task_tool"
-require_relative "claude_swarm/process_tracker"
+# External dependencies
+require "time"
+require "thor"
+require "yaml"
+require "json"
+require "fileutils"
+require "erb"
+require "tmpdir"
+require "open3"
+require "timeout"
+require "pty"
+require "io/console"
+
+# Zeitwerk setup
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/claude_swarm/templates")
+loader.inflector.inflect(
+  "cli" => "CLI"
+)
+loader.setup
 
 module ClaudeSwarm
   class Error < StandardError; 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/claude-3-5-haiku-20241022)
+- **model**: Claude model (opus/sonnet)
 - **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/claude-3-5-haiku-20241022
+      model: opus                           # opus/sonnet
       connections: [other1, other2]         # Connected instances
       prompt: "Custom system prompt"        # Additional instructions
       vibe: false                          # Skip permissions (default: false)