claude_swarm 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d324ca820897ad2929051a87d06f152df536434522f42cba507a9c6984b019f
-  data.tar.gz: bd2f9659c374ee277e3f20e4fd339b542887c394730acf5682a90d9c06cfcfb1
+  metadata.gz: c468e30d7de839a1b7bb88c2e2ee1c9bfa58b8bb0f0b0375b3495ebf5de340f0
+  data.tar.gz: 7234799e8b24cc2b0a691f188a890ee84d0780a77a85723307bdc9f17ad71545
 SHA512:
-  metadata.gz: 4ec9b2c70924671846cbfbaf98ddd93869b2e84162c199559b7551ae833bb73ac62950f4bee9dc19f59a138997c4873f6fb8746fa56f5cf1769855e01cdd74e3
-  data.tar.gz: 64cc15a5ee7844f900eda0097e539046d730e4eb07b1323217a55dee9b965db506b1c3838d15e311291edc133296191a80a92769727cce84361cba6b5a2c7f0a
+  metadata.gz: 7ed4d3460c8e686f683513796939827419d254d9b4a168a211d24d89cb18aaeb4cacf42a2dd90d1b88ecbc98ab97f7391b356ed24f0beb05da4bab6c62ce5332
+  data.tar.gz: ced867554fa8b43c6ce9f327f791212dcc04a87c378d78e99c87f41776074eba7f2a1bf7691b6b9daaf34fcd7923b057cefe453171d5838f2981ee87d67237f1

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [0.1.12]
+### Added
+- **Circular dependency detection**: Configuration validation now detects and reports circular dependencies between instances
+- Clear error messages showing the dependency cycle (e.g., "Circular dependency detected: lead -> backend -> lead")
+- Comprehensive test coverage for various circular dependency scenarios
+- **Session management improvements**: Session files are now stored in `~/.claude-swarm/sessions/` organized by project path
+- Added `SessionPath` module to centralize session path management
+- Sessions are now organized by project directory for better multi-project support
+- Added `CLAUDE_SWARM_HOME` environment variable support for custom storage location
+- Log full JSON to `session.log.json` as JSONL
+
+### Changed
+- Session files moved from `./.claude-swarm/sessions/` to `~/.claude-swarm/sessions/[project]/[timestamp]/`
+- Replaced `CLAUDE_SWARM_SESSION_TIMESTAMP` with `CLAUDE_SWARM_SESSION_PATH` environment variable
+- MCP server configurations now use the new centralized session path
+
+### Fixed
+- Fixed circular dependency example in README documentation
+
+## [0.1.11]
+### Added
+- Main instance debug mode with `claude-swarm --debug`
+
 ## [0.1.10]
 
 ### Added

data/README.md

@@ -1,6 +1,6 @@
 # Claude Swarm
 
-[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=1)](https://badge.fury.io/rb/claude_swarm)
+[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=0.1.11)](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.
@@ -48,15 +48,12 @@ swarm:
       directory: .
       model: opus
       connections: [frontend, backend]
-      allowed_tools: # Tools aren't required if you run it with `--vibe`
-        - Read
-        - Edit
-        - Bash
+      vibe: true   # Allow all tools for this instance
     frontend:
       description: "Frontend specialist handling UI and user experience"
       directory: ./frontend
       model: opus
-      allowed_tools:
+      allowed_tools:  # Tools aren't required if you run it with `--vibe`
         - Edit
         - Write
         - Bash
@@ -330,7 +327,7 @@ swarm:
       description: "Backend developer building APIs and services"
       directory: ./backend
       model: opus
-      connections: [architect, database]
+      connections: [database]
       allowed_tools:
         - Edit
         - Write

data/claude-swarm.yml

@@ -0,0 +1,42 @@
+version: 1
+swarm:
+  name: "Swarm Name"
+  main: lead_developer
+  instances:
+    lead_developer:
+      description: "Lead developer who coordinates the team and makes architectural decisions"
+      directory: .
+      model: sonnet
+      prompt: "You are the lead developer coordinating the team"
+      allowed_tools: [Read, Edit, Bash, Write]
+      connections: [frontend_dev, backend_dev]
+
+    # Example instances (uncomment and modify as needed):
+
+    frontend_dev:
+      description: "Frontend developer specializing in React and modern web technologies"
+      directory: .
+      model: sonnet
+      prompt: "You specialize in frontend development with React, TypeScript, and modern web technologies"
+      allowed_tools: [Read, Edit, Write, "Bash(npm:*)", "Bash(yarn:*)", "Bash(pnpm:*)"]
+
+    backend_dev:
+      description: "Backend developer focusing on APIs, databases, and server architecture"
+      directory: .
+      model: sonnet
+      prompt: "You specialize in backend development, APIs, databases, and server architecture"
+      allowed_tools: [Read, Edit, Write, Bash]
+
+    # devops_engineer:
+    #   description: "DevOps engineer managing infrastructure, CI/CD, and deployments"
+    #   directory: .
+    #   model: sonnet
+    #   prompt: "You specialize in infrastructure, CI/CD, containerization, and deployment"
+    #   allowed_tools: [Read, Edit, Write, "Bash(docker:*)", "Bash(kubectl:*)", "Bash(terraform:*)"]
+
+    # qa_engineer:
+    #   description: "QA engineer ensuring quality through comprehensive testing"
+    #   directory: ./tests
+    #   model: sonnet
+    #   prompt: "You specialize in testing, quality assurance, and test automation"
+    #   allowed_tools: [Read, Edit, Write, Bash]

data/lib/claude_swarm/claude_code_executor.rb

@@ -4,13 +4,11 @@ require "json"
 require "open3"
 require "logger"
 require "fileutils"
+require_relative "session_path"
 
 module ClaudeSwarm
   class ClaudeCodeExecutor
-    SWARM_DIR = ".claude-swarm"
-    SESSIONS_DIR = "sessions"
-
-    attr_reader :session_id, :last_response, :working_directory, :logger, :session_timestamp
+    attr_reader :session_id, :last_response, :working_directory, :logger, :session_path
 
     def initialize(working_directory: Dir.pwd, model: nil, mcp_config: nil, vibe: false, instance_name: nil, calling_instance: nil)
       @working_directory = working_directory
@@ -95,17 +93,13 @@ module ClaudeSwarm
     private
 
     def setup_logging
-      # Use environment variable for session timestamp if available (set by orchestrator)
-      # Otherwise create a new timestamp
-      @session_timestamp = ENV["CLAUDE_SWARM_SESSION_TIMESTAMP"] || Time.now.strftime("%Y%m%d_%H%M%S")
-
-      # Ensure the session directory exists
-      session_dir = File.join(Dir.pwd, SWARM_DIR, SESSIONS_DIR, @session_timestamp)
-      FileUtils.mkdir_p(session_dir)
+      # Use session path from environment (required)
+      @session_path = SessionPath.from_env
+      SessionPath.ensure_directory(@session_path)
 
       # Create logger with session.log filename
       log_filename = "session.log"
-      log_path = File.join(session_dir, log_filename)
+      log_path = File.join(@session_path, log_filename)
       @logger = Logger.new(log_path)
       @logger.level = Logger::INFO
 
@@ -128,6 +122,8 @@ module ClaudeSwarm
     end
 
     def log_streaming_event(event)
+      append_to_session_json(event)
+
       return log_system_message(event) if event["type"] == "system"
 
       # Add specific details based on event type
@@ -170,6 +166,32 @@ module ClaudeSwarm
       @logger.debug("USER: #{JSON.pretty_generate(content)}")
     end
 
+    def append_to_session_json(event)
+      json_filename = "session.log.json"
+      json_path = File.join(@session_path, json_filename)
+
+      # Use file locking to ensure thread-safe writes
+      File.open(json_path, File::WRONLY | File::APPEND | File::CREAT) do |file|
+        file.flock(File::LOCK_EX)
+
+        # Create entry with metadata
+        entry = {
+          instance: @instance_name,
+          calling_instance: @calling_instance,
+          timestamp: Time.now.iso8601,
+          event: event
+        }
+
+        # Write as single line JSON (JSONL format)
+        file.puts(entry.to_json)
+
+        file.flock(File::LOCK_UN)
+      end
+    rescue StandardError => e
+      @logger.error("Failed to append to session JSON: #{e.message}")
+      raise
+    end
+
     def build_command_array(prompt, options)
       cmd_array = ["claude"]
 

data/lib/claude_swarm/claude_mcp_server.rb

@@ -11,7 +11,7 @@ module ClaudeSwarm
   class ClaudeMcpServer
     # Class variables to share state with tool classes
     class << self
-      attr_accessor :executor, :instance_config, :logger, :session_timestamp, :calling_instance
+      attr_accessor :executor, :instance_config, :logger, :session_path, :calling_instance
     end
 
     def initialize(instance_config, calling_instance:)
@@ -30,7 +30,7 @@ module ClaudeSwarm
       self.class.executor = @executor
       self.class.instance_config = @instance_config
       self.class.logger = @executor.logger
-      self.class.session_timestamp = @executor.session_timestamp
+      self.class.session_path = @executor.session_path
       self.class.calling_instance = @calling_instance
     end
 

data/lib/claude_swarm/cli.rb

@@ -22,6 +22,8 @@ module ClaudeSwarm
                            desc: "Prompt to pass to the main Claude instance (non-interactive mode)"
     method_option :stream_logs, type: :boolean, default: false,
                                 desc: "Stream session logs to stdout (only works with -p)"
+    method_option :debug, type: :boolean, default: false,
+                          desc: "Enable debug output"
     def start(config_file = nil)
       config_path = config_file || options[:config]
       unless File.exist?(config_path)
@@ -39,13 +41,12 @@ module ClaudeSwarm
 
       begin
         config = Configuration.new(config_path)
-        session_timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
-        generator = McpGenerator.new(config, vibe: options[:vibe], timestamp: session_timestamp)
+        generator = McpGenerator.new(config, vibe: options[:vibe])
         orchestrator = Orchestrator.new(config, generator,
                                         vibe: options[:vibe],
                                         prompt: options[:prompt],
-                                        session_timestamp: session_timestamp,
-                                        stream_logs: options[:stream_logs])
+                                        stream_logs: options[:stream_logs],
+                                        debug: options[:debug])
         orchestrator.start
       rescue Error => e
         error e.message

data/lib/claude_swarm/configuration.rb

@@ -68,6 +68,7 @@ module ClaudeSwarm
         @instances[name] = parse_instance(name, config)
       end
       validate_connections
+      detect_circular_dependencies
     end
 
     def parse_instance(name, config)
@@ -127,6 +128,31 @@ module ClaudeSwarm
       end
     end
 
+    def detect_circular_dependencies
+      @instances.each_key do |instance_name|
+        visited = Set.new
+        path = []
+        detect_cycle_from(instance_name, visited, path)
+      end
+    end
+
+    def detect_cycle_from(instance_name, visited, path)
+      return if visited.include?(instance_name)
+
+      if path.include?(instance_name)
+        cycle_start = path.index(instance_name)
+        cycle = path[cycle_start..] + [instance_name]
+        raise Error, "Circular dependency detected: #{cycle.join(" -> ")}"
+      end
+
+      path.push(instance_name)
+      @instances[instance_name][:connections].each do |connection|
+        detect_cycle_from(connection, visited, path)
+      end
+      path.pop
+      visited.add(instance_name)
+    end
+
     def validate_directories
       @instances.each do |name, instance|
         directory = instance[:directory]

data/lib/claude_swarm/mcp_generator.rb

@@ -3,16 +3,14 @@
 require "json"
 require "fileutils"
 require "shellwords"
+require_relative "session_path"
 
 module ClaudeSwarm
   class McpGenerator
-    SWARM_DIR = ".claude-swarm"
-    SESSIONS_SUBDIR = "sessions"
-
-    def initialize(configuration, vibe: false, timestamp: nil)
+    def initialize(configuration, vibe: false)
       @config = configuration
       @vibe = vibe
-      @timestamp = timestamp || Time.now.strftime("%Y%m%d_%H%M%S")
+      @session_path = nil # Will be set when needed
     end
 
     def generate_all
@@ -24,24 +22,19 @@ module ClaudeSwarm
     end
 
     def mcp_config_path(instance_name)
-      File.join(Dir.pwd, SWARM_DIR, SESSIONS_SUBDIR, @timestamp, "#{instance_name}.mcp.json")
+      File.join(session_path, "#{instance_name}.mcp.json")
     end
 
     private
 
-    def swarm_dir
-      File.join(Dir.pwd, SWARM_DIR)
+    def session_path
+      @session_path ||= SessionPath.from_env
     end
 
     def ensure_swarm_directory
-      FileUtils.mkdir_p(swarm_dir)
-
-      # Create session directory with timestamp
-      session_dir = File.join(swarm_dir, SESSIONS_SUBDIR, @timestamp)
-      FileUtils.mkdir_p(session_dir)
-
-      gitignore_path = File.join(swarm_dir, ".gitignore")
-      File.write(gitignore_path, "*\n") unless File.exist?(gitignore_path)
+      # Session directory is already created by orchestrator
+      # Just ensure it exists
+      SessionPath.ensure_directory(session_path)
     end
 
     def generate_mcp_config(name, instance)
@@ -134,10 +127,7 @@ module ClaudeSwarm
       {
         "type" => "stdio",
         "command" => exe_path,
-        "args" => args,
-        "env" => {
-          "CLAUDE_SWARM_SESSION_TIMESTAMP" => @timestamp
-        }
+        "args" => args
       }
     end
   end

data/lib/claude_swarm/orchestrator.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
 require "shellwords"
+require_relative "session_path"
 
 module ClaudeSwarm
   class Orchestrator
-    def initialize(configuration, mcp_generator, vibe: false, prompt: nil, session_timestamp: nil, stream_logs: false)
+    def initialize(configuration, mcp_generator, vibe: false, prompt: nil, stream_logs: false, debug: false)
       @config = configuration
       @generator = mcp_generator
       @vibe = vibe
       @prompt = prompt
-      @session_timestamp = session_timestamp || Time.now.strftime("%Y%m%d_%H%M%S")
       @stream_logs = stream_logs
+      @debug = debug
     end
 
     def start
@@ -20,10 +21,15 @@ module ClaudeSwarm
         puts
       end
 
-      # Set session timestamp for all instances to share the same session directory
-      ENV["CLAUDE_SWARM_SESSION_TIMESTAMP"] = @session_timestamp
+      # Generate and set session path for all instances
+      session_path = SessionPath.generate(working_dir: Dir.pwd)
+      SessionPath.ensure_directory(session_path)
+
+      ENV["CLAUDE_SWARM_SESSION_PATH"] = session_path
+      ENV["CLAUDE_SWARM_START_DIR"] = Dir.pwd
+
       unless @prompt
-        puts "📝 Session files will be saved to: .claude-swarm/sessions/#{@session_timestamp}/"
+        puts "📝 Session files will be saved to: #{session_path}/"
         puts
       end
 
@@ -48,7 +54,7 @@ module ClaudeSwarm
       end
 
       command = build_main_command(main_instance)
-      if ENV["DEBUG"] && !@prompt
+      if @debug && !@prompt
         puts "Running: #{command}"
         puts
       end
@@ -73,9 +79,7 @@ module ClaudeSwarm
 
     def start_log_streaming
       Thread.new do
-        session_log_path = File.join(Dir.pwd, ClaudeSwarm::ClaudeCodeExecutor::SWARM_DIR,
-                                     ClaudeSwarm::ClaudeCodeExecutor::SESSIONS_DIR,
-                                     @session_timestamp, "session.log")
+        session_log_path = File.join(ENV.fetch("CLAUDE_SWARM_SESSION_PATH", nil), "session.log")
 
         # Wait for log file to be created
         sleep 0.1 until File.exist?(session_log_path)
@@ -133,6 +137,8 @@ module ClaudeSwarm
         parts << instance[:prompt]
       end
 
+      parts << "--debug" if @debug
+
       mcp_config_path = @generator.mcp_config_path(@config.main_instance)
       parts << "--mcp-config"
       parts << mcp_config_path

data/lib/claude_swarm/permission_mcp_server.rb

@@ -5,13 +5,10 @@ require "fast_mcp"
 require "logger"
 require "fileutils"
 require_relative "permission_tool"
+require_relative "session_path"
 
 module ClaudeSwarm
   class PermissionMcpServer
-    # Directory constants
-    SWARM_DIR = ".claude-swarm"
-    SESSIONS_DIR = "sessions"
-
     # Server configuration
     SERVER_NAME = "claude-swarm-permissions"
     SERVER_VERSION = "1.0.0"
@@ -60,20 +57,14 @@ module ClaudeSwarm
     end
 
     def setup_logging
-      session_dir = create_session_directory
-      @logger = create_logger(session_dir)
+      session_path = SessionPath.from_env
+      SessionPath.ensure_directory(session_path)
+      @logger = create_logger(session_path)
       @logger.info("Permission MCP server logging initialized")
     end
 
-    def create_session_directory
-      session_timestamp = ENV["CLAUDE_SWARM_SESSION_TIMESTAMP"] || Time.now.strftime("%Y%m%d_%H%M%S")
-      session_dir = File.join(Dir.pwd, SWARM_DIR, SESSIONS_DIR, session_timestamp)
-      FileUtils.mkdir_p(session_dir)
-      session_dir
-    end
-
-    def create_logger(session_dir)
-      log_path = File.join(session_dir, "permissions.log")
+    def create_logger(session_path)
+      log_path = File.join(session_path, "permissions.log")
       logger = Logger.new(log_path)
       logger.level = Logger::DEBUG
       logger.formatter = log_formatter

data/lib/claude_swarm/session_path.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module ClaudeSwarm
+  module SessionPath
+    SESSIONS_DIR = "sessions"
+
+    class << self
+      def swarm_home
+        ENV["CLAUDE_SWARM_HOME"] || File.expand_path("~/.claude-swarm")
+      end
+
+      # 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 timestamp
+      def generate(working_dir: Dir.pwd, timestamp: Time.now.strftime("%Y%m%d_%H%M%S"))
+        project_name = project_folder_name(working_dir)
+        File.join(swarm_home, SESSIONS_DIR, project_name, timestamp)
+      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 = File.join(swarm_home, ".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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.12
 platform: ruby
 authors:
 - Paulo Arruda
@@ -58,6 +58,7 @@ files:
 - README.md
 - RELEASING.md
 - Rakefile
+- claude-swarm.yml
 - example/claude-swarm.yml
 - example/microservices-team.yml
 - example/test-generation.yml
@@ -73,6 +74,7 @@ files:
 - lib/claude_swarm/permission_tool.rb
 - lib/claude_swarm/reset_session_tool.rb
 - lib/claude_swarm/session_info_tool.rb
+- lib/claude_swarm/session_path.rb
 - lib/claude_swarm/task_tool.rb
 - lib/claude_swarm/version.rb
 - sdk-docs.md