claude_swarm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d905c9233bd290f36581e1507efcfb081c4c06e25182d84cf7fc1aa5fd167468
+  data.tar.gz: 666090b2014f5b451cb264bf4bffc658a6d543e1d4e074e7ccb0f9ab03e44327
+SHA512:
+  metadata.gz: 6dd8b14d36a9ae772be13170fa28c30e85a93a02b5bfe6793294eca51d34520e02dc9d1ddefd5312cb2682472e6bcaa7dcb36213d28d6adf0b08852889117f36
+  data.tar.gz: d1762b2fd34da13e3262ebf82e3fd3576844c2487154c8b68a35f7e9ff270e96fa61f19a83e8488a8a2f630c96f6a61d78e827b352062cd695d5c656b06b9ca0

data/.rubocop.yml

@@ -0,0 +1,62 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+
+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

data/.ruby-version

@@ -0,0 +1 @@
+ruby-3.4.2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-05-24
+
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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).
+
+## Development Commands
+
+### Setup
+```bash
+bin/setup              # Install dependencies
+```
+
+### Testing
+```bash
+rake test             # Run the Minitest test suite
+```
+
+### Linting
+```bash
+rake rubocop -A       # Run RuboCop linter to auto fix problems
+```
+
+### Development Console
+```bash
+bin/console           # Start IRB session with gem loaded
+```
+
+### Build & Release
+```bash
+bundle exec rake install    # Install gem locally
+bundle exec rake release    # Release gem to RubyGems.org
+```
+
+### Default Task
+```bash
+rake                  # Runs both tests and RuboCop
+```
+
+## Architecture
+
+The gem is fully implemented with the following components:
+
+### Core Classes
+
+- **ClaudeSwarm::CLI** (`lib/claude_swarm/cli.rb`): Thor-based CLI that handles command parsing and orchestration
+- **ClaudeSwarm::Configuration** (`lib/claude_swarm/configuration.rb`): YAML parser and validator for swarm configurations
+- **ClaudeSwarm::McpGenerator** (`lib/claude_swarm/mcp_generator.rb`): Generates MCP JSON configurations for each instance
+- **ClaudeSwarm::Orchestrator** (`lib/claude_swarm/orchestrator.rb`): Launches the main Claude instance with proper configuration
+
+### Key Features
+
+1. **YAML Configuration**: Define swarms with instances, connections, tools, and MCP servers
+2. **Inter-Instance Communication**: Instances connect via MCP using `claude mcp serve` with `-p` flag
+3. **Tool Restrictions**: Support for pattern-based tool restrictions (e.g., `Bash(npm:*)`)
+4. **Multiple MCP Types**: Supports both stdio and SSE MCP server types
+5. **Automatic MCP Generation**: Creates `.claude-swarm/` directory with MCP configs
+6. **Custom System Prompts**: Each instance can have a custom prompt via `--append-system-prompt`
+
+### How It Works
+
+1. User creates a `claude-swarm.yml` file defining the swarm topology
+2. Running `claude-swarm` parses the configuration and validates it
+3. MCP configuration files are generated for each instance in `.claude-swarm/`
+4. The main instance is launched with `exec`, replacing the current process
+5. Connected instances are available as MCP servers to the main instance
+
+### Configuration Example
+
+```yaml
+version: 1
+swarm:
+  name: "Dev Team"
+  main: lead
+  instances:
+    lead:
+      role: "Lead Developer"
+      directory: .
+      model: opus
+      connections: [frontend, backend]
+      prompt: "You are the lead developer coordinating the team"
+      tools: [Read, Edit, Bash]
+    frontend:
+      role: "Frontend Developer"
+      directory: ./frontend
+      model: sonnet
+      prompt: "You specialize in frontend development with React"
+      tools: [Edit, Write, "Bash(npm:*)"]
+```
+
+## Testing
+
+The gem includes basic tests for version number and CLI existence. Additional tests should be added for:
+- Configuration parsing and validation
+- MCP generation logic
+- Error handling scenarios
+
+## Dependencies
+
+- **thor** (~> 1.3): Command-line interface framework
+- **yaml**: Built-in Ruby YAML parser (no explicit dependency needed)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Paulo Arruda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,391 @@
+# Claude Swarm
+
+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). Define your swarm topology in simple YAML and let Claude instances collaborate across codebases. Perfect for complex projects requiring specialized AI agents for frontend, backend, testing, DevOps, or research tasks.
+
+## Installation
+
+Install the gem by executing:
+
+```bash
+gem install claude_swarm
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem 'claude_swarm'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Prerequisites
+
+- Ruby 3.1.0 or higher
+- Claude CLI installed and configured
+- Any MCP servers you plan to use (optional)
+
+## Usage
+
+### Quick Start
+
+1. Create a `claude-swarm.yml` file in your project:
+
+```yaml
+version: 1
+swarm:
+  name: "My Dev Team"
+  main: lead
+  instances:
+    lead:
+      role: "Lead Developer"
+      directory: .
+      model: opus
+      connections: [frontend, backend]
+      tools:
+        - Read
+        - Edit
+        - Bash
+    frontend:
+      role: "Frontend Developer" 
+      directory: ./frontend
+      model: sonnet
+      tools:
+        - Edit
+        - Write
+        - Bash
+    backend:
+      role: "Backend Developer"
+      directory: ./backend  
+      model: sonnet
+      tools:
+        - Edit
+        - Write
+        - Bash
+```
+
+2. Start the swarm:
+
+```bash
+claude-swarm
+```
+
+This will:
+- Generate MCP configuration files in `.claude-swarm/`
+- Create a shared session timestamp for centralized logging
+- Launch the main instance (lead) with connections to other instances
+- The lead instance can communicate with frontend and backend instances via MCP
+- All instances log to `.claude-swarm/logs/session-{timestamp}/`
+
+### Configuration Format
+
+#### Top Level
+
+```yaml
+version: 1  # Required, currently only version 1 is supported
+swarm:
+  name: "Swarm Name"  # Display name for your swarm
+  main: instance_key  # Which instance to launch as the main interface
+  instances:
+    # Instance definitions...
+```
+
+#### Instance Configuration
+
+Each instance can have:
+
+- **role**: Human-readable role description (defaults to instance name)
+- **directory**: Working directory for this instance (can use ~ for home)
+- **model**: Claude model to use (opus, sonnet, haiku)
+- **connections**: Array of other instances this one can communicate with
+- **tools**: Array of tools this instance can use
+- **mcps**: Array of additional MCP servers to connect
+- **prompt**: Custom system prompt to append to the instance
+
+```yaml
+instance_name:
+  role: "Role Description"
+  directory: ~/project/path
+  model: opus
+  connections: [other_instance1, other_instance2]
+  prompt: "You are a specialized agent focused on..."
+  tools:
+    - Read
+    - Edit
+    - Write
+    - Bash
+    - WebFetch
+    - WebSearch
+  mcps:
+    - name: server_name
+      type: stdio
+      command: command_to_run
+      args: ["arg1", "arg2"]
+      env:
+        VAR1: value1
+```
+
+### MCP Server Types
+
+#### stdio (Standard I/O)
+```yaml
+mcps:
+  - name: my_tool
+    type: stdio
+    command: /path/to/executable
+    args: ["--flag", "value"]
+    env:
+      API_KEY: "secret"
+```
+
+#### sse (Server-Sent Events)
+```yaml
+mcps:
+  - name: remote_api
+    type: sse
+    url: "https://api.example.com/mcp"
+```
+
+### Tools
+
+Specify which tools each instance can use:
+
+```yaml
+tools:
+  - Bash           # Command execution
+  - Edit           # File editing
+  - Write          # File creation
+  - Read           # File reading
+  - WebFetch       # Fetch web content
+  - WebSearch      # Search the web
+```
+
+Tools are passed to Claude using the `--allowedTools` flag with comma-separated values.
+
+#### Tool Restrictions
+
+You can restrict tools with pattern-based filters:
+
+```yaml
+tools:
+  - Read                    # Unrestricted read access
+  - Edit                    # Unrestricted edit access
+  - "Bash(npm:*)"          # Only allow npm commands
+  - "Bash(git:*, make:*)"  # Only allow git and make commands
+```
+
+### Examples
+
+#### Full Stack Development Team
+
+```yaml
+version: 1
+swarm:
+  name: "Full Stack Team"
+  main: architect
+  instances:
+    architect:
+      role: "Software Architect"
+      directory: .
+      model: opus
+      connections: [frontend, backend, devops]
+      prompt: "You are the lead architect responsible for system design and code quality"
+      tools:
+        - Read
+        - Edit
+        - WebSearch
+        
+    frontend:
+      role: "Frontend Developer"
+      directory: ./frontend
+      model: sonnet
+      connections: [architect]
+      prompt: "You specialize in React, TypeScript, and modern frontend development"
+      tools:
+        - Edit
+        - Write
+        - Bash
+        
+    backend:
+      role: "Backend Developer"
+      directory: ./backend
+      model: sonnet
+      connections: [architect, database]
+      tools:
+        - Edit
+        - Write
+        - Bash
+        
+    database:
+      role: "Database Administrator"
+      directory: ./db
+      model: haiku
+      tools:
+        - Read
+        - Bash
+        
+    devops:
+      role: "DevOps Engineer"
+      directory: .
+      model: sonnet
+      connections: [architect]
+      tools:
+        - Read
+        - Edit
+        - Bash
+```
+
+#### Research Team with External Tools
+
+```yaml
+version: 1
+swarm:
+  name: "Research Team"
+  main: lead_researcher
+  instances:
+    lead_researcher:
+      role: "Lead Researcher"
+      directory: ~/research
+      model: opus
+      connections: [data_analyst, writer]
+      tools:
+        - Read
+        - WebSearch
+        - WebFetch
+      mcps:
+        - name: arxiv
+          type: sse
+          url: "https://arxiv-mcp.example.com"
+          
+    data_analyst:
+      role: "Data Analyst"
+      directory: ~/research/data
+      model: sonnet
+      tools:
+        - Read
+        - Write
+        - Bash
+      mcps:
+        - name: jupyter
+          type: stdio
+          command: jupyter-mcp
+          args: ["--notebook-dir", "."]
+          
+    writer:
+      role: "Technical Writer"
+      directory: ~/research/papers
+      model: sonnet
+      tools:
+        - Edit
+        - Write
+        - Read
+```
+
+### Command Line Options
+
+```bash
+# Use default claude-swarm.yml in current directory
+claude-swarm
+
+# Specify a different configuration file
+claude-swarm --config my-swarm.yml
+claude-swarm -c team-config.yml
+
+# Run with --dangerously-skip-permissions for all instances
+claude-swarm --vibe
+
+# Show version
+claude-swarm version
+
+# Internal command for MCP server (used by connected instances)
+claude-swarm mcp-serve INSTANCE_NAME --config CONFIG_FILE --session-timestamp TIMESTAMP
+```
+
+## How It Works
+
+1. **Configuration Parsing**: Claude Swarm reads your YAML configuration and validates it
+2. **MCP Generation**: For each instance, it generates an MCP configuration file that includes:
+   - Any explicitly defined MCP servers
+   - MCP servers for each connected instance (using `claude-swarm mcp-serve`)
+3. **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
+4. **Main Instance Launch**: The main instance is launched with its MCP configuration, giving it access to all connected instances
+5. **Inter-Instance Communication**: Connected instances expose themselves as MCP servers with these tools:
+   - **task**: Execute tasks using Claude Code with configurable tools and return results
+   - **session_info**: Get current Claude session information including ID and working directory
+   - **reset_session**: Reset the Claude session for a fresh start
+6. **Centralized Logging**: All instances log to `.claude-swarm/logs/session-{timestamp}/` with detailed request/response tracking
+
+## Troubleshooting
+
+### Common Issues
+
+**"Configuration file not found"**
+- Ensure `claude-swarm.yml` exists in the current directory
+- Or specify the path with `--config`
+
+**"Main instance not found in instances"**
+- Check that your `main:` field references a valid instance key
+
+**"Unknown instance in connections"**
+- Verify all instances in `connections:` arrays are defined
+
+**Permission Errors**
+- Ensure Claude CLI is properly installed and accessible
+- Check directory permissions for specified paths
+
+### Debug Output
+
+The swarm will display:
+- Generated MCP configuration location
+- Main instance details (model, directory, tools, connections)
+- The exact command being run
+
+### Logs
+
+Check the centralized logs in `.claude-swarm/logs/session-{timestamp}/` for:
+- Individual instance logs
+- MCP server communication
+- Error messages and debugging information
+
+## Architecture
+
+Claude Swarm consists of these core components:
+
+- **ClaudeSwarm::CLI** (`cli.rb`): Thor-based command-line interface with `start` and `mcp-serve` commands
+- **ClaudeSwarm::Configuration** (`configuration.rb`): YAML parser and validator with path expansion
+- **ClaudeSwarm::McpGenerator** (`mcp_generator.rb`): Generates MCP JSON configs for each instance
+- **ClaudeSwarm::Orchestrator** (`orchestrator.rb`): Launches the main Claude instance with shared session management
+- **ClaudeSwarm::ClaudeCodeExecutor** (`claude_code_executor.rb`): Wrapper for executing Claude commands with session persistence
+- **ClaudeSwarm::ClaudeMcpServer** (`claude_mcp_server.rb`): FastMCP-based server providing task execution, session info, and reset capabilities
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Development Commands
+
+```bash
+bin/setup              # Install dependencies
+rake test             # Run the Minitest test suite
+rake rubocop -A       # Run RuboCop linter with auto-fix
+bin/console           # Start IRB session with gem loaded
+bundle exec rake install    # Install gem locally
+bundle exec rake release    # Release gem to RubyGems.org
+rake                  # Default: runs both tests and RuboCop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/parruda/claude-swarm.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/claude-swarm.yml

@@ -0,0 +1,36 @@
+version: 1
+swarm:
+  name: "Rails Expert Team"
+  main: lead_rails_dev
+  instances:
+    lead_rails_dev:
+      role: "Lead Rails Developer"
+      directory: .
+      model: opus
+      connections: [backend_dev, frontend_dev, test_engineer]
+      prompt: "You are a senior Ruby on Rails developer with 10+ years of experience. You excel at Rails architecture, performance optimization, and best practices. You coordinate the team and make architectural decisions."
+      
+    backend_dev:
+      role: "Backend Rails Developer"
+      directory: .
+      model: sonnet
+      connections: [test_engineer]
+      prompt: "You specialize in Rails backend development including models, controllers, services, jobs, and API design. You follow Rails conventions and write clean, maintainable code with a focus on performance and security."
+      mcps:
+        - name: "headless_browser"
+          type: "stdio"
+          command: "bundle"
+          args: ["exec", "hbt", "stdio"]
+    
+    frontend_dev:
+      role: "Rails Frontend Developer"
+      directory: .
+      model: sonnet
+      connections: [test_engineer]
+      prompt: "You are a Rails developer specializing in views, partials, helpers, Stimulus/Turbo, and asset pipeline. You excel at creating responsive UIs with Rails' built-in tools and modern CSS/JavaScript integration."
+          
+    test_engineer:
+      role: "Rails Test Engineer"
+      directory: .
+      model: sonnet
+      prompt: "You are a Rails testing expert specializing in Minitest. You write comprehensive unit tests, integration tests, system tests, and fixtures. You ensure high test coverage and follow Rails testing best practices including proper use of assertions, test helpers, and factories."

data/exe/claude-swarm

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "claude_swarm"
+
+ClaudeSwarm::CLI.start(ARGV)