claude_swarm 0.1.12 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c468e30d7de839a1b7bb88c2e2ee1c9bfa58b8bb0f0b0375b3495ebf5de340f0
-  data.tar.gz: 7234799e8b24cc2b0a691f188a890ee84d0780a77a85723307bdc9f17ad71545
+  metadata.gz: 57e09297e72fe54ef127b5f7b5789c9e9d825279404ffa96c29f2ff0e7fbc622
+  data.tar.gz: 6e1d719d97d2f8fefa4ec8d0e9396e5fba867012b94d88d915247aea18690523
 SHA512:
-  metadata.gz: 7ed4d3460c8e686f683513796939827419d254d9b4a168a211d24d89cb18aaeb4cacf42a2dd90d1b88ecbc98ab97f7391b356ed24f0beb05da4bab6c62ce5332
-  data.tar.gz: ced867554fa8b43c6ce9f327f791212dcc04a87c378d78e99c87f41776074eba7f2a1bf7691b6b9daaf34fcd7923b057cefe453171d5838f2981ee87d67237f1
+  metadata.gz: 8ad9a411c8bc503829927ea534fed74e9f525dd62d68fc6eb9978667afdb40435b9bac0c13320c097f1f41556a8d50215c723c8066dec7366cf7d847d07a7e9e
+  data.tar.gz: 490824249ac673b7904f05a084d2ff0190a1034529a9302f423d00e965cd7c793b519b1d8e318a36a1e58af80706cb1fda80dd507af525b45f7df26299abd3f9

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [Unreleased]
+
+### Added
+- **Session restoration support (Experimental)**: Session management with the ability to resume previous Claude Swarm sessions. Note: This is an experimental feature with limitations - the main instance's conversation context is not fully restored
+  - New `--session-id` flag to resume a session by ID or path
+  - New `list-sessions` command to view available sessions with metadata
+  - Automatic capture and persistence of Claude session IDs for all instances
+  - Individual instance states stored in `state/` directory with instance ID as filename (e.g., `state/lead_abc123.json`)
+  - Swarm configuration copied to session directory as `config.yml` for restoration
+- **Instance ID tracking**: Each instance now gets a unique ID in the format `instance_name_<hex>` for better identification in logs
+- **Enhanced logging with instance IDs**: All log messages now include instance IDs when available (e.g., `lead (lead_1234abcd) -> backend (backend_5678efgh)`)
+- **Calling instance ID propagation**: When one instance calls another, both the calling instance name and ID are passed for complete tracking
+- Instance IDs are stored in MCP configuration files with `instance_id` and `instance_name` fields
+- New CLI options: `--instance-id` and `--calling-instance-id` for the `mcp-serve` command
+- ClaudeCodeExecutor now tracks and logs both instance and calling instance IDs
+- **Process tracking and cleanup**: Added automatic tracking and cleanup of child MCP server processes
+  - New `ProcessTracker` class creates individual PID files in a `pids/` directory within the session path
+  - Signal handlers (INT, TERM, QUIT) ensure all child processes are terminated when the main instance exits
+  - Prevents orphaned MCP server processes from continuing to run after swarm termination
+
+### Changed
+- Human-readable logs improved to show instance IDs in parentheses after instance names for easier tracking of multi-instance interactions
+- `log_request` method enhanced to include instance IDs in structured JSON logs
+- Configuration class now accepts optional `base_dir` parameter to support session restoration from different directories
+
+### Fixed
+- Fixed issue where child MCP server processes would continue running after the main instance exits
+
 ## [0.1.12]
 ### Added
 - **Circular dependency detection**: Configuration validation now detects and reports circular dependencies between instances

data/README.md

@@ -1,6 +1,6 @@
 # Claude Swarm
 
-[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=0.1.11)](https://badge.fury.io/rb/claude_swarm)
+[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=0.1.12)](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.
@@ -80,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 session files are stored in `.claude-swarm/sessions/{timestamp}/`
+- All session files are stored in `~/.claude-swarm/sessions/{project}/{timestamp}/` (customizable via `CLAUDE_SWARM_HOME`)
 
 #### Multi-Level Swarm Example
 
@@ -446,6 +446,14 @@ claude-swarm --vibe
 claude-swarm -p "Implement the new user authentication feature"
 claude-swarm --prompt "Fix the bug in the payment module"
 
+# Resume a previous session by ID
+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
 
@@ -457,6 +465,70 @@ claude-swarm tools-mcp --allowed-tools 'Read,Edit' --disallowed-tools 'Edit(*.lo
 claude-swarm mcp-serve INSTANCE_NAME --config CONFIG_FILE --session-timestamp TIMESTAMP
 ```
 
+### 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.**
+
+#### Session Structure
+All session files are organized in `~/.claude-swarm/sessions/{project}/{timestamp}/`:
+- `config.yml`: Copy of the original swarm configuration
+- `state/`: Directory containing individual instance states
+  - `{instance_id}.json`: Claude session ID and status for each instance (e.g., `lead_abc123.json`)
+- `{instance_name}.mcp.json`: MCP configuration files
+- `session.log`: Human-readable request/response tracking
+- `session.log.json`: All events in JSONL format (one JSON per line)
+- `permissions.log`: Permission checks and decisions
+
+#### Listing Sessions
+View your previous Claude Swarm sessions:
+
+```bash
+# List recent sessions (default: 10)
+claude-swarm list-sessions
+
+# List more sessions
+claude-swarm list-sessions --limit 20
+```
+
+Output shows:
+- Session ID (timestamp)
+- Creation time
+- Main instance name
+- Number of instances
+- Configuration file used
+- Full session path
+
+#### Resuming Sessions
+Resume a previous session with all instances restored to their Claude session states:
+
+```bash
+# Resume by session ID
+claude-swarm --session-id 20241206_143022
+
+# Resume by full path
+claude-swarm --session-id ~/.claude-swarm/sessions/my-project/20241206_143022
+```
+
+This will:
+1. Load the session manifest and instance states
+2. Restore the original swarm configuration
+3. Resume the main instance with its Claude session ID
+4. Restore all connected instances with their session IDs
+5. Maintain the same working directories and tool permissions
+
+#### How Session Restoration Works
+- Each instance's Claude session ID is automatically captured and persisted
+- Instance states are stored in separate files named by instance ID to prevent concurrency issues
+- MCP configurations are regenerated with the saved session IDs
+- The main instance uses Claude's `--resume` flag (limited effectiveness)
+- Connected instances receive their session IDs via `--claude-session-id`
+
+**Important Limitations:**
+- The main instance's conversation history and context are not fully restored
+- Only the session ID is preserved, not the actual conversation state
+- Connected instances restore more reliably than the main instance
+- This is an experimental feature and may not work as expected
+
 ## How It Works
 
 1. **Configuration Parsing**: Claude Swarm reads your YAML configuration and validates it
@@ -471,20 +543,17 @@ claude-swarm mcp-serve INSTANCE_NAME --config CONFIG_FILE --session-timestamp TI
    - Eliminates the need to manually accept each tool or use global `--vibe` mode
    - Per-instance `vibe: true` skips all permission checks for that specific instance
    - The permission MCP uses `--permission-prompt-tool` to check tool access
-   - Permission decisions are logged to `.claude-swarm/sessions/{timestamp}/permissions.log`
-4. **Session Management**: Claude Swarm maintains session continuity:
-   - Generates a shared session timestamp for all instances
-   - Each instance can maintain its own Claude session ID
-   - Sessions can be reset via the MCP server interface
+   - Permission decisions are logged to `~/.claude-swarm/sessions/{project}/{timestamp}/permissions.log`
+4. **Session Persistence**: Claude Swarm automatically tracks session state:
+   - Generates a shared session path for all instances
+   - Each instance's Claude session ID is captured and saved
+   - Instance states are stored using instance IDs as filenames to avoid conflicts
+   - Sessions can be fully restored with all instances reconnected
 5. **Main Instance Launch**: The main instance is launched with its MCP configuration, giving it access to all connected instances
 6. **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. 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
-7. **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
-   - Permission log: `permissions.log` with all permission checks and decisions
 
 ## Troubleshooting
 
@@ -507,14 +576,15 @@ claude-swarm mcp-serve INSTANCE_NAME --config CONFIG_FILE --session-timestamp TI
 ### Debug Output
 
 The swarm will display:
-- Session directory location (`.claude-swarm/sessions/{timestamp}/`)
+- Session directory location (`~/.claude-swarm/sessions/{project}/{timestamp}/`)
 - Main instance details (model, directory, tools, connections)
 - The exact command being run
 
 ### Session Files
 
-Check the session directory `.claude-swarm/sessions/{timestamp}/` for:
-- `session.log`: Detailed logs with request/response tracking
+Check the session directory `~/.claude-swarm/sessions/{project}/{timestamp}/` for:
+- `session.log`: Human-readable logs with request/response tracking
+- `session.log.json`: All events in JSONL format (one JSON object per line)
 - `{instance}.mcp.json`: MCP configuration for each instance
 - All files for a session are kept together for easy review
 

data/example/session-restoration-demo.yml

@@ -0,0 +1,19 @@
+version: 1
+swarm:
+  name: "Session Restoration Demo"
+  main: coordinator
+  instances:
+    coordinator:
+      description: "Main coordinator that manages the team"
+      directory: .
+      model: sonnet
+      prompt: "You are the team coordinator. You help manage tasks and coordinate between team members."
+      allowed_tools: [Read, Edit, Bash]
+      connections: [developer]
+    
+    developer:
+      description: "Developer who writes code"
+      directory: .
+      model: sonnet
+      prompt: "You are a skilled developer who writes clean, well-tested code."
+      allowed_tools: [Read, Edit, Write, Bash]

data/lib/claude_swarm/claude_code_executor.rb

@@ -10,15 +10,19 @@ module ClaudeSwarm
   class ClaudeCodeExecutor
     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)
+    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)
       @working_directory = working_directory
       @model = model
       @mcp_config = mcp_config
       @vibe = vibe
-      @session_id = nil
+      @session_id = claude_session_id
       @last_response = nil
       @instance_name = instance_name
+      @instance_id = instance_id
       @calling_instance = calling_instance
+      @calling_instance_id = calling_instance_id
 
       # Setup logging
       setup_logging
@@ -51,7 +55,10 @@ module ClaudeSwarm
           log_streaming_event(json_data)
 
           # Capture session_id from system init
-          @session_id = json_data["session_id"] if json_data["type"] == "system" && json_data["subtype"] == "init"
+          if json_data["type"] == "system" && json_data["subtype"] == "init"
+            @session_id = json_data["session_id"]
+            write_instance_state
+          end
 
           # Capture the final result
           result_response = json_data if json_data["type"] == "result"
@@ -92,6 +99,27 @@ module ClaudeSwarm
 
     private
 
+    def write_instance_state
+      return unless @instance_id && @session_id
+
+      state_dir = File.join(@session_path, "state")
+      FileUtils.mkdir_p(state_dir)
+
+      state_file = File.join(state_dir, "#{@instance_id}.json")
+      state_data = {
+        instance_name: @instance_name,
+        instance_id: @instance_id,
+        claude_session_id: @session_id,
+        status: "active",
+        updated_at: Time.now.iso8601
+      }
+
+      File.write(state_file, JSON.pretty_generate(state_data))
+      @logger.info("Wrote instance state for #{@instance_name} (#{@instance_id}) with session ID: #{@session_id}")
+    rescue StandardError => e
+      @logger.error("Failed to write instance state for #{@instance_name} (#{@instance_id}): #{e.message}")
+    end
+
     def setup_logging
       # Use session path from environment (required)
       @session_path = SessionPath.from_env
@@ -108,16 +136,41 @@ module ClaudeSwarm
         "[#{datetime.strftime("%Y-%m-%d %H:%M:%S.%L")}] [#{severity}] #{msg}\n"
       end
 
-      @logger.info("Started Claude Code executor for instance: #{@instance_name}") if @instance_name
+      return unless @instance_name
+
+      instance_info = @instance_name
+      instance_info += " (#{@instance_id})" if @instance_id
+      @logger.info("Started Claude Code executor for instance: #{instance_info}")
     end
 
     def log_request(prompt)
-      @logger.info("#{@calling_instance} -> #{@instance_name}: \n---\n#{prompt}\n---")
+      caller_info = @calling_instance
+      caller_info += " (#{@calling_instance_id})" if @calling_instance_id
+      instance_info = @instance_name
+      instance_info += " (#{@instance_id})" if @instance_id
+      @logger.info("#{caller_info} -> #{instance_info}: \n---\n#{prompt}\n---")
+
+      # Build event hash for JSON logging
+      event = {
+        type: "request",
+        from_instance: @calling_instance,
+        from_instance_id: @calling_instance_id,
+        to_instance: @instance_name,
+        to_instance_id: @instance_id,
+        prompt: prompt,
+        timestamp: Time.now.iso8601
+      }
+
+      append_to_session_json(event)
     end
 
     def log_response(response)
+      caller_info = @calling_instance
+      caller_info += " (#{@calling_instance_id})" if @calling_instance_id
+      instance_info = @instance_name
+      instance_info += " (#{@instance_id})" if @instance_id
       @logger.info(
-        "($#{response["total_cost"]} - #{response["duration_ms"]}ms) #{@instance_name} -> #{@calling_instance}: \n---\n#{response["result"]}\n---"
+        "($#{response["total_cost"]} - #{response["duration_ms"]}ms) #{instance_info} -> #{caller_info}: \n---\n#{response["result"]}\n---"
       )
     end
 
@@ -151,14 +204,18 @@ module ClaudeSwarm
         arguments = tool_call["input"].to_json
         arguments = "#{arguments[0..300]} ...}" if arguments.length > 300
 
+        instance_info = @instance_name
+        instance_info += " (#{@instance_id})" if @instance_id
         @logger.info(
-          "Tool call from #{@instance_name} -> Tool: #{tool_call["name"]}, ID: #{tool_call["id"]}, Arguments: #{arguments}"
+          "Tool call from #{instance_info} -> Tool: #{tool_call["name"]}, ID: #{tool_call["id"]}, Arguments: #{arguments}"
         )
       end
 
       text = content.select { |c| c["type"] == "text" }
       text.each do |t|
-        @logger.info("#{@instance_name} is thinking:\n---\n#{t["text"]}\n---")
+        instance_info = @instance_name
+        instance_info += " (#{@instance_id})" if @instance_id
+        @logger.info("#{instance_info} is thinking:\n---\n#{t["text"]}\n---")
       end
     end
 
@@ -177,7 +234,9 @@ module ClaudeSwarm
         # Create entry with metadata
         entry = {
           instance: @instance_name,
+          instance_id: @instance_id,
           calling_instance: @calling_instance,
+          calling_instance_id: @calling_instance_id,
           timestamp: Time.now.iso8601,
           event: event
         }

data/lib/claude_swarm/claude_mcp_server.rb

@@ -6,24 +6,29 @@ require_relative "claude_code_executor"
 require_relative "task_tool"
 require_relative "session_info_tool"
 require_relative "reset_session_tool"
+require_relative "process_tracker"
 
 module ClaudeSwarm
   class ClaudeMcpServer
     # Class variables to share state with tool classes
     class << self
-      attr_accessor :executor, :instance_config, :logger, :session_path, :calling_instance
+      attr_accessor :executor, :instance_config, :logger, :session_path, :calling_instance, :calling_instance_id
     end
 
-    def initialize(instance_config, calling_instance:)
+    def initialize(instance_config, calling_instance:, calling_instance_id: nil)
       @instance_config = instance_config
       @calling_instance = calling_instance
+      @calling_instance_id = calling_instance_id
       @executor = ClaudeCodeExecutor.new(
         working_directory: instance_config[:directory],
         model: instance_config[:model],
         mcp_config: instance_config[:mcp_config_path],
         vibe: instance_config[:vibe],
         instance_name: instance_config[:name],
-        calling_instance: calling_instance
+        instance_id: instance_config[:instance_id],
+        calling_instance: calling_instance,
+        calling_instance_id: calling_instance_id,
+        claude_session_id: instance_config[:claude_session_id]
       )
 
       # Set class variables so tools can access them
@@ -32,9 +37,16 @@ module ClaudeSwarm
       self.class.logger = @executor.logger
       self.class.session_path = @executor.session_path
       self.class.calling_instance = @calling_instance
+      self.class.calling_instance_id = @calling_instance_id
     end
 
     def start
+      # Track this process
+      if @executor.session_path && File.exist?(@executor.session_path)
+        tracker = ProcessTracker.new(@executor.session_path)
+        tracker.track_pid(Process.pid, "mcp_#{@instance_config[:name]}")
+      end
+
       server = FastMcp::Server.new(
         name: @instance_config[:name],
         version: "1.0.0"

data/lib/claude_swarm/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "thor"
+require "json"
 require_relative "configuration"
 require_relative "mcp_generator"
 require_relative "orchestrator"
@@ -24,7 +25,15 @@ module ClaudeSwarm
                                 desc: "Stream session logs to stdout (only works with -p)"
     method_option :debug, type: :boolean, default: false,
                           desc: "Enable debug output"
+    method_option :session_id, type: :string,
+                               desc: "Resume a previous session by ID or path"
     def start(config_file = nil)
+      # Handle session restoration
+      if options[:session_id]
+        restore_session(options[:session_id])
+        return
+      end
+
       config_path = config_file || options[:config]
       unless File.exist?(config_path)
         error "Configuration file not found: #{config_path}"
@@ -81,6 +90,12 @@ module ClaudeSwarm
                          desc: "Run with --dangerously-skip-permissions"
     method_option :calling_instance, type: :string, required: true,
                                      desc: "Name of the instance that launched this MCP server"
+    method_option :calling_instance_id, type: :string,
+                                        desc: "Unique ID of the instance that launched this MCP server"
+    method_option :instance_id, type: :string,
+                                desc: "Unique ID of this instance"
+    method_option :claude_session_id, type: :string,
+                                      desc: "Claude session ID to resume"
     def mcp_serve
       instance_config = {
         name: options[:name],
@@ -91,11 +106,17 @@ module ClaudeSwarm
         tools: options[:tools] || [],
         disallowed_tools: options[:disallowed_tools] || [],
         mcp_config_path: options[:mcp_config_path],
-        vibe: options[:vibe]
+        vibe: options[:vibe],
+        instance_id: options[:instance_id],
+        claude_session_id: options[:claude_session_id]
       }
 
       begin
-        server = ClaudeMcpServer.new(instance_config, calling_instance: options[:calling_instance])
+        server = ClaudeMcpServer.new(
+          instance_config,
+          calling_instance: options[:calling_instance],
+          calling_instance_id: options[:calling_instance_id]
+        )
         server.start
       rescue StandardError => e
         error "Error starting MCP server: #{e.message}"
@@ -171,6 +192,79 @@ module ClaudeSwarm
       say "Claude Swarm #{VERSION}"
     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"
+    def list_sessions
+      sessions_dir = File.expand_path("~/.claude-swarm/sessions")
+      unless Dir.exist?(sessions_dir)
+        say "No sessions found", :yellow
+        return
+      end
+
+      # Find all sessions with MCP configs
+      sessions = []
+      Dir.glob("#{sessions_dir}/*/*/*.mcp.json").each do |mcp_path|
+        session_path = File.dirname(mcp_path)
+        session_id = File.basename(session_path)
+        project_name = File.basename(File.dirname(session_path))
+
+        # Skip if we've already processed this session
+        next if sessions.any? { |s| s[:path] == session_path }
+
+        # Try to load session info
+        config_file = File.join(session_path, "config.yml")
+        next unless File.exist?(config_file)
+
+        # Load the config to get swarm info
+        config_data = YAML.load_file(config_file)
+        swarm_name = config_data.dig("swarm", "name") || "Unknown"
+        main_instance = config_data.dig("swarm", "main") || "Unknown"
+
+        mcp_files = Dir.glob(File.join(session_path, "*.mcp.json"))
+
+        # Get creation time from directory
+        created_at = File.stat(session_path).ctime
+
+        sessions << {
+          path: session_path,
+          id: session_id,
+          project: project_name,
+          created_at: created_at,
+          main_instance: main_instance,
+          instances_count: mcp_files.size,
+          swarm_name: swarm_name,
+          config_path: config_file
+        }
+      rescue StandardError
+        # Skip invalid manifests
+        next
+      end
+
+      if sessions.empty?
+        say "No sessions found", :yellow
+        return
+      end
+
+      # Sort by creation time (newest first)
+      sessions.sort_by! { |s| -s[:created_at].to_i }
+      sessions = sessions.first(options[:limit])
+
+      # Display sessions
+      say "\nAvailable sessions (newest first):\n", :bold
+      sessions.each do |session|
+        say "\n#{session[:project]}/#{session[:id]}", :green
+        say "  Created: #{session[:created_at].strftime("%Y-%m-%d %H:%M:%S")}"
+        say "  Main: #{session[:main_instance]}"
+        say "  Instances: #{session[:instances_count]}"
+        say "  Swarm: #{session[:swarm_name]}"
+        say "  Config: #{session[:config_path]}", :cyan
+      end
+
+      say "\nTo resume a session, run:", :bold
+      say "  claude-swarm --session-id <session-id>", :cyan
+    end
+
     desc "tools-mcp", "Start a permission management MCP server for tool access control"
     method_option :allowed_tools, aliases: "-t", type: :string,
                                   desc: "Comma-separated list of allowed tool patterns (supports wildcards)"
@@ -194,5 +288,77 @@ module ClaudeSwarm
     def error(message)
       say message, :red
     end
+
+    def restore_session(session_id)
+      say "Restoring session: #{session_id}", :green
+
+      # Find the session path
+      session_path = find_session_path(session_id)
+      unless session_path
+        error "Session not found: #{session_id}"
+        exit 1
+      end
+
+      begin
+        # Load session info from instance ID in MCP config
+        mcp_files = Dir.glob(File.join(session_path, "*.mcp.json"))
+        if mcp_files.empty?
+          error "No MCP configuration files found in session"
+          exit 1
+        end
+
+        # Load the configuration from the session directory
+        config_file = File.join(session_path, "config.yml")
+
+        unless File.exist?(config_file)
+          error "Configuration file not found in session"
+          exit 1
+        end
+
+        # Change to the original start directory if it exists
+        start_dir_file = File.join(session_path, "start_directory")
+        if File.exist?(start_dir_file)
+          original_dir = File.read(start_dir_file).strip
+          if Dir.exist?(original_dir)
+            Dir.chdir(original_dir)
+            say "Changed to original directory: #{original_dir}", :green unless options[:prompt]
+          else
+            error "Original directory no longer exists: #{original_dir}"
+            exit 1
+          end
+        end
+
+        config = Configuration.new(config_file, base_dir: Dir.pwd)
+
+        # Create orchestrator with restoration mode
+        generator = McpGenerator.new(config, vibe: options[:vibe], restore_session_path: session_path)
+        orchestrator = Orchestrator.new(config, generator,
+                                        vibe: options[:vibe],
+                                        prompt: options[:prompt],
+                                        stream_logs: options[:stream_logs],
+                                        debug: options[:debug],
+                                        restore_session_path: session_path)
+        orchestrator.start
+      rescue StandardError => e
+        error "Failed to restore session: #{e.message}"
+        error e.backtrace.join("\n") if options[:debug]
+        exit 1
+      end
+    end
+
+    def find_session_path(session_id)
+      sessions_dir = File.expand_path("~/.claude-swarm/sessions")
+
+      # Check if it's a full path
+      return session_id if File.exist?(File.join(session_id, "config.yml"))
+
+      # Search for the session ID in all projects
+      Dir.glob("#{sessions_dir}/*/#{session_id}").each do |path|
+        config_path = File.join(path, "config.yml")
+        return path if File.exist?(config_path)
+      end
+
+      nil
+    end
   end
 end

data/lib/claude_swarm/configuration.rb

@@ -5,11 +5,11 @@ require "pathname"
 
 module ClaudeSwarm
   class Configuration
-    attr_reader :config, :swarm_name, :main_instance, :instances
+    attr_reader :config, :config_path, :swarm, :swarm_name, :main_instance, :instances
 
-    def initialize(config_path)
+    def initialize(config_path, base_dir: nil)
       @config_path = Pathname.new(config_path).expand_path
-      @config_dir = @config_path.dirname
+      @config_dir = base_dir || @config_path.dirname
       load_and_validate
     end
 
@@ -60,11 +60,11 @@ module ClaudeSwarm
     end
 
     def parse_swarm
-      swarm = @config["swarm"]
-      @swarm_name = swarm["name"]
-      @main_instance = swarm["main"]
+      @swarm = @config["swarm"]
+      @swarm_name = @swarm["name"]
+      @main_instance = @swarm["main"]
       @instances = {}
-      swarm["instances"].each do |name, config|
+      @swarm["instances"].each do |name, config|
         @instances[name] = parse_instance(name, config)
       end
       validate_connections

data/lib/claude_swarm/mcp_generator.rb

@@ -3,19 +3,33 @@
 require "json"
 require "fileutils"
 require "shellwords"
+require "securerandom"
 require_relative "session_path"
 
 module ClaudeSwarm
   class McpGenerator
-    def initialize(configuration, vibe: false)
+    def initialize(configuration, vibe: false, restore_session_path: nil)
       @config = configuration
       @vibe = vibe
+      @restore_session_path = restore_session_path
       @session_path = nil # Will be set when needed
+      @instance_ids = {} # Store instance IDs for all instances
+      @restore_states = {} # Store loaded state data during restoration
     end
 
     def generate_all
       ensure_swarm_directory
 
+      if @restore_session_path
+        # Load existing instance IDs and states from state files
+        load_instance_states
+      else
+        # Generate new instance IDs
+        @config.instances.each_key do |name|
+          @instance_ids[name] = "#{name}_#{SecureRandom.hex(4)}"
+        end
+      end
+
       @config.instances.each do |name, instance|
         generate_mcp_config(name, instance)
       end
@@ -48,13 +62,18 @@ 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, calling_instance: name)
+        mcp_servers[connection_name] = build_instance_mcp_config(
+          connection_name, connected_instance,
+          calling_instance: name, calling_instance_id: @instance_ids[name]
+        )
       end
 
       # Add permission MCP server if not in vibe mode (global or instance-specific)
       mcp_servers["permissions"] = build_permission_mcp_config(instance[:tools], instance[:disallowed_tools]) unless @vibe || instance[:vibe]
 
       config = {
+        "instance_id" => @instance_ids[name],
+        "instance_name" => name,
         "mcpServers" => mcp_servers
       }
 
@@ -79,7 +98,7 @@ module ClaudeSwarm
       end
     end
 
-    def build_instance_mcp_config(name, instance, calling_instance:)
+    def build_instance_mcp_config(name, instance, calling_instance:, calling_instance_id:)
       # Get the path to the claude-swarm executable
       exe_path = "claude-swarm"
 
@@ -104,8 +123,18 @@ module ClaudeSwarm
 
       args.push("--calling-instance", calling_instance) if calling_instance
 
+      args.push("--calling-instance-id", calling_instance_id) if calling_instance_id
+
+      args.push("--instance-id", @instance_ids[name]) if @instance_ids[name]
+
       args.push("--vibe") if @vibe || instance[:vibe]
 
+      # Add claude session ID if restoring
+      if @restore_states[name.to_s]
+        claude_session_id = @restore_states[name.to_s]["claude_session_id"]
+        args.push("--claude-session-id", claude_session_id) if claude_session_id
+      end
+
       {
         "type" => "stdio",
         "command" => exe_path,
@@ -113,6 +142,27 @@ module ClaudeSwarm
       }
     end
 
+    def load_instance_states
+      state_dir = File.join(@restore_session_path, "state")
+      return unless Dir.exist?(state_dir)
+
+      Dir.glob(File.join(state_dir, "*.json")).each do |state_file|
+        data = JSON.parse(File.read(state_file))
+        instance_name = data["instance_name"]
+        instance_id = data["instance_id"]
+
+        # Check both string and symbol keys since config instances might have either
+        if instance_name && (@config.instances.key?(instance_name) || @config.instances.key?(instance_name.to_sym))
+          # Store with the same key type as in @config.instances
+          key = @config.instances.key?(instance_name) ? instance_name : instance_name.to_sym
+          @instance_ids[key] = instance_id
+          @restore_states[instance_name] = data
+        end
+      rescue StandardError
+        # Skip invalid state files
+      end
+    end
+
     def build_permission_mcp_config(allowed_tools, disallowed_tools)
       exe_path = "claude-swarm"
 

data/lib/claude_swarm/orchestrator.rb

@@ -1,43 +1,88 @@
 # frozen_string_literal: true
 
 require "shellwords"
+require "json"
+require "fileutils"
 require_relative "session_path"
+require_relative "process_tracker"
 
 module ClaudeSwarm
   class Orchestrator
-    def initialize(configuration, mcp_generator, vibe: false, prompt: nil, stream_logs: false, debug: false)
+    def initialize(configuration, mcp_generator, vibe: false, prompt: nil, stream_logs: false, debug: false,
+                   restore_session_path: nil)
       @config = configuration
       @generator = mcp_generator
       @vibe = vibe
       @prompt = prompt
       @stream_logs = stream_logs
       @debug = debug
+      @restore_session_path = restore_session_path
     end
 
     def start
-      unless @prompt
-        puts "🐝 Starting Claude Swarm: #{@config.swarm_name}"
-        puts "😎 Vibe mode ON" if @vibe
-        puts
-      end
+      if @restore_session_path
+        unless @prompt
+          puts "🔄 Restoring Claude Swarm: #{@config.swarm_name}"
+          puts "😎 Vibe mode ON" if @vibe
+          puts
+        end
 
-      # Generate and set session path for all instances
-      session_path = SessionPath.generate(working_dir: Dir.pwd)
-      SessionPath.ensure_directory(session_path)
+        # Use existing session path
+        session_path = @restore_session_path
+        ENV["CLAUDE_SWARM_SESSION_PATH"] = session_path
+        ENV["CLAUDE_SWARM_START_DIR"] = Dir.pwd
 
-      ENV["CLAUDE_SWARM_SESSION_PATH"] = session_path
-      ENV["CLAUDE_SWARM_START_DIR"] = Dir.pwd
+        unless @prompt
+          puts "📝 Using existing session: #{session_path}/"
+          puts
+        end
 
-      unless @prompt
-        puts "📝 Session files will be saved to: #{session_path}/"
-        puts
-      end
+        # Initialize process tracker
+        @process_tracker = ProcessTracker.new(session_path)
 
-      # Generate all MCP configuration files
-      @generator.generate_all
-      unless @prompt
-        puts "✓ Generated MCP configurations in session directory"
-        puts
+        # Set up signal handlers to clean up child processes
+        setup_signal_handlers
+
+        # Regenerate MCP configurations with session IDs for restoration
+        @generator.generate_all
+        unless @prompt
+          puts "✓ Regenerated MCP configurations with session IDs"
+          puts
+        end
+      else
+        unless @prompt
+          puts "🐝 Starting Claude Swarm: #{@config.swarm_name}"
+          puts "😎 Vibe mode ON" if @vibe
+          puts
+        end
+
+        # 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: #{session_path}/"
+          puts
+        end
+
+        # Initialize process tracker
+        @process_tracker = ProcessTracker.new(session_path)
+
+        # Set up signal handlers to clean up child processes
+        setup_signal_handlers
+
+        # Generate all MCP configuration files
+        @generator.generate_all
+        unless @prompt
+          puts "✓ Generated MCP configurations in session directory"
+          puts
+        end
+
+        # Save swarm config path for restoration
+        save_swarm_config_path(session_path)
       end
 
       # Launch the main instance
@@ -69,14 +114,44 @@ module ClaudeSwarm
       end
 
       # Clean up log streaming thread
-      return unless log_thread
+      if log_thread
+        log_thread.terminate
+        log_thread.join
+      end
 
-      log_thread.terminate
-      log_thread.join
+      # Clean up child processes
+      cleanup_processes
     end
 
     private
 
+    def save_swarm_config_path(session_path)
+      # Copy the YAML config file to the session directory
+      config_copy_path = File.join(session_path, "config.yml")
+      FileUtils.cp(@config.config_path, config_copy_path)
+
+      # Save the original working directory
+      start_dir_file = File.join(session_path, "start_directory")
+      File.write(start_dir_file, Dir.pwd)
+    end
+
+    def setup_signal_handlers
+      %w[INT TERM QUIT].each do |signal|
+        Signal.trap(signal) do
+          puts "\n🛑 Received #{signal} signal, cleaning up..."
+          cleanup_processes
+          exit
+        end
+      end
+    end
+
+    def cleanup_processes
+      @process_tracker.cleanup_all
+      puts "✓ Cleanup complete"
+    rescue StandardError => e
+      puts "⚠️  Error during cleanup: #{e.message}"
+    end
+
     def start_log_streaming
       Thread.new do
         session_log_path = File.join(ENV.fetch("CLAUDE_SWARM_SESSION_PATH", nil), "session.log")
@@ -110,6 +185,26 @@ module ClaudeSwarm
         instance[:model]
       ]
 
+      # Add resume flag if restoring session
+      if @restore_session_path
+        # Look for main instance state file
+        main_instance_name = @config.main_instance
+        state_files = Dir.glob(File.join(@restore_session_path, "state", "*.json"))
+
+        # Find the state file for the main instance
+        state_files.each do |state_file|
+          state_data = JSON.parse(File.read(state_file))
+          next unless state_data["instance_name"] == main_instance_name
+
+          claude_session_id = state_data["claude_session_id"]
+          if claude_session_id
+            parts << "--resume"
+            parts << claude_session_id
+          end
+          break
+        end
+      end
+
       if @vibe || instance[:vibe]
         parts << "--dangerously-skip-permissions"
       else

data/lib/claude_swarm/permission_mcp_server.rb

@@ -6,6 +6,7 @@ require "logger"
 require "fileutils"
 require_relative "permission_tool"
 require_relative "session_path"
+require_relative "process_tracker"
 
 module ClaudeSwarm
   class PermissionMcpServer
@@ -46,6 +47,13 @@ module ClaudeSwarm
     end
 
     def create_and_start_server
+      # Track this process
+      session_path = SessionPath.from_env
+      if session_path && File.exist?(session_path)
+        tracker = ProcessTracker.new(session_path)
+        tracker.track_pid(Process.pid, "mcp_permissions")
+      end
+
       server = FastMcp::Server.new(
         name: SERVER_NAME,
         version: SERVER_VERSION

data/lib/claude_swarm/process_tracker.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+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
+
+    def self.cleanup_session(session_path)
+      return unless Dir.exist?(File.join(session_path, PIDS_DIR))
+
+      tracker = new(session_path)
+      tracker.cleanup_all
+    end
+
+    private
+
+    def ensure_pids_directory
+      FileUtils.mkdir_p(@pids_dir)
+    end
+  end
+end

data/lib/claude_swarm/version.rb

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

data/lib/claude_swarm.rb

@@ -2,10 +2,18 @@
 
 require_relative "claude_swarm/version"
 require_relative "claude_swarm/cli"
+require_relative "claude_swarm/configuration"
+require_relative "claude_swarm/mcp_generator"
+require_relative "claude_swarm/orchestrator"
 require_relative "claude_swarm/claude_code_executor"
 require_relative "claude_swarm/claude_mcp_server"
 require_relative "claude_swarm/permission_tool"
 require_relative "claude_swarm/permission_mcp_server"
+require_relative "claude_swarm/session_path"
+require_relative "claude_swarm/session_info_tool"
+require_relative "claude_swarm/reset_session_tool"
+require_relative "claude_swarm/task_tool"
+require_relative "claude_swarm/process_tracker"
 
 module ClaudeSwarm
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.12
+  version: 0.1.13
 platform: ruby
 authors:
 - Paulo Arruda
@@ -61,6 +61,7 @@ files:
 - claude-swarm.yml
 - example/claude-swarm.yml
 - example/microservices-team.yml
+- example/session-restoration-demo.yml
 - example/test-generation.yml
 - exe/claude-swarm
 - lib/claude_swarm.rb
@@ -72,6 +73,7 @@ files:
 - lib/claude_swarm/orchestrator.rb
 - lib/claude_swarm/permission_mcp_server.rb
 - lib/claude_swarm/permission_tool.rb
+- lib/claude_swarm/process_tracker.rb
 - lib/claude_swarm/reset_session_tool.rb
 - lib/claude_swarm/session_info_tool.rb
 - lib/claude_swarm/session_path.rb