claude_swarm 0.1.19 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecbec0c31b9252f826e28978e871cdc0003644d691a541906a8c36ae60c717f6
-  data.tar.gz: 9d88ab7118d614108adcd2995b270f3c223e08a0a7ccd8768136f362f9f002d6
+  metadata.gz: 4085d9345464dcd7fc7be4c78155aa03f2467f7f089b056f2be0589f5de260f2
+  data.tar.gz: fda22e57619c30b1d9e1efcabb5a8a0b2b74f9f6df2d969944e07d27753adbd9
 SHA512:
-  metadata.gz: 66783c2bc619846d7ce78b33e290d34b414946a5e66714f0528ef312a1e641cc9c6950e30d492e1f428374da391f39e11556bffaa68ced4b4cda726987ea4a8c
-  data.tar.gz: f04e7f694fb8f151c5ccfa4bd145a2184cb7674b78a1c3af414704664b6efadd5887d9f78e3ad8da4d7f41a25bdfb8e23d355eb79c4bb7675aebb79424995a59
+  metadata.gz: 216ff3a7bfda3f2763195eec1e32821596d7047c155d0757d33da0718ad1dbb3c51f04fe50591c2a99d98da37d53255a9bda11c9bf9b6bf79dff788ac27fc0c9
+  data.tar.gz: 39784e3be63360c32ec3388983a10068f9d8193bde6cebef190aae856a2da9caa47cb63c772e268203a85eb8a8fad2e0717a901401fffbd0ce8e716979cd3f20

data/.rubocop.yml

@@ -1,68 +1,14 @@
-AllCops:
-  TargetRubyVersion: 3.4
-  NewCops: enable
+inherit_from: .rubocop_todo.yml
+
+inherit_gem:
+  rubocop-shopify: rubocop.yml
 
 plugins:
   - rubocop-minitest
   - rubocop-rake
 
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
-
-# Disable documentation for internal classes
-Style/Documentation:
-  Enabled: false
-
-# Allow slightly longer methods
-Metrics/MethodLength:
-  Enabled: false
-
-# Disable gemspec specific cops
-Gemspec/RequireMFA:
-  Enabled: false
-
-Gemspec/RequiredRubyVersion:
-  Enabled: false
-
-Gemspec/DevelopmentDependencies:
-  Enabled: false
-
-Naming/AccessorMethodName:
-  Enabled: false
-
-Metrics/BlockLength:
-  Enabled: false
-
-Metrics/ClassLength:
-  Enabled: false
-
-Metrics/PerceivedComplexity:
-  Enabled: false
-
-Metrics/CyclomaticComplexity:
-  Enabled: false
-
-Metrics/AbcSize:
-  Enabled: false
-
-Naming/PredicateName:
-  Enabled: false
-
-Layout/LineLength:
-  Max: 150
-
-Metrics/ModuleLength:
-  Enabled: false
-
-Minitest/MultipleAssertions:
-  Enabled: false
-
-Metrics/ParameterLists:
-  Enabled: false
-
-Style/PerlBackrefs:
-  Enabled: false
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  Exclude:
+    - '.ruby-lsp/**/*'

data/.rubocop_todo.yml

@@ -0,0 +1,11 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-07-02 11:28:10 UTC using RuboCop version 1.77.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 34
+Minitest/MultipleAssertions:
+  Max: 23

data/CHANGELOG.md

@@ -1,3 +1,113 @@
+## [0.2.0]
+
+### Added
+- **After commands support**: Added `after` field to swarm configuration for executing cleanup commands
+  - Commands run after Claude exits but before cleanup processes
+  - Execute in the main instance's directory (including worktree if enabled)
+  - Run even when interrupted by signals (Ctrl+C)
+  - Failures in after commands do not prevent cleanup from proceeding
+  - Not executed during session restoration
+  - Example: `after: ["docker-compose down", "rm -rf temp/*"]`
+
+### Changed
+- **Session restoration command**: Session restoration now uses a dedicated `restore` command instead of the `--session-id` flag
+  - Previous: `claude-swarm start --session-id SESSION_ID`
+  - New: `claude-swarm restore SESSION_ID`
+  - More intuitive command structure following standard CLI patterns
+- **Removed redundant -c flag**: The `-c/--config` option has been removed from the `start` command
+  - Config file can still be specified as a positional argument: `claude-swarm start my-config.yml`
+  - Default remains `claude-swarm.yml` when no file is specified
+- **Session ID format**: Session IDs now use UUIDs instead of timestamp format
+  - Previous format: `YYYYMMDD_HHMMSS` (e.g., `20250707_181341`)
+  - New format: UUID v4 (e.g., `550e8400-e29b-41d4-a716-446655440000`)
+  - Provides globally unique identifiers suitable for external application integration
+  - Sessions remain sorted by file creation time, not by ID
+- **BREAKING CHANGE: Before commands now execute in main instance directory**: The `before` commands specified in swarm configuration now run after changing to the main instance's directory (including worktrees when enabled), rather than in the original working directory
+  - This ensures commands like `npm install` or `bundle install` affect only the isolated worktree
+  - Makes behavior more intuitive and consistent with user expectations
+  - Existing swarms relying on before commands running in the original directory will need to be updated
+- **Custom session ID support**: Added `--session-id` option to the `start` command to allow users to specify their own session ID
+  - Use `claude-swarm start --session-id my-custom-id` to use a custom session ID
+  - If not provided, a UUID is generated automatically
+  - Useful for integrating with external systems that need predictable session identifiers
+- **Environment variable interpolation in configuration**: Claude Swarm now supports environment variable interpolation in all YAML configuration values
+  - Use `${ENV_VAR_NAME}` syntax to reference environment variables
+  - Variables are interpolated recursively in strings, arrays, and nested structures
+  - Fails with clear error message if referenced environment variable is not set
+  - Supports multiple variables in the same string and partial string interpolation
+- **Environment variable defaults**: Environment variables in configuration now support default values
+  - Use `${ENV_VAR_NAME:=default_value}` syntax to provide defaults
+  - Default values are used when the environment variable is not set
+  - Supports any string as default value, including spaces and special characters
+  - Examples: `${DB_PORT:=5432}`, `${API_URL:=https://api.example.com}`
+- **Session path display in show command**: The `claude-swarm show SESSION_ID` command now displays the session path for easier access to session files
+- **Main process PID tracking**: The orchestrator now writes its process ID to `SESSION_PATH/main_pid` for external monitoring and management
+- **Swarm execution summary**: Display runtime duration and total cost at the end of each swarm run [@claudenm]
+  - Shows total execution time in hours, minutes, and seconds format
+  - Calculates and displays aggregate cost across all instances
+  - Indicates when main instance cost is excluded (e.g., for interactive sessions)
+  - Session metadata now includes end time and duration in seconds
+
+- **Session cost calculator**: New `SessionCostCalculator` class for aggregating costs from session logs [@claudenm]
+  - Processes session.log.json files to calculate total usage costs
+  - Tracks which instances have cost data available
+
+- **Session cost calculator**: New `SessionCostCalculator` class for aggregating costs from session logs
+  - Processes session.log.json files to calculate total usage costs
+  - Tracks which instances have cost data available
+
+- **OpenAI provider support**: Claude Swarm now supports OpenAI models as an alternative provider
+  - Instances can specify `provider: openai` in configuration (default remains "claude")
+  - Full MCP tool support for OpenAI instances via automatic conversion
+  - Mixed provider swarms allow Claude and OpenAI instances to collaborate
+  - OpenAI instances only work with `vibe: true` at the moment. There's no way to set allowed/disallowed tools.
+  
+- **Dual OpenAI API support**: Two API versions available for different use cases
+  - Chat Completion API (`api_version: "chat_completion"`) - Traditional format with tool calling
+  - Responses API (`api_version: "responses"`) - New structured format with function calls
+  - Both APIs support recursive tool execution with proper conversation tracking
+  
+- **OpenAI-specific configuration options**:
+  - `temperature`: Control response randomness (default: 0.3)
+  - `api_version`: Choose between "chat_completion" or "responses" 
+  - `openai_token_env`: Custom environment variable for API key (default: "OPENAI_API_KEY")
+  - `base_url`: Support for OpenAI-compatible endpoints and proxies
+  
+- **Enhanced debugging and logging**:
+  - Detailed error response logging for OpenAI API calls
+  - Conversation flow tracking with IDs for debugging
+  - Full request/response logging in session JSONL files
+
+### Changed
+- Configuration validation now enforces provider-specific fields
+- Example configurations moved from `example/` to `examples/` directory
+- Added `mixed-provider-swarm.yml` example demonstrating Claude-OpenAI collaboration
+- Session metadata now includes `start_time`, `end_time`, and `duration_seconds` fields [@claudenm]
+- Updated `ps` and `show` commands to use the new cost calculation functionality [@claudenm]
+
+
+### Internal
+- New classes: `OpenAIExecutor`, `OpenAIChatCompletion`, `OpenAIResponses`
+- Comprehensive test coverage for OpenAI provider functionality
+- MCP generator enhanced to support provider-specific configurations
+
+## [0.1.20]
+
+### Added
+- **External worktree directory**: Git worktrees are now created in `~/.claude-swarm/worktrees/` for better isolation from the main repository
+  - Prevents conflicts with bundler and other tools
+  - Each unique Git repository gets its own worktree with the same name
+  - Session metadata tracks worktree information for restoration
+- **Zeitwerk autoloading**: Implemented Zeitwerk for better code organization and loading
+
+### Changed
+- **Improved team coordination**: Removed circular dependencies in team configurations
+- **Better code organization**: Refactored code structure to work with Zeitwerk autoloading
+
+### Internal
+- Updated Gemfile.lock to include zeitwerk dependency
+- Added prompt best practices documentation
+
 ## [0.1.19]
 
 ### Added

data/CLAUDE.md

@@ -18,6 +18,23 @@ bin/setup              # Install dependencies
 rake test             # Run the Minitest test suite
 ```
 
+**Important**: Tests should not generate any output to stdout or stderr. When writing tests:
+- Capture or suppress all stdout/stderr output from tested methods
+- Use `capture_io` or `capture_subprocess_io` for Minitest
+- Redirect output streams to `StringIO` or `/dev/null` when necessary
+- Mock or stub methods that produce console output
+- Ensure clean test output for better CI/CD integration
+
+Example:
+```ruby
+def test_command_with_output
+  output, err = capture_io do
+    # Code that produces output
+  end
+  # Test assertions here
+end
+```
+
 ### Linting
 ```bash
 rake rubocop -A       # Run RuboCop linter to auto fix problems
@@ -71,14 +88,15 @@ instances:
 ```
 
 ### Worktree Behavior
-- Worktrees are created inside each repository in a `.worktrees/` directory
-- A `.gitignore` file is automatically created inside `.worktrees/` to ignore all contents
+- Worktrees are created in external directory: `~/.claude-swarm/worktrees/[session_id]/[repo_name-hash]/[worktree_name]`
+- This ensures proper isolation from the main repository and avoids conflicts with bundler and other tools
 - Each unique Git repository gets its own worktree with the same name
 - All instance directories are mapped to their worktree equivalents
 - Worktrees are automatically cleaned up when the swarm exits
 - Session metadata tracks worktree information for restoration
 - Non-Git directories are used as-is without creating worktrees
 - Existing worktrees with the same name are reused
+- The `claude-swarm clean` command removes orphaned worktrees
 
 ## Architecture
 
@@ -151,3 +169,47 @@ The gem includes comprehensive tests covering:
 
 - **thor** (~> 1.3): Command-line interface framework
 - **yaml**: Built-in Ruby YAML parser (no explicit dependency needed)
+
+## Zeitwerk Autoloading
+
+This project uses Zeitwerk for automatic class loading. Important guidelines:
+
+### Require Statement Rules
+
+1. **DO NOT include any require statements for lib files**: Zeitwerk automatically loads all classes under `lib/claude_swarm/`. Never use `require`, `require_relative`, or `require "claude_swarm/..."` for internal project files.
+
+2. **All dependencies must be consolidated in lib/claude_swarm.rb**: Both standard library and external gem dependencies are required at the top of `lib/claude_swarm.rb`. This includes:
+   - Standard library dependencies (json, yaml, fileutils, etc.)
+   - External gem dependencies (thor, openai, mcp_client, fast_mcp_annotations)
+
+3. **No requires in other lib files**: Individual files in `lib/claude_swarm/` should not have any require statements. They rely on:
+   - Dependencies loaded in `lib/claude_swarm.rb`
+   - Other classes autoloaded by Zeitwerk
+
+### Example
+
+```ruby
+# ✅ CORRECT - lib/claude_swarm.rb
+# Standard library dependencies
+require "json"
+require "yaml"
+require "fileutils"
+# ... other standard libraries
+
+# External dependencies
+require "thor"
+require "openai"
+# ... other gems
+
+# Zeitwerk setup
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+# ❌ INCORRECT - lib/claude_swarm/some_class.rb
+require "json"  # Don't do this!
+require_relative "other_class"  # Don't do this!
+require "claude_swarm/configuration"  # Don't do this!
+```
+
+This approach ensures clean dependency management and leverages Ruby's modern autoloading capabilities.

data/README.md

@@ -27,7 +27,13 @@ Claude Swarm orchestrates multiple Claude Code instances as a collaborative AI d
 
 ## Installation
 
-Install the gem by executing:
+Install [Claude CLI](https://docs.anthropic.com/en/docs/claude-code/overview) if you haven't already:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+Install this gem by executing:
 
 ```bash
 gem install claude_swarm
@@ -215,10 +221,70 @@ swarm:
     - "echo 'Setting up environment...'"
     - "npm install"
     - "docker-compose up -d"
+  after:  # Optional: commands to run after exiting the swarm
+    - "echo 'Cleaning up environment...'"
+    - "docker-compose down"
   instances:
     # Instance definitions...
 ```
 
+#### Environment Variable Interpolation
+
+Claude Swarm supports environment variable interpolation in all configuration values using the `${ENV_VAR_NAME}` syntax:
+
+```yaml
+version: 1
+swarm:
+  name: "${APP_NAME} Development Team"
+  main: lead
+  instances:
+    lead:
+      description: "Lead developer for ${APP_NAME}"
+      directory: "${PROJECT_ROOT}"
+      model: "${CLAUDE_MODEL}"
+      prompt: "You are developing ${APP_NAME} version ${APP_VERSION}"
+      allowed_tools: ["${TOOL_1}", "${TOOL_2}", "Bash"]
+      mcps:
+        - name: github
+          type: stdio
+          command: "${MCP_GITHUB_PATH}"
+          env:
+            GITHUB_TOKEN: "${GITHUB_TOKEN}"
+```
+
+Features:
+- Variables are interpolated recursively in strings, arrays, and nested structures
+- Multiple variables can be used in the same string
+- Partial string interpolation is supported (e.g., `"prefix-${VAR}-suffix"`)
+- If a referenced environment variable is not set, Claude Swarm will exit with a clear error message
+- Non-matching patterns like `$VAR` or `{VAR}` are preserved as-is
+
+##### Default Values
+
+Environment variables can have default values using the `${VAR_NAME:=default_value}` syntax:
+
+```yaml
+version: 1
+swarm:
+  name: "Dev Team"
+  main: lead
+  instances:
+    lead:
+      description: "Lead developer"
+      directory: "${PROJECT_DIR:=.}"
+      model: "${CLAUDE_MODEL:=sonnet}"
+      mcps:
+        - name: api-server
+          type: sse
+          url: "${API_URL:=http://localhost:8080}"
+      worktree: "${BRANCH_NAME:=feature-branch}"
+```
+
+- Default values are used when the environment variable is not set
+- Any string can be used as a default value, including spaces and special characters
+- Empty defaults are supported: `${VAR:=}` results in an empty string if VAR is not set
+- Works in all configuration values: strings, arrays, and nested structures
+
 #### Instance Configuration
 
 Each instance must have:
@@ -236,6 +302,24 @@ Each instance can have:
 - **prompt**: Custom system prompt to append to the instance
 - **vibe**: Enable vibe mode (--dangerously-skip-permissions) for this instance (default: false)
 - **worktree**: Configure Git worktree usage for this instance (true/false/string)
+- **provider**: AI provider to use - "claude" (default) or "openai"
+
+#### OpenAI Provider Configuration
+
+When using `provider: openai`, the following additional fields are available:
+
+- **temperature**: Temperature for GPT models only (0.0-2.0). Not supported for O-series reasoning models (o1, o1-preview, o1-mini, o3, etc.)
+- **api_version**: API version to use - "chat_completion" (default) or "responses"
+- **openai_token_env**: Environment variable name for OpenAI API key (default: "OPENAI_API_KEY")
+- **base_url**: Custom base URL for OpenAI API (optional)
+- **reasoning_effort**: Reasoning effort for O-series models only - "low", "medium", or "high"
+
+**Important Notes:**
+- O-series models (o1, o1-preview, o1-mini, o3, etc.) use deterministic reasoning and do not support the `temperature` parameter
+- The `reasoning_effort` parameter is only supported by O-series models
+- GPT models support `temperature` but not `reasoning_effort`
+- OpenAI instances default to and ONLY operate as `vibe: true` and use MCP for tool access
+- By default it comes with Claude Code tools, connected with MCP to `claude mcp serve`
 
 ```yaml
 instance_name:
@@ -262,6 +346,27 @@ instance_name:
       args: ["arg1", "arg2"]
       env:
         VAR1: value1
+
+# OpenAI instance examples
+
+# GPT model with temperature
+gpt_instance:
+  description: "OpenAI GPT-powered creative assistant"
+  provider: openai
+  model: gpt-4o
+  temperature: 0.7  # Supported for GPT models
+  api_version: chat_completion
+  openai_token_env: OPENAI_API_KEY
+  prompt: "You are a creative assistant specializing in content generation"
+
+# O-series reasoning model with reasoning_effort
+reasoning_instance:
+  description: "OpenAI O-series reasoning assistant"
+  provider: openai
+  model: o1-mini
+  reasoning_effort: medium  # Only for O-series models
+  api_version: responses    # Can use either API version
+  prompt: "You are a reasoning assistant for complex problem solving"
 ```
 
 ### MCP Server Types
@@ -453,9 +558,54 @@ When using multiple directories:
 - Additional directories are accessible via the `--add-dir` flag in Claude
 - All directories must exist or the configuration will fail validation
 
-#### Before Commands
+#### Mixed AI Provider Team
+
+Combine Claude and OpenAI instances in a single swarm:
+
+```yaml
+version: 1
+swarm:
+  name: "Mixed AI Development Team"
+  main: lead_developer
+  instances:
+    lead_developer:
+      description: "Claude lead developer coordinating the team"
+      directory: .
+      model: opus
+      connections: [creative_assistant, reasoning_expert, backend_dev]
+      prompt: "You are the lead developer coordinating a mixed AI team"
+      allowed_tools: [Read, Edit, Bash, Write]
+      
+    creative_assistant:
+      description: "OpenAI-powered assistant for creative and UI/UX tasks"
+      provider: openai
+      model: gpt-4o
+      temperature: 0.7  # Supported for GPT models
+      directory: ./frontend
+      prompt: "You are a creative frontend developer specializing in UI/UX design"
+      # OpenAI instances default to vibe: true
+      
+    reasoning_expert:
+      description: "OpenAI O-series model for complex problem solving"
+      provider: openai
+      model: o1-mini
+      reasoning_effort: high  # For O-series models only
+      directory: ./architecture
+      prompt: "You solve complex architectural and algorithmic problems"
+      
+    backend_dev:
+      description: "Claude backend developer for system architecture"
+      directory: ./backend
+      model: sonnet
+      prompt: "You specialize in backend development and system architecture"
+      allowed_tools: [Read, Edit, Write, Bash]
+```
+
+Note: OpenAI instances require the API key to be set in the environment variable (default: `OPENAI_API_KEY`).
 
-You can specify commands to run before launching the swarm using the `before` field:
+#### Before and After Commands
+
+You can specify commands to run before launching and after exiting the swarm using the `before` and `after` fields:
 
 ```yaml
 version: 1
@@ -467,6 +617,10 @@ swarm:
     - "npm install"
     - "docker-compose up -d"
     - "bundle install"
+  after:
+    - "echo '🛑 Cleaning up development environment...'"
+    - "docker-compose down"
+    - "rm -rf temp/*"
   instances:
     lead_developer:
       description: "Lead developer coordinating the team"
@@ -477,16 +631,26 @@ swarm:
 
 The `before` commands:
 - Are executed in sequence before launching any Claude instances
+- Execute in the main instance's directory (including worktree if enabled)
 - Must all succeed for the swarm to launch (exit code 0)
 - Are only executed on initial swarm launch, not when restoring sessions
 - Have their output logged to the session log file
 - Will abort the swarm launch if any command fails
 
+The `after` commands:
+- Are executed after Claude exits but before cleanup processes
+- Execute in the main instance's directory (including worktree if enabled)
+- Run even when the swarm is interrupted by signals (Ctrl+C)
+- Failures do not prevent cleanup from proceeding
+- Are only executed on initial swarm runs, not when restoring sessions
+- Have their output logged to the session log file
+
 This is useful for:
-- Installing dependencies
+- Installing dependencies in the isolated worktree environment
 - Starting required services (databases, Docker containers, etc.)
 - Setting up the development environment
 - Running any prerequisite setup scripts
+- Ensuring setup commands affect only the working directory, not the original repository
 
 
 #### Mixed Permission Modes
@@ -522,17 +686,16 @@ swarm:
 
 #### Git Worktrees
 
-Claude Swarm supports running instances in Git worktrees, allowing isolated work without affecting your main repository state. Worktrees are created inside each repository in a `.worktrees/` directory following Git best practices.
+Claude Swarm supports running instances in Git worktrees, allowing isolated work without affecting your main repository state. Worktrees are created in an external directory (`~/.claude-swarm/worktrees/`) to ensure proper isolation from the main repository and avoid conflicts with bundler and other tools.
 
 **Example Structure:**
 ```
-my-repo/
-├── .git/
-├── .worktrees/        (created by Claude Swarm)
-│   ├── .gitignore     (auto-created, contains "*")
-│   └── feature-x/     (worktree for feature-x branch)
-├── src/
-└── tests/
+~/.claude-swarm/worktrees/
+└── [session_id]/
+    ├── my-repo-[hash]/
+    │   └── feature-x/     (worktree for feature-x branch)
+    └── other-repo-[hash]/
+        └── feature-x/     (worktree for feature-x branch)
 ```
 
 **CLI Option:**
@@ -577,14 +740,14 @@ swarm:
 - Omitted - Follows CLI behavior (use worktree if `--worktree` is specified)
 
 **Notes:**
-- Worktrees are created inside each repository in a `.worktrees/` directory
 - Auto-generated worktree names use the session ID (e.g., `worktree-20241206_143022`)
 - This makes it easy to correlate worktrees with their Claude Swarm sessions
-- A `.gitignore` file is automatically created inside `.worktrees/` to ignore all worktree contents
+- Worktrees are stored externally in `~/.claude-swarm/worktrees/[session_id]/`
 - All worktrees are automatically cleaned up when the swarm exits
 - Worktrees with the same name across different repositories share that name
 - Non-Git directories are unaffected by worktree settings
 - Existing worktrees with the same name are reused
+- The `claude-swarm clean` command also removes orphaned worktrees
 
 ### Command Line Options
 
@@ -593,8 +756,8 @@ swarm:
 claude-swarm
 
 # Specify a different configuration file
-claude-swarm --config my-swarm.yml
-claude-swarm -c team-config.yml
+claude-swarm my-swarm.yml
+claude-swarm team-config.yml
 
 # Run with --dangerously-skip-permissions for all instances
 claude-swarm --vibe
@@ -603,9 +766,11 @@ 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
+# Use a custom session ID instead of auto-generated UUID
+claude-swarm --session-id my-custom-session-123
+
+# Stream logs to stdout in prompt mode
+claude-swarm -p "Fix the tests" --stream-logs
 
 # Run all instances in Git worktrees
 claude-swarm --worktree                  # Auto-generated name (worktree-SESSION_ID)
@@ -652,10 +817,10 @@ claude-swarm watch 20250617_235233 -n 50
 claude-swarm list-sessions
 claude-swarm list-sessions --limit 20
 
-# Clean up stale session symlinks
+# Clean up stale session symlinks and orphaned worktrees
 claude-swarm clean
 
-# Remove sessions older than 30 days
+# Remove sessions and worktrees older than 30 days
 claude-swarm clean --days 30
 ```
 
@@ -666,7 +831,7 @@ Example output from `claude-swarm ps`:
 SESSION_ID       SWARM_NAME                 TOTAL_COST    UPTIME      DIRECTORY
 -------------------------------------------------------------------------------
 20250617_235233  Feature Development        $0.3847       15m         .
-20250617_143022  Bug Investigation          $1.2156       1h          ./shopify
+20250617_143022  Bug Investigation          $1.2156       1h          .
 20250617_091547  Multi-Module Dev           $0.8932       30m         ./frontend, ./backend, ./shared
 ```
 
@@ -729,11 +894,8 @@ Output shows:
 Resume a previous session with all instances restored to their Claude session states:
 
 ```bash
-# Resume by session ID
-claude-swarm --session-id 20250617_143022
-
-# Resume by full path
-claude-swarm --session-id ~/.claude-swarm/sessions/my-project/20250617_143022
+# Restore using the session's UUID
+claude-swarm restore 550e8400-e29b-41d4-a716-446655440000
 ```
 
 This will:
@@ -805,7 +967,7 @@ The swarm will display:
 
 ### Session Files
 
-Check the session directory `~/.claude-swarm/sessions/{project}/{timestamp}/` for:
+Check the session directory `~/.claude-swarm/sessions/{project}/{session-id}/` 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

data/Rakefile

@@ -9,4 +9,4 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+task default: [:test, :rubocop]

data/examples/mixed-provider-swarm.yml

@@ -0,0 +1,23 @@
+version: 1
+swarm:
+  name: "Mixed AI Team"
+  main: lead_developer
+  instances:
+    lead_developer:
+      description: "Claude lead developer coordinating the team"
+      directory: .
+      model: opus
+      prompt: "You are the lead developer coordinating a mixed AI team"
+      allowed_tools: [Read, Edit, Bash, Write]
+      connections: [openai_assistant]
+      
+    openai_assistant:
+      description: "OpenAI-powered assistant for creative tasks"
+      directory: .
+      provider: openai
+      model: o3
+      api_version: responses
+      reasoning_effort: high  # Optional: low, medium, or high
+      prompt: "You are a creative frontend developer using React and modern web technologies"
+      # OpenAI instances default to vibe: true
+