swarm_memory 2.0.0

data/lib/claude_swarm/process_tracker.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  class ProcessTracker
+    PIDS_DIR = "pids"
+
+    def initialize(session_path)
+      @session_path = session_path
+      @pids_dir = File.join(@session_path, PIDS_DIR)
+      ensure_pids_directory
+    end
+
+    def track_pid(pid, name)
+      pid_file = File.join(@pids_dir, pid.to_s)
+      File.write(pid_file, name)
+    end
+
+    def cleanup_all
+      return unless Dir.exist?(@pids_dir)
+
+      # Get all PID files
+      pid_files = Dir.glob(File.join(@pids_dir, "*"))
+
+      pid_files.each do |pid_file|
+        pid = File.basename(pid_file).to_i
+        name = begin
+          File.read(pid_file).strip
+        rescue StandardError
+          "unknown"
+        end
+
+        begin
+          # Check if process is still running
+          Process.kill(0, pid)
+          # If we get here, process is running, so kill it
+          Process.kill("TERM", pid)
+          puts "✓ Terminated MCP server: #{name} (PID: #{pid})"
+
+          # Give it a moment to terminate gracefully
+          sleep(0.1)
+
+          # Force kill if still running
+          begin
+            Process.kill(0, pid)
+            Process.kill("KILL", pid)
+            puts "  → Force killed #{name} (PID: #{pid})"
+          rescue Errno::ESRCH
+            # Process is gone, which is what we want
+          end
+        rescue Errno::ESRCH
+          # Process not found, already terminated
+          puts "  → MCP server #{name} (PID: #{pid}) already terminated"
+        rescue Errno::EPERM
+          # Permission denied
+          puts "  ⚠️  No permission to terminate #{name} (PID: #{pid})"
+        end
+      end
+
+      # Clean up the pids directory
+      FileUtils.rm_rf(@pids_dir)
+    end
+
+    class << self
+      def cleanup_session(session_path)
+        return unless Dir.exist?(File.join(session_path, PIDS_DIR))
+
+        tracker = new(session_path)
+        tracker.cleanup_all
+      end
+    end
+
+    private
+
+    def ensure_pids_directory
+      FileUtils.mkdir_p(@pids_dir)
+    end
+  end
+end

data/lib/claude_swarm/session_cost_calculator.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  module SessionCostCalculator
+    extend self
+
+    # Model pricing in dollars per million tokens
+    MODEL_PRICING = {
+      opus: {
+        input: 15.0,
+        output: 75.0,
+        cache_write: 18.75,
+        cache_read: 1.50,
+      },
+      sonnet: {
+        input: 3.0,
+        output: 15.0,
+        cache_write: 3.75,
+        cache_read: 0.30,
+      },
+      haiku: {
+        input: 0.80,
+        output: 4.0,
+        cache_write: 1.0,
+        cache_read: 0.08,
+      },
+    }.freeze
+
+    # Determine model type from model name
+    def model_type_from_name(model_name)
+      return unless model_name
+
+      model_name_lower = model_name.downcase
+      if model_name_lower.include?("opus")
+        :opus
+      elsif model_name_lower.include?("sonnet")
+        :sonnet
+      elsif model_name_lower.include?("haiku")
+        :haiku
+      end
+    end
+
+    # Calculate cost from token usage
+    def calculate_token_cost(usage, model_name)
+      model_type = model_type_from_name(model_name)
+      return 0.0 unless model_type && usage
+
+      pricing = MODEL_PRICING[model_type]
+      return 0.0 unless pricing
+
+      cost = 0.0
+
+      # Regular input tokens
+      if usage["input_tokens"]
+        cost += (usage["input_tokens"] / 1_000_000.0) * pricing[:input]
+      end
+
+      # Output tokens
+      if usage["output_tokens"]
+        cost += (usage["output_tokens"] / 1_000_000.0) * pricing[:output]
+      end
+
+      # Cache creation tokens (write)
+      if usage["cache_creation_input_tokens"]
+        cost += (usage["cache_creation_input_tokens"] / 1_000_000.0) * pricing[:cache_write]
+      end
+
+      # Cache read tokens
+      if usage["cache_read_input_tokens"]
+        cost += (usage["cache_read_input_tokens"] / 1_000_000.0) * pricing[:cache_read]
+      end
+
+      cost
+    end
+
+    # Calculate total cost from session log file
+    # Returns a hash with:
+    # - total_cost: Total cost in USD (sum of cost_usd for instances, token costs for main)
+    # - instances_with_cost: Set of instance names that have cost data
+    def calculate_total_cost(session_log_path)
+      return { total_cost: 0.0, instances_with_cost: Set.new } unless File.exist?(session_log_path)
+
+      # Track costs per instance - simple sum of cost_usd
+      instance_costs = {}
+      instances_with_cost = Set.new
+      main_instance_cost = 0.0
+
+      File.foreach(session_log_path) do |line|
+        data = JsonHandler.parse(line)
+        next if data == line # Skip unparseable lines
+
+        instance_name = data["instance"]
+        instance_id = data["instance_id"]
+
+        # Handle main instance token-based costs
+        if instance_id == "main" && data.dig("event", "type") == "assistant"
+          usage = data.dig("event", "message", "usage")
+          model = data.dig("event", "message", "model")
+          if usage && model
+            token_cost = calculate_token_cost(usage, model)
+            main_instance_cost += token_cost
+            instances_with_cost << instance_name if token_cost > 0
+          end
+        # Handle other instances with cost_usd (non-cumulative)
+        elsif instance_id != "main" && data.dig("event", "type") == "result"
+          # Use cost_usd (non-cumulative) instead of total_cost_usd (cumulative)
+          if (cost = data.dig("event", "cost_usd"))
+            instances_with_cost << instance_name
+            instance_costs[instance_name] ||= 0.0
+            instance_costs[instance_name] += cost
+          end
+        end
+      end
+
+      # Calculate total: sum of all instance costs + main instance token costs
+      other_instances_cost = instance_costs.values.sum
+      total_cost = other_instances_cost + main_instance_cost
+
+      {
+        total_cost: total_cost,
+        instances_with_cost: instances_with_cost,
+      }
+    end
+
+    # Calculate simple total cost (for backward compatibility)
+    def calculate_simple_total(session_log_path)
+      calculate_total_cost(session_log_path)[:total_cost]
+    end
+
+    # Parse instance hierarchy with costs from session log
+    # Returns a hash of instances with their cost data and relationships
+    def parse_instance_hierarchy(session_log_path)
+      instances = {}
+      # Track main instance token costs
+      main_instance_costs = {}
+
+      return instances unless File.exist?(session_log_path)
+
+      File.foreach(session_log_path) do |line|
+        data = JsonHandler.parse(line)
+        next if data == line # Skip unparseable lines
+
+        instance_name = data["instance"]
+        instance_id = data["instance_id"]
+        calling_instance = data["calling_instance"]
+
+        # Initialize instance data
+        instances[instance_name] ||= {
+          name: instance_name,
+          id: instance_id,
+          cost: 0.0,
+          calls: 0,
+          called_by: Set.new,
+          calls_to: Set.new,
+          has_cost_data: false,
+        }
+
+        # Track relationships
+        if calling_instance && calling_instance != instance_name
+          instances[instance_name][:called_by] << calling_instance
+
+          instances[calling_instance] ||= {
+            name: calling_instance,
+            id: data["calling_instance_id"],
+            cost: 0.0,
+            calls: 0,
+            called_by: Set.new,
+            calls_to: Set.new,
+            has_cost_data: false,
+          }
+          instances[calling_instance][:calls_to] << instance_name
+        end
+
+        # Handle main instance token-based costs
+        if instance_id == "main" && data.dig("event", "type") == "assistant"
+          usage = data.dig("event", "message", "usage")
+          model = data.dig("event", "message", "model")
+          if usage && model
+            token_cost = calculate_token_cost(usage, model)
+            if token_cost > 0
+              main_instance_costs[instance_name] ||= 0.0
+              main_instance_costs[instance_name] += token_cost
+              instances[instance_name][:has_cost_data] = true
+              instances[instance_name][:calls] += 1
+            end
+          end
+        # Track costs and calls for non-main instances using cost_usd
+        elsif data.dig("event", "type") == "result" && instance_id != "main"
+          instances[instance_name][:calls] += 1
+          # Use cost_usd (non-cumulative) instead of total_cost_usd
+          if (cost = data.dig("event", "cost_usd"))
+            instances[instance_name][:cost] += cost
+            instances[instance_name][:has_cost_data] = true
+          end
+        end
+      end
+
+      # Set main instance costs (replace, don't add)
+      main_instance_costs.each do |name, cost|
+        if instances[name]
+          # For main instances, use ONLY token costs, not cumulative costs
+          instances[name][:cost] = cost
+        end
+      end
+
+      instances
+    end
+  end
+end

data/lib/claude_swarm/session_path.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  module SessionPath
+    class << self
+      # Convert a directory path to a safe folder name using + as separator
+      def project_folder_name(working_dir = Dir.pwd)
+        # Don't expand path if it's already expanded (avoids double expansion on Windows)
+        path = working_dir.start_with?("/") || working_dir.match?(/^[A-Za-z]:/) ? working_dir : File.expand_path(working_dir)
+
+        # Handle Windows drive letters (C:\ → C)
+        path = path.gsub(/^([A-Za-z]):/, '\1')
+
+        # Remove leading slash/backslash
+        path = path.sub(%r{^[/\\]}, "")
+
+        # Replace all path separators with +
+        path.gsub(%r{[/\\]}, "+")
+      end
+
+      # Generate a full session path for a given directory and session ID
+      def generate(working_dir: Dir.pwd, session_id: SecureRandom.uuid)
+        project_name = project_folder_name(working_dir)
+        ClaudeSwarm.joined_sessions_dir(project_name, session_id)
+      end
+
+      # Ensure the session directory exists
+      def ensure_directory(session_path)
+        FileUtils.mkdir_p(session_path)
+
+        # Add .gitignore to swarm home if it doesn't exist
+        gitignore_path = ClaudeSwarm.joined_home_dir(".gitignore")
+        File.write(gitignore_path, "*\n") unless File.exist?(gitignore_path)
+      end
+
+      # Get the session path from environment (required)
+      def from_env
+        ENV["CLAUDE_SWARM_SESSION_PATH"] or raise "CLAUDE_SWARM_SESSION_PATH not set"
+      end
+    end
+  end
+end

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
+      JsonHandler.write_file!(settings_path(name), 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/system_utils.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  module SystemUtils
+    def system!(*args)
+      system(*args)
+      handle_command_failure(last_status, args)
+    end
+
+    def system_with_pid!(*args)
+      # Spawn the process - by default, inherits the parent's I/O
+      pid = Process.spawn(*args)
+
+      # Yield the PID to the block if given
+      yield(pid) if block_given?
+
+      # Wait for the process to complete
+      _, status = Process.wait2(pid)
+
+      # Check the exit status
+      handle_command_failure(status, args)
+    end
+
+    def last_status
+      $CHILD_STATUS
+    end
+
+    private
+
+    def handle_command_failure(status, args) # rubocop:disable Naming/PredicateMethod
+      return true if status&.success?
+
+      exit_status = status&.exitstatus || 1
+      command_str = args.size == 1 ? args.first : args.join(" ")
+
+      if exit_status == 143 # timeout command exit status = 128 + 15 (SIGTERM)
+        warn("⏱️ Command timeout: #{command_str}")
+      else
+        warn("❌ Command failed with exit status: #{exit_status}")
+        raise Error, "Command failed with exit status #{exit_status}: #{command_str}"
+      end
+
+      false
+    end
+  end
+end

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 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).
+
+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)
+- Support for OpenAI instances
+
+## 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: opus
+      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 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
+  - 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 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>
+
+
+IMPORTANT: Do not generate swarms with circular dependencies. For example, instance A connections to instance B, and instance B connections to instance A.