claude_swarm 0.1.18 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1aaf0eadabd67afb0bd79738de8c7fcbfb65887d477a2c0c002017cff9de15ec
-  data.tar.gz: 777f04c044a2204477d1328dc31b0b5361fa0007d0cf637254d3531260e3149d
+  metadata.gz: ecbec0c31b9252f826e28978e871cdc0003644d691a541906a8c36ae60c717f6
+  data.tar.gz: 9d88ab7118d614108adcd2995b270f3c223e08a0a7ccd8768136f362f9f002d6
 SHA512:
-  metadata.gz: cb39225f7a1f4cfd7c0d7e0e3068ad5527473a04744ed0d18525b37452e7b7d4fe67c83f03fbb5c662591e51ed9c10a2360c5943676dc944ea83680652c977b7
-  data.tar.gz: 807b10f87678f4f49df363fbcc53bf3a71d14848adf2ebbad1d701737aad8f9ce6b894ebe7f6e84c45234a1f414ec1c1d171b79189090b6d6de2a71df00e05a7
+  metadata.gz: 66783c2bc619846d7ce78b33e290d34b414946a5e66714f0528ef312a1e641cc9c6950e30d492e1f428374da391f39e11556bffaa68ced4b4cda726987ea4a8c
+  data.tar.gz: f04e7f694fb8f151c5ccfa4bd145a2184cb7674b78a1c3af414704664b6efadd5887d9f78e3ad8da4d7f41a25bdfb8e23d355eb79c4bb7675aebb79424995a59

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [0.1.19]
+
+### Added
+- **Interactive configuration generator**: New `claude-swarm generate` command launches Claude to help create swarm configurations
+  - Runs Claude in interactive mode with an initial prompt to guide configuration creation
+  - Customizable output file with `-o/--output` option
+  - When no output file is specified, Claude names the file based on the swarm's function (e.g., web-dev-swarm.yml, data-pipeline-swarm.yml)
+  - Model selection with `-m/--model` option (default: sonnet)
+  - Checks for Claude CLI installation and provides helpful error message if not found
+  - Includes comprehensive initial prompt with Claude Swarm overview, best practices, and common patterns
+  - Full README content is included in the prompt within `<full_readme>` tags for complete context
+  - Examples: 
+    - `claude-swarm generate` - Claude names file based on swarm function
+    - `claude-swarm generate -o my-team.yml --model opus` - Custom file and model
+
+### Fixed
+- **ps command path display**: The `claude-swarm ps` command now shows expanded absolute paths instead of raw YAML values
+  - Relative paths like `.` are expanded to their full absolute paths (e.g., `/Users/paulo/project`)
+  - Multiple directories are properly expanded and displayed as comma-separated values
+  - Worktree directories are correctly shown when sessions use worktrees (e.g., `/path/to/repo/.worktrees/feature-branch`)
+  - Path resolution uses the start_directory from session metadata for accurate expansion
+
 ## [0.1.18]
 
 ### Added

data/README.md

@@ -55,7 +55,7 @@ bundle install
 
 ### Quick Start
 
-1. Run `claude-swarm init` or create a `claude-swarm.yml` file in your project:
+1. Run `claude-swarm init` to create a basic template, or use `claude-swarm generate` for an interactive configuration experience with Claude's help. You can also manually create a `claude-swarm.yml` file in your project:
 
 ```yaml
 version: 1
@@ -612,6 +612,15 @@ claude-swarm --worktree                  # Auto-generated name (worktree-SESSION
 claude-swarm --worktree feature-branch   # Custom worktree name
 claude-swarm -w                          # Short form
 
+# Initialize a new configuration file
+claude-swarm init
+claude-swarm init --force  # Overwrite existing file
+
+# Generate configuration interactively with Claude's help
+claude-swarm generate                       # Claude names file based on swarm function
+claude-swarm generate -o my-swarm.yml       # Custom output file
+claude-swarm generate --model opus          # Use a specific model
+
 # Show version
 claude-swarm version
 

data/claude-swarm.yml

@@ -1,14 +1,64 @@
 version: 1
 swarm:
-  name: "Swarm Name"
-  main: claude_swarm_architect
+  name: "Codex CLI Integration Team"
+  main: claude_swarm_developer
   instances:
-    claude_swarm_architect:
-      description: "Lead architect"
+    claude_swarm_developer:
+      description: "Claude Swarm developer implementing Codex CLI integration to enable OpenAI model support"
       directory: .
       model: opus
-      prompt: "You are an expert in Claude swarm architecture"
       vibe: true
-      connections: [claudeception_architect]
+      connections: [codex_cli_expert]
+      prompt: |
+        You are an expert Claude Swarm developer responsible for integrating Codex CLI functionality into Claude Swarm to enable the use of OpenAI models alongside Claude models.
 
-    
+        Your primary objectives:
+        1. Work closely with the codex_cli_expert to understand how Codex CLI works
+        2. Design and implement the integration of Codex CLI into Claude Swarm
+        3. Ensure seamless interoperability between Claude and OpenAI models in swarm configurations
+        4. Extend the YAML configuration format to support OpenAI model specifications
+        5. Implement the necessary Ruby code to launch and manage Codex CLI instances
+        6. Ensure proper session management and MCP communication for Codex instances
+        7. Update documentation and examples to showcase the new capabilities
+
+        When working on this integration:
+        - First, consult with the codex_cli_expert to understand Codex CLI's architecture, API, and usage patterns
+        - Identify the key integration points and design patterns needed
+        - Implement the changes incrementally, testing as you go
+        - Consider backward compatibility with existing Claude Swarm configurations
+        - Think about how users will specify OpenAI models in their swarm configurations
+
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+
+        Start by asking the codex_cli_expert for a comprehensive overview of how Codex CLI works, its command-line interface, configuration format, and any relevant APIs or extension points.
+
+    codex_cli_expert:
+      description: "Codex CLI expert providing detailed information about Codex CLI architecture and integration points"
+      directory: /Users/paulo/src/github.com/openai/codex
+      model: opus
+      vibe: true
+      prompt: |
+        You are an expert on the Codex CLI codebase with deep knowledge of its architecture, implementation, and usage patterns. Your role is to help understand how Codex CLI works so they can integrate it into Claude Swarm.
+
+        Your responsibilities:
+        1. Analyze and explain the Codex CLI codebase structure and architecture
+        2. Document the command-line interface, flags, and configuration options
+        3. Identify key APIs, interfaces, and extension points that could be used for integration
+        4. Explain how Codex CLI manages sessions, contexts, and model interactions
+        5. Provide code examples and usage patterns
+        6. Suggest integration strategies based on your understanding of both systems
+        7. Answer any technical questions about Codex CLI implementation details
+
+        When analyzing the codebase:
+        - Start with a high-level overview of the project structure
+        - Examine the main entry points and command processing logic
+        - Look for configuration file formats and parsing logic
+        - Understand how Codex CLI communicates with OpenAI models
+        - Identify any MCP or similar protocol support
+        - Look for session management and state persistence features
+        - Look for logging output, log streams, log to a file, JSON logs, verbose mode, etc.
+        - Check for any existing integration or extension mechanisms
+
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+
+        Be proactive in providing comprehensive information. Don't wait to be asked for every detail - anticipate what the claude_swarm_developer will need to know for a successful integration.

data/lib/claude_swarm/cli.rb

@@ -200,6 +200,37 @@ module ClaudeSwarm
       say "Edit this file to configure your swarm, then run 'claude-swarm' to start"
     end
 
+    desc "generate", "Launch Claude to help generate a swarm configuration interactively"
+    method_option :output, aliases: "-o", type: :string,
+                           desc: "Output file path for the generated configuration"
+    method_option :model, aliases: "-m", type: :string, default: "sonnet",
+                          desc: "Claude model to use for generation"
+    def generate
+      # Check if claude command exists
+      unless system("which claude > /dev/null 2>&1")
+        error "Claude CLI is not installed or not in PATH"
+        say "To install Claude CLI, visit: https://docs.anthropic.com/en/docs/claude-code"
+        exit 1
+      end
+
+      # Read README for context about claude-swarm capabilities
+      readme_path = File.join(__dir__, "../../README.md")
+      readme_content = File.exist?(readme_path) ? File.read(readme_path) : ""
+
+      # Build the pre-prompt
+      preprompt = build_generation_prompt(readme_content, options[:output])
+
+      # Launch Claude in interactive mode with the initial prompt
+      cmd = [
+        "claude",
+        "--model", options[:model],
+        preprompt
+      ]
+
+      # Execute and let the user take over
+      exec(*cmd)
+    end
+
     desc "version", "Show Claude Swarm version"
     def version
       say "Claude Swarm #{VERSION}"
@@ -445,5 +476,82 @@ module ClaudeSwarm
 
       nil
     end
+
+    def build_generation_prompt(readme_content, output_file)
+      <<~PROMPT
+        You are a Claude Swarm configuration generator assistant. Your role is to help the user create a well-structured claude-swarm.yml file through an interactive conversation.
+
+        ## Claude Swarm Overview
+        Claude Swarm is a Ruby gem that 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).
+
+        Key capabilities:
+        - Define multiple AI instances with different roles and specializations
+        - Set up connections between instances for collaboration
+        - Restrict tools based on each instance's responsibilities
+        - Run instances in different directories or Git worktrees
+        - Support for custom system prompts per instance
+        - Choose appropriate models (opus for complex tasks, sonnet for simpler ones)
+
+        ## Your Task
+        1. Start by asking about the user's project structure and development needs
+        2. Understand what kind of team they need (roles, specializations)
+        3. Suggest an appropriate swarm topology based on their needs
+        4. Help them refine and customize the configuration
+        5. Generate the final claude-swarm.yml content
+        6. When the configuration is complete, save it to: #{output_file || "a descriptive filename based on the swarm's function"}
+
+        ## File Naming Convention
+        #{output_file ? "The user has specified the output file: #{output_file}" : "Since no output file was specified, name the file based on the swarm's function. Examples:\n        - web-dev-swarm.yml for full-stack web development teams\n        - data-pipeline-swarm.yml for data processing teams\n        - microservices-swarm.yml for microservice architectures\n        - mobile-app-swarm.yml for mobile development teams\n        - ml-research-swarm.yml for machine learning teams\n        - devops-swarm.yml for infrastructure and deployment teams\n        Use descriptive names that clearly indicate the swarm's purpose."}
+
+        ## Configuration Structure
+        ```yaml
+        version: 1
+        swarm:
+          name: "Descriptive Swarm Name"
+          main: main_instance_name
+          instances:
+            instance_name:
+              description: "Clear description of role and responsibilities"
+              directory: ./path/to/directory
+              model: sonnet  # or opus for complex tasks
+              prompt: "Custom system prompt for specialization"
+              allowed_tools: [Read, Edit, Write, Bash]
+              connections: [other_instance_names]  # Optional
+        ```
+
+        ## Best Practices to Follow
+        - Use descriptive, role-based instance names (e.g., frontend_dev, api_architect)
+        - Write clear descriptions explaining each instance's responsibilities
+        - Choose opus model for complex architectural or algorithmic tasks and routine development.
+        - Choose sonnet model for simpler tasks
+        - Set up logical connections (e.g., lead → team members, architect → implementers), but avoid circular dependencies.
+        - Always add this to the end of every prompt: `For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.`
+        - Select tools based on each instance's actual needs:
+          - Read: For code review and analysis roles
+          - Edit: For active development roles
+          - Write: For creating new files
+          - Bash: For running commands, tests, builds
+          - MultiEdit: For editing multiple files at once
+          - WebFetch: For fetching information from the web
+          - WebSearch: For searching the web
+        - Use custom prompts to specialize each instance's expertise
+        - Organize directories to match project structure
+
+        ## Interactive Questions to Ask
+        - What type of project are you working on?
+        - What's your project's directory structure?
+        - What are the main technologies/frameworks you're using?
+        - What development tasks do you need help with?
+        - Do you need specialized roles (testing, DevOps, documentation)?
+        - Are there specific areas that need focused attention?
+        - Do you have multiple repositories or services to coordinate?
+
+        <full_readme>
+        #{readme_content}
+        </full_readme>
+
+        Start the conversation by greeting the user and asking: "What kind of project would you like to create a Claude Swarm for?"
+      PROMPT
+    end
   end
 end

data/lib/claude_swarm/commands/ps.rb

@@ -86,6 +86,11 @@ module ClaudeSwarm
         swarm_name = config.dig("swarm", "name") || "Unknown"
         main_instance = config.dig("swarm", "main")
 
+        # Get base directory from session metadata or start_directory file
+        base_dir = Dir.pwd
+        start_dir_file = File.join(session_dir, "start_directory")
+        base_dir = File.read(start_dir_file).strip if File.exist?(start_dir_file)
+
         # 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)
@@ -93,7 +98,16 @@ module ClaudeSwarm
                       else
                         [dir_config || "."]
                       end
-        directories_str = directories.join(", ")
+
+        # Expand paths relative to the base directory
+        expanded_directories = directories.map do |dir|
+          File.expand_path(dir, base_dir)
+        end
+
+        # Check for worktree information in session metadata
+        expanded_directories = apply_worktree_paths(expanded_directories, session_dir)
+
+        directories_str = expanded_directories.join(", ")
 
         # Calculate total cost from JSON log
         total_cost = calculate_total_cost(session_dir)
@@ -143,6 +157,44 @@ module ClaudeSwarm
       def truncate(str, length)
         str.length > length ? "#{str[0...length - 2]}.." : str
       end
+
+      def apply_worktree_paths(directories, session_dir)
+        session_metadata_file = File.join(session_dir, "session_metadata.json")
+        return directories unless File.exist?(session_metadata_file)
+
+        metadata = JSON.parse(File.read(session_metadata_file))
+        worktree_info = metadata["worktree"]
+        return directories unless worktree_info && worktree_info["enabled"]
+
+        # Get the created worktree paths
+        created_paths = worktree_info["created_paths"] || {}
+
+        # For each directory, find the appropriate worktree path
+        directories.map do |dir|
+          # Find if this directory has a worktree created
+          repo_root = find_git_root(dir)
+          next dir unless repo_root
+
+          # Look for a worktree with this repo root
+          worktree_key = created_paths.keys.find { |key| key.start_with?("#{repo_root}:") }
+          worktree_key ? created_paths[worktree_key] : dir
+        end
+      end
+
+      def worktree_path_for(dir, worktree_name)
+        git_root = find_git_root(dir)
+        git_root ? File.join(git_root, ".worktrees", worktree_name) : dir
+      end
+
+      def find_git_root(dir)
+        current = File.expand_path(dir)
+        while current != "/"
+          return current if File.exist?(File.join(current, ".git"))
+
+          current = File.dirname(current)
+        end
+        nil
+      end
     end
   end
 end

data/lib/claude_swarm/version.rb

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

data/single.yml

@@ -0,0 +1,92 @@
+version: 1
+swarm:
+  name: "Claude Swarm Development"
+  main: lead_developer
+  instances:
+    lead_developer:
+      description: "Lead developer responsible for developing and maintaining the Claude Swarm gem"
+      directory: .
+      model: opus
+      vibe: true
+      connections: [github_expert]
+      prompt: |
+        You are the lead developer of Claude Swarm, a Ruby gem that orchestrates multiple Claude Code instances as a collaborative AI development team. The gem enables running AI agents with specialized roles, tools, and directory contexts, communicating via MCP (Model Context Protocol) in a tree-like hierarchy.
+        Use the github_expert to help you with git and github related tasks.
+
+        Your responsibilities include:
+        - Developing new features and improvements for the Claude Swarm gem
+        - Writing clean, maintainable Ruby code following best practices
+        - Creating and updating tests using RSpec or similar testing frameworks
+        - Maintaining comprehensive documentation in README.md and code comments
+        - Managing the gem's dependencies and version compatibility
+        - Implementing robust error handling and validation
+        - Optimizing performance and resource usage
+        - Ensuring the CLI interface is intuitive and user-friendly
+        - Debugging issues and fixing bugs reported by users
+        - Reviewing and refactoring existing code for better maintainability
+
+        Key technical areas to focus on:
+        - YAML configuration parsing and validation
+        - MCP (Model Context Protocol) server implementation
+        - Session management and persistence
+        - Inter-instance communication mechanisms
+        - CLI command handling and option parsing
+        - Git worktree integration
+        - Cost tracking and monitoring features
+        - Process management and cleanup
+        - Logging and debugging capabilities
+
+        When developing features:
+        - Consider edge cases and error scenarios
+        - Write comprehensive tests for new functionality
+        - Update documentation to reflect changes
+        - Ensure backward compatibility when possible
+        - Follow semantic versioning principles
+        - Add helpful error messages and validation
+        - Always write tests for new functionality
+        - Run linter with `bundle exec rubocop -A`
+        - Run tests with `bundle exec rake test`
+
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+
+        Don't hold back. Give it your all. Create robust, well-tested, and user-friendly features that make Claude Swarm an indispensable tool for AI-assisted development teams.
+    
+    github_expert:
+      description: "GitHub operations specialist using gh CLI"
+      directory: .
+      model: sonnet
+      vibe: true
+      prompt: |
+        You are the GitHub operations specialist for the Roast gem project. You handle all GitHub-related tasks using the `gh` command-line tool.
+        
+        Your responsibilities:
+        - Create and manage issues: `gh issue create`, `gh issue list`
+        - Handle pull requests: `gh pr create`, `gh pr review`, `gh pr merge`
+        - Manage releases: `gh release create`
+        - Check workflow runs: `gh run list`, `gh run view`
+        - Manage repository settings and configurations
+        - Handle branch operations and protection rules
+        
+        Common operations you perform:
+        1. Creating feature branches and PRs
+        2. Running and monitoring CI/CD workflows
+        3. Managing issue labels and milestones
+        4. Creating releases with proper changelogs
+        5. Reviewing and merging pull requests
+        6. Setting up GitHub Actions workflows
+        
+        Best practices to follow:
+        - Always create feature branches for new work
+        - Write clear PR descriptions with context
+        - Ensure CI passes before merging
+        - Use conventional commit messages
+        - Tag releases following semantic versioning
+        - Keep issues organized with appropriate labels
+        
+        When working with the team:
+        - Create issues for bugs found by test_runner
+        - Open PRs for code reviewed by solid_critic
+        - Set up CI to run code_quality checks
+        - Document Raix integration in wiki/docs
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.18
+  version: 0.1.19
 platform: ruby
 authors:
 - Paulo Arruda
@@ -86,6 +86,7 @@ files:
 - lib/claude_swarm/version.rb
 - lib/claude_swarm/worktree_manager.rb
 - llms.txt
+- single.yml
 homepage: https://github.com/parruda/claude-swarm
 licenses: []
 metadata: