claude_swarm 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37bc8baf6ea837fcd1e8936a1ae5a6a13138fad6e6efb3708deca991673e119d
-  data.tar.gz: 1e3d06c4138a42e7ab54a121c4bd3e584db3859e640a5965aac88d04fe0e6132
+  metadata.gz: a4597e6fdc67837e39ae1c175cc9dded454460ec00488d92aa81cab928737b4a
+  data.tar.gz: 46790b958dc4916a3df066ae7384e753c84c6c4cc624ac62754cab646f2c9102
 SHA512:
-  metadata.gz: dba5aab927293d3cc5fc4190b0cd84f7addf7ae0f90224df425a166d33c5feb5e062be21c8b915589191a14609f25f6fc68da63402c5295588bd5c4ed1d177ab
-  data.tar.gz: 6a7d5058d8583bd1bf6fec8d148fe62e617535528f49f960412eb6da065db01a0405f4de6cff8963c63c523ce81cbf661dc49fe8840df3d568eaa2fcba853284
+  metadata.gz: f876006a8368881b252e675fab2b2999ae5a79574caff9db081ea7ea72402ce172524d7c6a2fe9c4b967502971a1cab83895dfd1f339592a516c58298450426a
+  data.tar.gz: b55120d481b8605e11a7024f1d6626f5c1fecca18627b6247e4b517c16e29d762166408a1753b1fc1b845c80f820f9701ce30ef2b0edb7e8a58da1b3635d0cc4

data/CHANGELOG.md

@@ -1,4 +1,26 @@
-## [Unreleased]
+## [0.1.4]
+
+### Added
+- **Required `description` field for instances**: Each instance must now have a description that clearly explains its role and specialization
+- Dynamic task tool descriptions that include both the instance name and description (e.g., "Execute a task using Agent frontend_dev. Frontend developer specializing in React and modern web technologies")
+- Description validation during configuration parsing - configurations without descriptions will fail with a clear error message
+
+### Changed
+- Updated all documentation examples to include meaningful instance descriptions
+- The `claude-swarm init` command now generates a template with description fields
+
+## [0.1.3]
+
+### Fixed
+- Fixed duplicate prompt arguments being passed to Claude Code executor, which could cause command execution failures
+
+### Changed
+- Improved logging to track request flow between instances using `from_instance` and `to_instance` fields instead of generic `instance_name`
+- Added required `calling_instance` parameter to MCP server command to properly identify the source of requests in tree configurations
+- Consolidated session files into a single directory structure (`.claude-swarm/sessions/<timestamp>/`)
+- MCP configuration files are now stored alongside session logs in the same timestamped directory
+- Session logs are now named `session.log` instead of `session_<timestamp>.log`
+- Improved organization by keeping all session-related files together
 
 ## [0.1.2] - 2025-05-29
 

data/README.md

@@ -41,6 +41,7 @@ swarm:
   main: lead
   instances:
     lead:
+      description: "Team lead coordinating development efforts"
       directory: .
       model: opus
       connections: [frontend, backend]
@@ -49,6 +50,7 @@ swarm:
         - Edit
         - Bash
     frontend:
+      description: "Frontend specialist handling UI and user experience"
       directory: ./frontend
       model: sonnet
       tools:
@@ -56,6 +58,7 @@ swarm:
         - Write
         - Bash
     backend:
+      description: "Backend developer managing APIs and data layer"
       directory: ./backend  
       model: sonnet
       tools:
@@ -77,7 +80,7 @@ claude-swarm --vibe # That will allow ALL tools for all instances! Be Careful!
 This will:
 - Launch the main instance (lead) with connections to other instances
 - The lead instance can communicate with the other instances via MCP
-- All instances log to `.claude-swarm/logs/session-{timestamp}/`
+- All session files are stored in `.claude-swarm/sessions/{timestamp}/`
 
 #### Multi-Level Swarm Example
 
@@ -90,6 +93,7 @@ swarm:
   main: architect
   instances:
     architect:
+      description: "System architect coordinating between service teams"
       directory: .
       model: opus
       connections: [frontend_lead, backend_lead, mobile_lead, devops]
@@ -97,6 +101,7 @@ swarm:
       tools: [Read, Edit, WebSearch]
     
     frontend_lead:
+      description: "Frontend team lead overseeing React development"
       directory: ./web-frontend
       model: opus
       connections: [react_dev, css_expert]
@@ -104,18 +109,21 @@ swarm:
       tools: [Read, Edit, Bash]
     
     react_dev:
+      description: "React developer specializing in components and state management"
       directory: ./web-frontend/src
       model: sonnet
       prompt: "You specialize in React components and state management"
       tools: [Edit, Write, "Bash(npm:*)"]
     
     css_expert:
+      description: "CSS specialist handling styling and responsive design"
       directory: ./web-frontend/styles
       model: sonnet
       prompt: "You handle all CSS and styling concerns"
       tools: [Edit, Write, Read]
     
     backend_lead:
+      description: "Backend team lead managing API development"
       directory: ./api-server
       model: opus
       connections: [api_dev, database_expert]
@@ -123,18 +131,21 @@ swarm:
       tools: [Read, Edit, Bash]
     
     api_dev:
+      description: "API developer building REST endpoints"
       directory: ./api-server/src
       model: sonnet
       prompt: "You develop REST API endpoints"
       tools: [Edit, Write, Bash]
     
     database_expert:
+      description: "Database specialist managing schemas and migrations"
       directory: ./api-server/db
       model: sonnet
       prompt: "You handle database schema and migrations"
       tools: [Edit, Write, "Bash(psql:*, migrate:*)"]
     
     mobile_lead:
+      description: "Mobile team lead coordinating cross-platform development"
       directory: ./mobile-app
       model: sonnet
       connections: [ios_dev, android_dev]
@@ -142,18 +153,21 @@ swarm:
       tools: [Read, Edit]
     
     ios_dev:
+      description: "iOS developer building native Apple applications"
       directory: ./mobile-app/ios
       model: sonnet
       prompt: "You develop the iOS application"
       tools: [Edit, Write, "Bash(xcodebuild:*, pod:*)"]
     
     android_dev:
+      description: "Android developer creating native Android apps"
       directory: ./mobile-app/android
       model: sonnet
       prompt: "You develop the Android application"
       tools: [Edit, Write, "Bash(gradle:*, adb:*)"]
     
     devops:
+      description: "DevOps engineer managing CI/CD and infrastructure"
       directory: ./infrastructure
       model: sonnet
       prompt: "You handle CI/CD and infrastructure"
@@ -182,6 +196,10 @@ swarm:
 
 #### Instance Configuration
 
+Each instance must have:
+
+- **description** (required): Brief description of the agent's role (used in task tool descriptions)
+
 Each instance can have:
 
 - **directory**: Working directory for this instance (can use ~ for home)
@@ -193,6 +211,7 @@ Each instance can have:
 
 ```yaml
 instance_name:
+  description: "Specialized agent focused on specific tasks"
   directory: ~/project/path
   model: opus
   connections: [other_instance1, other_instance2]
@@ -273,6 +292,7 @@ swarm:
   main: architect
   instances:
     architect:
+      description: "Lead architect responsible for system design and code quality"
       directory: .
       model: opus
       connections: [frontend, backend, devops]
@@ -283,6 +303,7 @@ swarm:
         - WebSearch
         
     frontend:
+      description: "Frontend developer specializing in React and TypeScript"
       directory: ./frontend
       model: sonnet
       connections: [architect]
@@ -293,6 +314,7 @@ swarm:
         - Bash
         
     backend:
+      description: "Backend developer building APIs and services"
       directory: ./backend
       model: sonnet
       connections: [architect, database]
@@ -302,6 +324,7 @@ swarm:
         - Bash
         
     database:
+      description: "Database administrator managing data persistence"
       directory: ./db
       model: haiku
       tools:
@@ -309,6 +332,7 @@ swarm:
         - Bash
         
     devops:
+      description: "DevOps engineer handling deployment and infrastructure"
       directory: .
       model: sonnet
       connections: [architect]
@@ -327,6 +351,7 @@ swarm:
   main: lead_researcher
   instances:
     lead_researcher:
+      description: "Lead researcher coordinating analysis and documentation"
       directory: ~/research
       model: opus
       connections: [data_analyst, writer]
@@ -340,6 +365,7 @@ swarm:
           url: "https://arxiv-mcp.example.com"
           
     data_analyst:
+      description: "Data analyst processing research data and statistics"
       directory: ~/research/data
       model: sonnet
       tools:
@@ -353,6 +379,7 @@ swarm:
           args: ["--notebook-dir", "."]
           
     writer:
+      description: "Technical writer preparing research documentation"
       directory: ~/research/papers
       model: sonnet
       tools:
@@ -397,10 +424,12 @@ claude-swarm mcp-serve INSTANCE_NAME --config CONFIG_FILE --session-timestamp TI
    - Sessions can be reset via the MCP server interface
 4. **Main Instance Launch**: The main instance is launched with its MCP configuration, giving it access to all connected instances
 5. **Inter-Instance Communication**: Connected instances expose themselves as MCP servers with these tools:
-   - **task**: Execute tasks using Claude Code with configurable tools and return results
+   - **task**: Execute tasks using Claude Code with configurable tools and return results. The tool description includes the instance name and description (e.g., "Execute a task using Agent frontend_dev. Frontend developer specializing in React and TypeScript")
    - **session_info**: Get current Claude session information including ID and working directory
    - **reset_session**: Reset the Claude session for a fresh start
-6. **Centralized Logging**: All instances log to `.claude-swarm/logs/session-{timestamp}/` with detailed request/response tracking
+6. **Session Management**: All session files are organized in `.claude-swarm/sessions/{timestamp}/`:
+   - MCP configuration files: `{instance_name}.mcp.json`
+   - Session log: `session.log` with detailed request/response tracking
 
 ## Troubleshooting
 
@@ -423,16 +452,16 @@ claude-swarm mcp-serve INSTANCE_NAME --config CONFIG_FILE --session-timestamp TI
 ### Debug Output
 
 The swarm will display:
-- Generated MCP configuration location
+- Session directory location (`.claude-swarm/sessions/{timestamp}/`)
 - Main instance details (model, directory, tools, connections)
 - The exact command being run
 
-### Logs
+### Session Files
 
-Check the centralized logs in `.claude-swarm/logs/session-{timestamp}/` for:
-- Individual instance logs
-- MCP server communication
-- Error messages and debugging information
+Check the session directory `.claude-swarm/sessions/{timestamp}/` for:
+- `session.log`: Detailed logs with request/response tracking
+- `{instance}.mcp.json`: MCP configuration for each instance
+- All files for a session are kept together for easy review
 
 ## Architecture
 

data/claude-swarm.yml

@@ -4,6 +4,7 @@ swarm:
   main: lead_developer
   instances:
     lead_developer:
+      description: "Lead developer coordinating the team and making architectural decisions"
       directory: .
       model: sonnet
       prompt: "You are the lead developer coordinating the team"
@@ -13,6 +14,7 @@ swarm:
     # 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"

data/example/claude-swarm.yml

@@ -4,14 +4,14 @@ swarm:
   main: lead_rails_dev
   instances:
     lead_rails_dev:
-      role: "Lead Rails Developer"
+      description: "Senior Rails developer with 10+ years experience, coordinating the team and making architectural decisions"
       directory: .
       model: opus
       connections: [backend_dev, frontend_dev, test_engineer]
       prompt: "You are a senior Ruby on Rails developer with 10+ years of experience. You excel at Rails architecture, performance optimization, and best practices. You coordinate the team and make architectural decisions."
       
     backend_dev:
-      role: "Backend Rails Developer"
+      description: "Backend specialist focusing on Rails models, controllers, services, jobs, and API design"
       directory: .
       model: sonnet
       connections: [test_engineer]
@@ -23,14 +23,14 @@ swarm:
           args: ["exec", "hbt", "stdio"]
     
     frontend_dev:
-      role: "Rails Frontend Developer"
+      description: "Frontend Rails developer specializing in views, Stimulus/Turbo, and responsive UIs"
       directory: .
       model: sonnet
       connections: [test_engineer]
       prompt: "You are a Rails developer specializing in views, partials, helpers, Stimulus/Turbo, and asset pipeline. You excel at creating responsive UIs with Rails' built-in tools and modern CSS/JavaScript integration."
           
     test_engineer:
-      role: "Rails Test Engineer"
+      description: "Testing expert specializing in Minitest and Rails testing best practices"
       directory: .
       model: sonnet
       prompt: "You are a Rails testing expert specializing in Minitest. You write comprehensive unit tests, integration tests, system tests, and fixtures. You ensure high test coverage and follow Rails testing best practices including proper use of assertions, test helpers, and factories."

data/lib/claude_swarm/claude_code_executor.rb

@@ -67,8 +67,8 @@ module ClaudeSwarm
       # Always use JSON output format for structured responses
       cmd_array += ["--output-format", "json"]
 
-      # Add non-interactive mode
-      cmd_array << "--print"
+      # Add non-interactive mode with prompt
+      cmd_array += ["--print", "-p", prompt]
 
       # Add any custom system prompt
       cmd_array += ["--system-prompt", options[:system_prompt]] if options[:system_prompt]
@@ -81,9 +81,6 @@ module ClaudeSwarm
         cmd_array += ["--allowedTools", tools]
       end
 
-      # Add the prompt as the last argument (no escaping needed with array syntax)
-      cmd_array << prompt
-
       cmd_array
     end
 

data/lib/claude_swarm/claude_mcp_server.rb

@@ -9,15 +9,16 @@ require_relative "claude_code_executor"
 module ClaudeSwarm
   class ClaudeMcpServer
     SWARM_DIR = ".claude-swarm"
-    LOGS_DIR = "logs"
+    SESSIONS_DIR = "sessions"
 
     # Class variables to share state with tool classes
     class << self
-      attr_accessor :executor, :instance_config, :logger, :session_timestamp
+      attr_accessor :executor, :instance_config, :logger, :session_timestamp, :calling_instance
     end
 
-    def initialize(instance_config)
+    def initialize(instance_config, calling_instance:)
       @instance_config = instance_config
+      @calling_instance = calling_instance
       @executor = ClaudeCodeExecutor.new(
         working_directory: instance_config[:directory],
         model: instance_config[:model],
@@ -32,6 +33,7 @@ module ClaudeSwarm
       self.class.executor = @executor
       self.class.instance_config = @instance_config
       self.class.logger = @logger
+      self.class.calling_instance = @calling_instance
     end
 
     private
@@ -41,13 +43,13 @@ module ClaudeSwarm
       # Otherwise create a new timestamp
       self.class.session_timestamp ||= ENV["CLAUDE_SWARM_SESSION_TIMESTAMP"] || Time.now.strftime("%Y%m%d_%H%M%S")
 
-      # Ensure the logs directory exists
-      logs_dir = File.join(Dir.pwd, SWARM_DIR, LOGS_DIR)
-      FileUtils.mkdir_p(logs_dir)
+      # Ensure the session directory exists
+      session_dir = File.join(Dir.pwd, SWARM_DIR, SESSIONS_DIR, self.class.session_timestamp)
+      FileUtils.mkdir_p(session_dir)
 
-      # Create logger with timestamped filename
-      log_filename = "session_#{self.class.session_timestamp}.log"
-      log_path = File.join(logs_dir, log_filename)
+      # Create logger with session.log filename
+      log_filename = "session.log"
+      log_path = File.join(session_dir, log_filename)
       @logger = Logger.new(log_path)
       @logger.level = Logger::INFO
 
@@ -67,6 +69,13 @@ module ClaudeSwarm
         version: "1.0.0"
       )
 
+      # Set dynamic description for TaskTool based on instance config
+      if @instance_config[:description]
+        TaskTool.description "Execute a task using Agent #{@instance_config[:name]}. #{@instance_config[:description]}"
+      else
+        TaskTool.description "Execute a task using Agent #{@instance_config[:name]}"
+      end
+
       # Register tool classes (not instances)
       server.register_tool(TaskTool)
       server.register_tool(SessionInfoTool)
@@ -81,7 +90,7 @@ module ClaudeSwarm
       description "Execute a task using Claude Code"
 
       arguments do
-        required(:prompt).filled(:string).description("The task or question for Claude")
+        required(:prompt).filled(:string).description("The task or question for the agent")
         optional(:new_session).filled(:bool).description("Start a new session (default: false)")
         optional(:system_prompt).filled(:string).description("Override the system prompt for this request")
       end
@@ -103,7 +112,8 @@ module ClaudeSwarm
           # Log the request
           log_entry = {
             timestamp: Time.now.utc.iso8601,
-            instance_name: instance_config[:name],
+            from_instance: ClaudeMcpServer.calling_instance, # The instance making the request
+            to_instance: instance_config[:name], # This instance is receiving the request
             model: instance_config[:model],
             working_directory: instance_config[:directory],
             session_id: executor.session_id,
@@ -120,7 +130,10 @@ module ClaudeSwarm
           response = executor.execute(prompt, options)
 
           # Log the response
-          response_entry = log_entry.merge(
+          response_entry = {
+            timestamp: Time.now.utc.iso8601,
+            from_instance: instance_config[:name], # This instance is sending the response
+            to_instance: ClaudeMcpServer.calling_instance, # The instance that made the request receives the response
             session_id: executor.session_id, # Update with new session ID if changed
             response: {
               result: response["result"],
@@ -129,7 +142,7 @@ module ClaudeSwarm
               is_error: response["is_error"],
               total_cost: response["total_cost"]
             }
-          )
+          }
 
           logger.info("RESPONSE: #{JSON.pretty_generate(response_entry)}")
 
@@ -151,7 +164,7 @@ module ClaudeSwarm
 
     class SessionInfoTool < FastMcp::Tool
       tool_name "session_info"
-      description "Get information about the current Claude session"
+      description "Get information about the current Claude session for this agent"
 
       arguments do
         # No arguments needed
@@ -170,7 +183,7 @@ module ClaudeSwarm
 
     class ResetSessionTool < FastMcp::Tool
       tool_name "reset_session"
-      description "Reset the Claude session, starting fresh on the next task"
+      description "Reset the Claude session for this agent, starting fresh on the next task"
 
       arguments do
         # No arguments needed

data/lib/claude_swarm/cli.rb

@@ -29,8 +29,12 @@ module ClaudeSwarm
       say "Starting Claude Swarm from #{config_path}..." unless options[:prompt]
       begin
         config = Configuration.new(config_path)
-        generator = McpGenerator.new(config, vibe: options[:vibe])
-        orchestrator = Orchestrator.new(config, generator, vibe: options[:vibe], prompt: options[:prompt])
+        session_timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
+        generator = McpGenerator.new(config, vibe: options[:vibe], timestamp: session_timestamp)
+        orchestrator = Orchestrator.new(config, generator,
+                                        vibe: options[:vibe],
+                                        prompt: options[:prompt],
+                                        session_timestamp: session_timestamp)
         orchestrator.start
       rescue Error => e
         error e.message
@@ -51,6 +55,8 @@ module ClaudeSwarm
                           desc: "Claude model to use (e.g., opus, sonnet)"
     method_option :prompt, aliases: "-p", type: :string,
                            desc: "System prompt for the instance"
+    method_option :description, type: :string,
+                                desc: "Description of the instance's role"
     method_option :tools, aliases: "-t", type: :array,
                           desc: "Allowed tools for the instance"
     method_option :mcp_config_path, type: :string,
@@ -59,19 +65,22 @@ module ClaudeSwarm
                           desc: "Enable debug output"
     method_option :vibe, type: :boolean, default: false,
                          desc: "Run with --dangerously-skip-permissions"
+    method_option :calling_instance, type: :string, required: true,
+                                     desc: "Name of the instance that launched this MCP server"
     def mcp_serve
       instance_config = {
         name: options[:name],
         directory: options[:directory],
         model: options[:model],
         prompt: options[:prompt],
+        description: options[:description],
         tools: options[:tools] || [],
         mcp_config_path: options[:mcp_config_path],
         vibe: options[:vibe]
       }
 
       begin
-        server = ClaudeMcpServer.new(instance_config)
+        server = ClaudeMcpServer.new(instance_config, calling_instance: options[:calling_instance])
         server.start
       rescue StandardError => e
         error "Error starting MCP server: #{e.message}"
@@ -99,6 +108,7 @@ module ClaudeSwarm
           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"
@@ -108,24 +118,28 @@ module ClaudeSwarm
             # Example instances (uncomment and modify as needed):
 
             # frontend_dev:
+            #   description: "Frontend developer specializing in React and modern web technologies"
             #   directory: ./frontend
             #   model: sonnet
             #   prompt: "You specialize in frontend development with React, TypeScript, and modern web technologies"
             #   tools: [Read, Edit, Write, "Bash(npm:*)", "Bash(yarn:*)", "Bash(pnpm:*)"]
 
             # backend_dev:
+            #   description: "Backend developer focusing on APIs, databases, and server architecture"
             #   directory: ../other-app/backend
             #   model: sonnet
             #   prompt: "You specialize in backend development, APIs, databases, and server architecture"
             #   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"
             #   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"

data/lib/claude_swarm/configuration.rb

@@ -72,6 +72,10 @@ module ClaudeSwarm
 
     def parse_instance(name, config)
       config ||= {}
+
+      # Validate required fields
+      raise Error, "Instance '#{name}' missing required 'description' field" unless config["description"]
+
       {
         name: name,
         directory: expand_path(config["directory"] || "."),
@@ -79,7 +83,8 @@ module ClaudeSwarm
         connections: Array(config["connections"]),
         tools: Array(config["tools"]),
         mcps: parse_mcps(config["mcps"] || []),
-        prompt: config["prompt"]
+        prompt: config["prompt"],
+        description: config["description"]
       }
     end
 

data/lib/claude_swarm/mcp_generator.rb

@@ -7,10 +7,12 @@ require "shellwords"
 module ClaudeSwarm
   class McpGenerator
     SWARM_DIR = ".claude-swarm"
+    SESSIONS_SUBDIR = "sessions"
 
-    def initialize(configuration, vibe: false)
+    def initialize(configuration, vibe: false, timestamp: nil)
       @config = configuration
       @vibe = vibe
+      @timestamp = timestamp || Time.now.strftime("%Y%m%d_%H%M%S")
     end
 
     def generate_all
@@ -22,7 +24,7 @@ module ClaudeSwarm
     end
 
     def mcp_config_path(instance_name)
-      File.join(Dir.pwd, SWARM_DIR, "#{instance_name}.mcp.json")
+      File.join(Dir.pwd, SWARM_DIR, SESSIONS_SUBDIR, @timestamp, "#{instance_name}.mcp.json")
     end
 
     private
@@ -34,9 +36,9 @@ module ClaudeSwarm
     def ensure_swarm_directory
       FileUtils.mkdir_p(swarm_dir)
 
-      # Create logs directory as well
-      logs_dir = File.join(swarm_dir, "logs")
-      FileUtils.mkdir_p(logs_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)
@@ -53,7 +55,7 @@ module ClaudeSwarm
       # Add connection MCPs for other instances
       instance[:connections].each do |connection_name|
         connected_instance = @config.instances[connection_name]
-        mcp_servers[connection_name] = build_instance_mcp_config(connection_name, connected_instance)
+        mcp_servers[connection_name] = build_instance_mcp_config(connection_name, connected_instance, calling_instance: name)
       end
 
       config = {
@@ -81,7 +83,7 @@ module ClaudeSwarm
       end
     end
 
-    def build_instance_mcp_config(name, instance)
+    def build_instance_mcp_config(name, instance, calling_instance:)
       # Get the path to the claude-swarm executable
       exe_path = "claude-swarm"
 
@@ -96,10 +98,14 @@ module ClaudeSwarm
       # Add optional arguments
       args.push("--prompt", instance[:prompt]) if instance[:prompt]
 
+      args.push("--description", instance[:description]) if instance[:description]
+
       args.push("--tools", instance[:tools].join(",")) if instance[:tools] && !instance[:tools].empty?
 
       args.push("--mcp-config-path", mcp_config_path(name))
 
+      args.push("--calling-instance", calling_instance) if calling_instance
+
       args.push("--vibe") if @vibe
 
       {

data/lib/claude_swarm/orchestrator.rb

@@ -4,11 +4,12 @@ require "shellwords"
 
 module ClaudeSwarm
   class Orchestrator
-    def initialize(configuration, mcp_generator, vibe: false, prompt: nil)
+    def initialize(configuration, mcp_generator, vibe: false, prompt: nil, session_timestamp: nil)
       @config = configuration
       @generator = mcp_generator
       @vibe = vibe
       @prompt = prompt
+      @session_timestamp = session_timestamp || Time.now.strftime("%Y%m%d_%H%M%S")
     end
 
     def start
@@ -18,18 +19,17 @@ module ClaudeSwarm
         puts
       end
 
-      # Set session timestamp for all instances to share the same log file
-      session_timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
-      ENV["CLAUDE_SWARM_SESSION_TIMESTAMP"] = session_timestamp
+      # Set session timestamp for all instances to share the same session directory
+      ENV["CLAUDE_SWARM_SESSION_TIMESTAMP"] = @session_timestamp
       unless @prompt
-        puts "📝 Session logs will be saved to: .claude-swarm/logs/session_#{session_timestamp}.log"
+        puts "📝 Session files will be saved to: .claude-swarm/sessions/#{@session_timestamp}/"
         puts
       end
 
       # Generate all MCP configuration files
       @generator.generate_all
       unless @prompt
-        puts "✓ Generated MCP configurations in .claude-swarm/"
+        puts "✓ Generated MCP configurations in session directory"
         puts
       end
 

data/lib/claude_swarm/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Paulo Arruda
 bindir: exe
 cert_chain: []
-date: 2025-05-29 00:00:00.000000000 Z
+date: 2025-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor