claude_swarm 0.1.16 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b71b3ce3aebae7de091dd130cda9fc4c474f538f444be15f1ee5b07501210db6
-  data.tar.gz: 846ac3f979b5912ccbc70f1810b760f625e75b1c7e905d5d1199b893d0bc3400
+  metadata.gz: 3f0ab99665f31bddf2d3641525481ce2df55e910950af03290137246847bf70d
+  data.tar.gz: 2435170f5b61604c3131b1680f60ed8727795c58432806d9b61007813d4f5ce3
 SHA512:
-  metadata.gz: 9f891010506baba80420357aad85a7fde6704c2ed99155e9cf32fd38cc35efd007ac19fe0e8a1df59b5f1df2d24980f7f0150551629667b42254d02bf77c4ddc
-  data.tar.gz: 29f913521f66298ee24dbdff1b8a043d3a00abe0723080b953cb3dbc127ac6e5ecb35a8b857f61af062db9d570f3c42a90e874dcb114b42f6bee163162f96a0a
+  metadata.gz: ee74c188f6cc7fd31bb8705661f0913674bb687fd1eae6c2973728d2418f62bbad86054a89bd150965f39ec0bbd37ac04b2413dd22340311afd03cd5ec9d5424
+  data.tar.gz: a6c5fb7db4a8659619c9c7b5de000303ce91b046b85d635381f437adc92b4fd739e8d2142f0e65323346d1ba4d2607bf2b90c7d76fcf7c119bf6b9d5c431a7fc

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [0.1.17]
+
+### Added
+- **Multi-directory support**: Instances can now access multiple directories
+  - The `directory` field in YAML configuration now accepts either a string (single directory) or an array of strings (multiple directories)
+  - Additional directories are passed to Claude using the `--add-dir` flag
+  - The first directory in the array serves as the primary working directory
+  - All specified directories must exist or validation will fail
+  - Example: `directory: [./frontend, ./backend, ./shared]`
+- **Session monitoring commands**: New commands for monitoring and managing active Claude Swarm sessions
+  - `claude-swarm ps`: List all active sessions with properly aligned columns showing session ID, swarm name, total cost, uptime, and directories
+  - `claude-swarm show SESSION_ID`: Display detailed session information including instance hierarchy and individual costs
+  - `claude-swarm watch SESSION_ID`: Tail session logs in real-time (uses native `tail -f`)
+  - `claude-swarm clean`: Remove stale session symlinks with optional age filtering (`--days N`)
+  - Active sessions are tracked via symlinks in `~/.claude-swarm/run/` for efficient monitoring
+  - Cost tracking aggregates data from `session.log.json` for accurate reporting
+  - Interactive main instance shows "n/a (interactive)" for cost when not available
+
 ## [0.1.16]
 
 ### Changed

data/README.md

@@ -203,8 +203,8 @@ Each instance must have:
 
 Each instance can have:
 
-- **directory**: Working directory for this instance (can use ~ for home)
-- **model**: Claude model to use (opus, sonnet, haiku)
+- **directory**: Working directory for this instance (can use ~ for home). Can be a string for a single directory or an array of strings for multiple directories
+- **model**: Claude model to use (opus, sonnet)
 - **connections**: Array of other instances this one can communicate with
 - **allowed_tools**: Array of tools this instance can use (backward compatible with `tools`)
 - **disallowed_tools**: Array of tools to explicitly deny (takes precedence over allowed_tools)
@@ -336,7 +336,7 @@ swarm:
     database:
       description: "Database administrator managing data persistence"
       directory: ./db
-      model: haiku
+      model: sonnet
       allowed_tools:
         - Read
         - Bash
@@ -398,6 +398,36 @@ swarm:
         - Read
 ```
 
+#### Multi-Directory Support
+
+Instances can have access to multiple directories using an array (uses `claude --add-dir`):
+
+```yaml
+version: 1
+swarm:
+  name: "Multi-Module Project"
+  main: fullstack_dev
+  instances:
+    fullstack_dev:
+      description: "Full-stack developer working across multiple modules"
+      directory: [./frontend, ./backend, ./shared]  # Access to multiple directories
+      model: opus
+      allowed_tools: [Read, Edit, Write, Bash]
+      prompt: "You work across frontend, backend, and shared code modules"
+      
+    documentation_writer:
+      description: "Documentation specialist with access to code and docs"
+      directory: ["./docs", "./src", "./examples"]  # Multiple directories as array
+      model: sonnet
+      allowed_tools: [Read, Write, Edit]
+      prompt: "You maintain documentation based on code and examples"
+```
+
+When using multiple directories:
+- The first directory in the array is the primary working directory
+- Additional directories are accessible via the `--add-dir` flag in Claude
+- All directories must exist or the configuration will fail validation
+
 #### Mixed Permission Modes
 
 You can have different permission modes for different instances:
@@ -450,10 +480,6 @@ claude-swarm --prompt "Fix the bug in the payment module"
 claude-swarm --session-id 20241206_143022
 claude-swarm --session-id ~/path/to/session
 
-# List available sessions
-claude-swarm list-sessions
-claude-swarm list-sessions --limit 20
-
 # Show version
 claude-swarm version
 
@@ -464,6 +490,67 @@ claude-swarm version
 claude-swarm mcp-serve INSTANCE_NAME --config CONFIG_FILE --session-timestamp TIMESTAMP
 ```
 
+### Session Monitoring
+
+Claude Swarm provides commands to monitor and inspect running sessions:
+
+```bash
+# List running swarm sessions with costs and uptime
+claude-swarm ps
+
+# Show detailed information about a session including instance hierarchy
+claude-swarm show 20250617_235233
+
+# Watch live logs from a session
+claude-swarm watch 20250617_235233
+
+# Watch logs starting from the last 50 lines
+claude-swarm watch 20250617_235233 -n 50
+
+# List all available sessions (including completed ones)
+claude-swarm list-sessions
+claude-swarm list-sessions --limit 20
+
+# Clean up stale session symlinks
+claude-swarm clean
+
+# Remove sessions older than 30 days
+claude-swarm clean --days 30
+```
+
+Example output from `claude-swarm ps`:
+```
+⚠️  Total cost does not include the cost of the main instance
+
+SESSION_ID       SWARM_NAME                 TOTAL_COST    UPTIME      DIRECTORY
+-------------------------------------------------------------------------------
+20250617_235233  Feature Development        $0.3847       15m         .
+20250617_143022  Bug Investigation          $1.2156       1h          ./shopify
+20250617_091547  Multi-Module Dev           $0.8932       30m         ./frontend, ./backend, ./shared
+```
+
+Note: The total cost shown reflects only the costs of connected instances called via MCP. The main instance cost is not tracked when running interactively.
+
+Example output from `claude-swarm show`:
+```
+Session: 20250617_235233
+Swarm: Feature Development
+Total Cost: $0.3847 (excluding main instance)
+Start Directory: /Users/paulo/project
+
+Instance Hierarchy:
+--------------------------------------------------
+├─ orchestrator [main] (orchestrator_e85036fc)
+   Cost: n/a (interactive) | Calls: 0
+   └─ test_archaeologist (test_archaeologist_c504ca5f)
+      Cost: $0.1925 | Calls: 1
+   └─ pr_analyst (pr_analyst_bfbefe56)
+      Cost: $0.1922 | Calls: 1
+
+Note: Main instance (orchestrator) cost is not tracked in interactive mode.
+      View costs directly in the Claude interface.
+```
+
 ### Session Management and Restoration (Experimental)
 
 Claude Swarm provides experimental session management with restoration capabilities. **Note: This feature is experimental and has limitations - the main instance's conversation context is not fully restored.**
@@ -502,10 +589,10 @@ Resume a previous session with all instances restored to their Claude session st
 
 ```bash
 # Resume by session ID
-claude-swarm --session-id 20241206_143022
+claude-swarm --session-id 20250617_143022
 
 # Resume by full path
-claude-swarm --session-id ~/.claude-swarm/sessions/my-project/20241206_143022
+claude-swarm --session-id ~/.claude-swarm/sessions/my-project/20250617_143022
 ```
 
 This will:

data/claude-swarm.yml

@@ -1,42 +1,26 @@
 version: 1
 swarm:
   name: "Swarm Name"
-  main: lead_developer
+  main: claude_swarm_architect
   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]
+    claude_swarm_architect:
+      description: "Lead architect"
+      directory:
+        - .
+        - /Users/paulo/src/github.com/shopify-playground/claudeception
+      model: opus
+      prompt: "You are an expert in Claude swarm architecture"
+      vibe: true
+      connections: [claudeception_architect]
 
     # 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]
+    claudeception_architect:
+      description: "You are an expert in Claudeception architecture"
+      directory:
+        - .
+        - /Users/paulo/src/github.com/shopify-playground/claudeception
+      model: opus
+      prompt: "You are an expert in Claudeception architecture"
+      vibe: true
 
-    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]
-
-    # 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/examples/monitoring-demo.yml

@@ -0,0 +1,26 @@
+version: 1
+swarm:
+  name: "Monitoring Demo"
+  main: coordinator
+  instances:
+    coordinator:
+      description: "Main coordinator managing the team"
+      directory: .
+      model: haiku
+      connections: [analyzer, reporter]
+      prompt: "You coordinate analysis and reporting tasks"
+      allowed_tools: [Read, Edit]
+    
+    analyzer:
+      description: "Data analyzer processing information"
+      directory: ./data
+      model: haiku  
+      prompt: "You analyze data and provide insights"
+      allowed_tools: [Read, Bash]
+    
+    reporter:
+      description: "Report generator creating summaries"
+      directory: ./reports
+      model: haiku
+      prompt: "You generate reports from analysis"
+      allowed_tools: [Write, Edit]

data/examples/multi-directory.yml

@@ -0,0 +1,26 @@
+version: 1
+swarm:
+  name: "Multi-Directory Example"
+  main: fullstack_dev
+  instances:
+    fullstack_dev:
+      description: "Full-stack developer with access to multiple project directories"
+      directory: [./frontend, ./backend, ./shared, ./docs]
+      model: opus
+      connections: [frontend_specialist, backend_specialist]
+      allowed_tools: [Read, Edit, Write, Bash, WebSearch]
+      prompt: "You are a full-stack developer with access to frontend, backend, shared code, and documentation directories"
+      
+    frontend_specialist:
+      description: "Frontend developer focused on React components"
+      directory: ./frontend
+      model: sonnet
+      allowed_tools: [Read, Edit, Write, Bash]
+      prompt: "You specialize in React and frontend development"
+      
+    backend_specialist:
+      description: "Backend developer focused on API development"
+      directory: ./backend
+      model: sonnet
+      allowed_tools: [Read, Edit, Write, Bash]
+      prompt: "You specialize in backend API development"

data/lib/claude_swarm/claude_code_executor.rb

@@ -12,8 +12,9 @@ module ClaudeSwarm
 
     def initialize(working_directory: Dir.pwd, model: nil, mcp_config: nil, vibe: false,
                    instance_name: nil, instance_id: nil, calling_instance: nil, calling_instance_id: nil,
-                   claude_session_id: nil)
+                   claude_session_id: nil, additional_directories: [])
       @working_directory = working_directory
+      @additional_directories = additional_directories
       @model = model
       @mcp_config = mcp_config
       @vibe = vibe
@@ -259,6 +260,12 @@ module ClaudeSwarm
 
       cmd_array << "--verbose"
 
+      # Add additional directories with --add-dir
+      cmd_array << "--add-dir" if @additional_directories.any?
+      @additional_directories.each do |additional_dir|
+        cmd_array << additional_dir
+      end
+
       # Add MCP config if specified
       cmd_array += ["--mcp-config", @mcp_config] if @mcp_config
 

data/lib/claude_swarm/claude_mcp_server.rb

@@ -28,7 +28,8 @@ module ClaudeSwarm
         instance_id: instance_config[:instance_id],
         calling_instance: calling_instance,
         calling_instance_id: calling_instance_id,
-        claude_session_id: instance_config[:claude_session_id]
+        claude_session_id: instance_config[:claude_session_id],
+        additional_directories: instance_config[:directories][1..] || []
       )
 
       # Set class variables so tools can access them

data/lib/claude_swarm/cli.rb

@@ -71,6 +71,8 @@ module ClaudeSwarm
                          desc: "Instance name"
     method_option :directory, aliases: "-d", type: :string, required: true,
                               desc: "Working directory for the instance"
+    method_option :directories, type: :array,
+                                desc: "All directories (including main directory) for the instance"
     method_option :model, aliases: "-m", type: :string, required: true,
                           desc: "Claude model to use (e.g., opus, sonnet)"
     method_option :prompt, aliases: "-p", type: :string,
@@ -101,6 +103,7 @@ module ClaudeSwarm
       instance_config = {
         name: options[:name],
         directory: options[:directory],
+        directories: options[:directories] || [options[:directory]],
         model: options[:model],
         prompt: options[:prompt],
         description: options[:description],
@@ -108,7 +111,7 @@ module ClaudeSwarm
         disallowed_tools: options[:disallowed_tools] || [],
         connections: options[:connections] || [],
         mcp_config_path: options[:mcp_config_path],
-        vibe: options[:vibe],
+        vibe: options[:vibe] || false,
         instance_id: options[:instance_id],
         claude_session_id: options[:claude_session_id]
       }
@@ -194,6 +197,82 @@ module ClaudeSwarm
       say "Claude Swarm #{VERSION}"
     end
 
+    desc "ps", "List running Claude Swarm sessions"
+    def ps
+      require_relative "commands/ps"
+      Commands::Ps.new.execute
+    end
+
+    desc "show SESSION_ID", "Show detailed session information"
+    def show(session_id)
+      require_relative "commands/show"
+      Commands::Show.new.execute(session_id)
+    end
+
+    desc "clean", "Remove stale session symlinks"
+    method_option :days, aliases: "-d", type: :numeric, default: 7,
+                         desc: "Remove sessions older than N days"
+    def clean
+      run_dir = File.expand_path("~/.claude-swarm/run")
+      unless Dir.exist?(run_dir)
+        say "No run directory found", :yellow
+        return
+      end
+
+      cleaned = 0
+      Dir.glob("#{run_dir}/*").each do |symlink|
+        next unless File.symlink?(symlink)
+
+        begin
+          # Remove if target doesn't exist (stale)
+          unless File.exist?(File.readlink(symlink))
+            File.unlink(symlink)
+            cleaned += 1
+            next
+          end
+
+          # Remove if older than specified days
+          if File.stat(symlink).mtime < Time.now - (options[:days] * 86_400)
+            File.unlink(symlink)
+            cleaned += 1
+          end
+        rescue StandardError
+          # Skip problematic symlinks
+        end
+      end
+
+      say "Cleaned #{cleaned} stale session#{cleaned == 1 ? "" : "s"}", :green
+    end
+
+    desc "watch SESSION_ID", "Watch session logs"
+    method_option :lines, aliases: "-n", type: :numeric, default: 100,
+                          desc: "Number of lines to show initially"
+    def watch(session_id)
+      # Find session path
+      run_symlink = File.join(File.expand_path("~/.claude-swarm/run"), session_id)
+      session_path = if File.symlink?(run_symlink)
+                       File.readlink(run_symlink)
+                     else
+                       # Search in sessions directory
+                       Dir.glob(File.expand_path("~/.claude-swarm/sessions/*/*")).find do |path|
+                         File.basename(path) == session_id
+                       end
+                     end
+
+      unless session_path && Dir.exist?(session_path)
+        error "Session not found: #{session_id}"
+        exit 1
+      end
+
+      log_file = File.join(session_path, "session.log")
+      unless File.exist?(log_file)
+        error "Log file not found for session: #{session_id}"
+        exit 1
+      end
+
+      exec("tail", "-f", "-n", options[:lines].to_s, log_file)
+    end
+
     desc "list-sessions", "List all available Claude Swarm sessions"
     method_option :limit, aliases: "-l", type: :numeric, default: 10,
                           desc: "Maximum number of sessions to display"

data/lib/claude_swarm/commands/ps.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+require "time"
+
+module ClaudeSwarm
+  module Commands
+    class Ps
+      RUN_DIR = File.expand_path("~/.claude-swarm/run")
+
+      def execute
+        unless Dir.exist?(RUN_DIR)
+          puts "No active sessions"
+          return
+        end
+
+        sessions = []
+
+        # Read all symlinks in run directory
+        Dir.glob("#{RUN_DIR}/*").each do |symlink|
+          next unless File.symlink?(symlink)
+
+          begin
+            session_dir = File.readlink(symlink)
+            # Skip if target doesn't exist (stale symlink)
+            next unless Dir.exist?(session_dir)
+
+            session_info = parse_session_info(session_dir)
+            sessions << session_info if session_info
+          rescue StandardError
+            # Skip problematic symlinks
+          end
+        end
+
+        if sessions.empty?
+          puts "No active sessions"
+          return
+        end
+
+        # Column widths
+        col_session = 15
+        col_swarm = 25
+        col_cost = 12
+        col_uptime = 10
+
+        # Display header with proper spacing
+        header = "#{
+          "SESSION_ID".ljust(col_session)
+        }  #{
+          "SWARM_NAME".ljust(col_swarm)
+        }  #{
+          "TOTAL_COST".ljust(col_cost)
+        }  #{
+          "UPTIME".ljust(col_uptime)
+        }  DIRECTORY"
+        puts "\n⚠️  \e[3mTotal cost does not include the cost of the main instance\e[0m\n\n"
+        puts header
+        puts "-" * header.length
+
+        # Display sessions sorted by start time (newest first)
+        sessions.sort_by { |s| s[:start_time] }.reverse.each do |session|
+          cost_str = format("$%.4f", session[:cost])
+          puts "#{
+            session[:id].ljust(col_session)
+          }  #{
+            truncate(session[:name], col_swarm).ljust(col_swarm)
+          }  #{
+            cost_str.ljust(col_cost)
+          }  #{
+            session[:uptime].ljust(col_uptime)
+          }  #{session[:directory]}"
+        end
+      end
+
+      private
+
+      def parse_session_info(session_dir)
+        session_id = File.basename(session_dir)
+
+        # Load config for swarm name and main directory
+        config_file = File.join(session_dir, "config.yml")
+        return nil unless File.exist?(config_file)
+
+        config = YAML.load_file(config_file)
+        swarm_name = config.dig("swarm", "name") || "Unknown"
+        main_instance = config.dig("swarm", "main")
+
+        # Get all directories - handle both string and array formats
+        dir_config = config.dig("swarm", "instances", main_instance, "directory")
+        directories = if dir_config.is_a?(Array)
+                        dir_config
+                      else
+                        [dir_config || "."]
+                      end
+        directories_str = directories.join(", ")
+
+        # Calculate total cost from JSON log
+        total_cost = calculate_total_cost(session_dir)
+
+        # Get uptime from directory creation time
+        start_time = File.stat(session_dir).ctime
+        uptime = format_duration(Time.now - start_time)
+
+        {
+          id: session_id,
+          name: swarm_name,
+          cost: total_cost,
+          uptime: uptime,
+          directory: directories_str,
+          start_time: start_time
+        }
+      rescue StandardError
+        nil
+      end
+
+      def calculate_total_cost(session_dir)
+        log_file = File.join(session_dir, "session.log.json")
+        return 0.0 unless File.exist?(log_file)
+
+        total = 0.0
+        File.foreach(log_file) do |line|
+          data = JSON.parse(line)
+          total += data["event"]["total_cost_usd"] if data.dig("event", "type") == "result" && data.dig("event", "total_cost_usd")
+        rescue JSON::ParserError
+          next
+        end
+        total
+      end
+
+      def format_duration(seconds)
+        if seconds < 60
+          "#{seconds.to_i}s"
+        elsif seconds < 3600
+          "#{(seconds / 60).to_i}m"
+        elsif seconds < 86_400
+          "#{(seconds / 3600).to_i}h"
+        else
+          "#{(seconds / 86_400).to_i}d"
+        end
+      end
+
+      def truncate(str, length)
+        str.length > length ? "#{str[0...length - 2]}.." : str
+      end
+    end
+  end
+end

data/lib/claude_swarm/commands/show.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+module ClaudeSwarm
+  module Commands
+    class Show
+      def execute(session_id)
+        session_path = find_session_path(session_id)
+        unless session_path
+          puts "Session not found: #{session_id}"
+          exit 1
+        end
+
+        # Load config to get main instance name
+        config = YAML.load_file(File.join(session_path, "config.yml"))
+        main_instance_name = config.dig("swarm", "main")
+
+        # Parse all events to build instance data
+        instances = parse_instance_hierarchy(session_path, main_instance_name)
+
+        # Calculate total cost (excluding main if not available)
+        total_cost = instances.values.sum { |i| i[:cost] }
+        cost_display = if instances[main_instance_name] && instances[main_instance_name][:has_cost_data]
+                         format("$%.4f", total_cost)
+                       else
+                         "#{format("$%.4f", total_cost)} (excluding main instance)"
+                       end
+
+        # Display session info
+        puts "Session: #{session_id}"
+        puts "Swarm: #{config.dig("swarm", "name")}"
+        puts "Total Cost: #{cost_display}"
+
+        # Try to read start directory
+        start_dir_file = File.join(session_path, "start_directory")
+        puts "Start Directory: #{File.read(start_dir_file).strip}" if File.exist?(start_dir_file)
+
+        puts
+        puts "Instance Hierarchy:"
+        puts "-" * 50
+
+        # Find root instances
+        roots = instances.values.select { |i| i[:called_by].empty? }
+        roots.each do |instance|
+          display_instance_tree(instance, instances, 0, main_instance_name)
+        end
+
+        # Add note about interactive main instance
+        return if instances[main_instance_name]&.dig(:has_cost_data)
+
+        puts
+        puts "Note: Main instance (#{main_instance_name}) cost is not tracked in interactive mode."
+        puts "      View costs directly in the Claude interface."
+      end
+
+      private
+
+      def find_session_path(session_id)
+        # First check the run directory
+        run_symlink = File.join(File.expand_path("~/.claude-swarm/run"), session_id)
+        if File.symlink?(run_symlink)
+          target = File.readlink(run_symlink)
+          return target if Dir.exist?(target)
+        end
+
+        # Fall back to searching all sessions
+        Dir.glob(File.expand_path("~/.claude-swarm/sessions/*/*")).find do |path|
+          File.basename(path) == session_id
+        end
+      end
+
+      def parse_instance_hierarchy(session_path, _main_instance_name)
+        log_file = File.join(session_path, "session.log.json")
+        instances = {}
+
+        return instances unless File.exist?(log_file)
+
+        File.foreach(log_file) do |line|
+          data = JSON.parse(line)
+          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
+
+          # Track costs and calls
+          if data.dig("event", "type") == "result"
+            instances[instance_name][:calls] += 1
+            if (cost = data.dig("event", "total_cost_usd"))
+              instances[instance_name][:cost] += cost
+              instances[instance_name][:has_cost_data] = true
+            end
+          end
+        rescue JSON::ParserError
+          next
+        end
+
+        instances
+      end
+
+      def display_instance_tree(instance, all_instances, level, main_instance_name)
+        indent = "  " * level
+        prefix = level.zero? ? "├─" : "└─"
+
+        # Display instance name with special marker for main
+        instance_display = instance[:name]
+        instance_display += " [main]" if instance[:name] == main_instance_name
+
+        puts "#{indent}#{prefix} #{instance_display} (#{instance[:id]})"
+
+        # Display cost - show n/a for main instance without cost data
+        cost_display = if instance[:name] == main_instance_name && !instance[:has_cost_data]
+                         "n/a (interactive)"
+                       else
+                         format("$%.4f", instance[:cost])
+                       end
+
+        puts "#{indent}   Cost: #{cost_display} | Calls: #{instance[:calls]}"
+
+        # Display children
+        children = instance[:calls_to].map { |name| all_instances[name] }.compact
+        children.each do |child|
+          # Don't recurse if we've already shown this instance (avoid cycles)
+          next if level.positive? && child[:called_by].size > 1
+
+          display_instance_tree(child, all_instances, level + 1, main_instance_name)
+        end
+      end
+    end
+  end
+end

data/lib/claude_swarm/configuration.rb

@@ -86,9 +86,13 @@ module ClaudeSwarm
       # Support both 'tools' (deprecated) and 'allowed_tools' for backward compatibility
       allowed_tools = config["allowed_tools"] || config["tools"] || []
 
+      # Parse directory field - support both string and array
+      directories = parse_directories(config["directory"])
+
       {
         name: name,
-        directory: expand_path(config["directory"] || "."),
+        directory: directories.first, # Keep single directory for backward compatibility
+        directories: directories, # New field with all directories
         model: config["model"] || "sonnet",
         connections: Array(config["connections"]),
         tools: Array(allowed_tools), # Keep as 'tools' internally for compatibility
@@ -156,8 +160,10 @@ module ClaudeSwarm
 
     def validate_directories
       @instances.each do |name, instance|
-        directory = instance[:directory]
-        raise Error, "Directory '#{directory}' for instance '#{name}' does not exist" unless File.directory?(directory)
+        # Validate all directories in the directories array
+        instance[:directories].each do |directory|
+          raise Error, "Directory '#{directory}' for instance '#{name}' does not exist" unless File.directory?(directory)
+        end
       end
     end
 
@@ -168,6 +174,17 @@ module ClaudeSwarm
       raise Error, "Instance '#{instance_name}' field '#{field_name}' must be an array, got #{field_value.class.name}" unless field_value.is_a?(Array)
     end
 
+    def parse_directories(directory_config)
+      # Default to current directory if not specified
+      directory_config ||= "."
+
+      # Convert to array and expand paths
+      directories = Array(directory_config).map { |dir| expand_path(dir) }
+
+      # Ensure at least one directory
+      directories.empty? ? [expand_path(".")] : directories
+    end
+
     def expand_path(path)
       Pathname.new(path).expand_path(@base_dir).to_s
     end

data/lib/claude_swarm/mcp_generator.rb

@@ -107,6 +107,9 @@ module ClaudeSwarm
         "--model", instance[:model]
       ]
 
+      # Add directories array if we have multiple directories
+      args.push("--directories", *instance[:directories]) if instance[:directories] && instance[:directories].size > 1
+
       # Add optional arguments
       args.push("--prompt", instance[:prompt]) if instance[:prompt]
 

data/lib/claude_swarm/orchestrator.rb

@@ -8,6 +8,8 @@ require_relative "process_tracker"
 
 module ClaudeSwarm
   class Orchestrator
+    RUN_DIR = File.expand_path("~/.claude-swarm/run")
+
     def initialize(configuration, mcp_generator, vibe: false, prompt: nil, stream_logs: false, debug: false,
                    restore_session_path: nil)
       @config = configuration
@@ -17,6 +19,7 @@ module ClaudeSwarm
       @stream_logs = stream_logs
       @debug = debug
       @restore_session_path = restore_session_path
+      @session_path = nil
     end
 
     def start
@@ -29,9 +32,13 @@ module ClaudeSwarm
 
         # Use existing session path
         session_path = @restore_session_path
+        @session_path = session_path
         ENV["CLAUDE_SWARM_SESSION_PATH"] = session_path
         ENV["CLAUDE_SWARM_START_DIR"] = Dir.pwd
 
+        # Create run symlink for restored session
+        create_run_symlink
+
         unless @prompt
           puts "📝 Using existing session: #{session_path}/"
           puts
@@ -59,10 +66,14 @@ module ClaudeSwarm
         # Generate and set session path for all instances
         session_path = SessionPath.generate(working_dir: Dir.pwd)
         SessionPath.ensure_directory(session_path)
+        @session_path = session_path
 
         ENV["CLAUDE_SWARM_SESSION_PATH"] = session_path
         ENV["CLAUDE_SWARM_START_DIR"] = Dir.pwd
 
+        # Create run symlink for new session
+        create_run_symlink
+
         unless @prompt
           puts "📝 Session files will be saved to: #{session_path}/"
           puts
@@ -90,7 +101,12 @@ module ClaudeSwarm
       unless @prompt
         puts "🚀 Launching main instance: #{@config.main_instance}"
         puts "   Model: #{main_instance[:model]}"
-        puts "   Directory: #{main_instance[:directory]}"
+        if main_instance[:directories].size == 1
+          puts "   Directory: #{main_instance[:directory]}"
+        else
+          puts "   Directories:"
+          main_instance[:directories].each { |dir| puts "     - #{dir}" }
+        end
         puts "   Allowed tools: #{main_instance[:allowed_tools].join(", ")}" if main_instance[:allowed_tools].any?
         puts "   Disallowed tools: #{main_instance[:disallowed_tools].join(", ")}" if main_instance[:disallowed_tools]&.any?
         puts "   Connections: #{main_instance[:connections].join(", ")}" if main_instance[:connections].any?
@@ -119,8 +135,9 @@ module ClaudeSwarm
         log_thread.join
       end
 
-      # Clean up child processes
+      # Clean up child processes and run symlink
       cleanup_processes
+      cleanup_run_symlink
     end
 
     private
@@ -140,6 +157,7 @@ module ClaudeSwarm
         Signal.trap(signal) do
           puts "\n🛑 Received #{signal} signal, cleaning up..."
           cleanup_processes
+          cleanup_run_symlink
           exit
         end
       end
@@ -152,6 +170,35 @@ module ClaudeSwarm
       puts "⚠️  Error during cleanup: #{e.message}"
     end
 
+    def create_run_symlink
+      return unless @session_path
+
+      FileUtils.mkdir_p(RUN_DIR)
+
+      # Session ID is the last part of the session path
+      session_id = File.basename(@session_path)
+      symlink_path = File.join(RUN_DIR, session_id)
+
+      # Remove stale symlink if exists
+      File.unlink(symlink_path) if File.symlink?(symlink_path)
+
+      # Create new symlink
+      File.symlink(@session_path, symlink_path)
+    rescue StandardError => e
+      # Don't fail the process if symlink creation fails
+      puts "⚠️  Warning: Could not create run symlink: #{e.message}" unless @prompt
+    end
+
+    def cleanup_run_symlink
+      return unless @session_path
+
+      session_id = File.basename(@session_path)
+      symlink_path = File.join(RUN_DIR, session_id)
+      File.unlink(symlink_path) if File.symlink?(symlink_path)
+    rescue StandardError
+      # Ignore errors during cleanup
+    end
+
     def start_log_streaming
       Thread.new do
         session_log_path = File.join(ENV.fetch("CLAUDE_SWARM_SESSION_PATH", nil), "session.log")
@@ -238,6 +285,14 @@ module ClaudeSwarm
 
       parts << "--debug" if @debug
 
+      # Add additional directories with --add-dir
+      if instance[:directories].size > 1
+        instance[:directories][1..].each do |additional_dir|
+          parts << "--add-dir"
+          parts << additional_dir
+        end
+      end
+
       mcp_config_path = @generator.mcp_config_path(@config.main_instance)
       parts << "--mcp-config"
       parts << mcp_config_path

data/lib/claude_swarm/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.16
+  version: 0.1.17
 platform: ruby
 authors:
 - Paulo Arruda
@@ -65,11 +65,15 @@ files:
 - example/microservices-team.yml
 - example/session-restoration-demo.yml
 - example/test-generation.yml
+- examples/monitoring-demo.yml
+- examples/multi-directory.yml
 - exe/claude-swarm
 - lib/claude_swarm.rb
 - lib/claude_swarm/claude_code_executor.rb
 - lib/claude_swarm/claude_mcp_server.rb
 - lib/claude_swarm/cli.rb
+- lib/claude_swarm/commands/ps.rb
+- lib/claude_swarm/commands/show.rb
 - lib/claude_swarm/configuration.rb
 - lib/claude_swarm/mcp_generator.rb
 - lib/claude_swarm/orchestrator.rb