# claude-swarm
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).
## Purpose
claude-swarm allows you to:
- Create teams of specialized AI agents working together
- Restrict tool access per agent for safety and focus
- Organize agents in tree-like hierarchies for delegation
- Maintain separate working directories per agent
- Enable inter-agent communication via MCP protocol
- Track sessions and restore previous swarm states
## Installation
```bash
# Install via RubyGems
gem install claude_swarm
# Or add to Gemfile
gem 'claude_swarm'
bundle install
```
### Prerequisites
- Ruby 3.2.0 or higher
- Claude CLI installed and configured (`claude` command available)
- Any MCP servers you plan to use (optional)
## Quick Start
1. Initialize a configuration:
```bash
claude-swarm init
```
2. Or create `claude-swarm.yml`:
```yaml
version: 1
swarm:
  name: "My Dev Team"
  main: lead
  instances:
    lead:
      description: "Team lead coordinating development"
      directory: .
      model: opus
      connections: [frontend, backend]
      allowed_tools: [Read, Edit, Bash]
      prompt: "You coordinate the team"
    frontend:
      description: "Frontend developer"
      directory: ./frontend
      model: sonnet
      allowed_tools: [Read, Edit, Write, "Bash(npm:*)"]
```
3. Start the swarm:
```bash
claude-swarm
claude-swarm --vibe  # Allow all tools (dangerous!)
```
## Key Concepts
### Swarm
A collection of Claude instances (agents) working together. One instance is designated as "main" - the entry point that coordinates others.
### Instance
An individual Claude Code agent with:
- **description** (required): Role and responsibilities
- **directory**: Working directory context
- **model**: Claude model (opus/sonnet)
- **connections**: Other instances it can delegate to
- **allowed_tools**: Tools this instance can use
- **disallowed_tools**: Explicitly denied tools (override allowed)
- **prompt**: Custom system prompt
- **vibe**: Skip permission checks for this instance
- **mcps**: Additional MCP servers
### MCP (Model Context Protocol)
Protocol enabling Claude to use external tools. claude-swarm uses MCP for:
- Inter-instance communication (task delegation)
- Permission management
- Additional tool integration
## Configuration Format
```yaml
version: 1
swarm:
  name: "Swarm Name"
  main: instance_key  # Entry point instance
  instances:
    instance_name:
      description: "Agent role description"  # REQUIRED
      directory: ~/path/to/dir              # Working directory
      model: opus                           # opus/sonnet
      connections: [other1, other2]         # Connected instances
      prompt: "Custom system prompt"        # Additional instructions
      vibe: false                          # Skip permissions (default: false)
      allowed_tools:                       # Tools this instance can use
        - Read
        - Edit
        - Write
        - Bash
        - WebSearch
        - WebFetch
      disallowed_tools:                    # Explicitly deny patterns
        - "Write(*.log)"
        - "Bash(rm:*)"
      mcps:                                # Additional MCP servers
        - name: database
          type: stdio
          command: /path/to/mcp
          args: ["--flag"]
          env:
            API_KEY: "value"
        - name: api
          type: sse
          url: https://example.com/mcp
```
## Tool Patterns
Tools can be restricted using patterns:
- `Bash(npm:*)` - Only npm commands in Bash
- `Write(*.md)` - Only write markdown files
- `mcp__frontend__*` - All frontend MCP tools
- `Read` - Unrestricted Read tool
Disallowed tools always override allowed tools.
## Inter-Instance Communication
Instances communicate via the `task` tool exposed by connected instances:
### Task Tool
When instance A connects to instance B, A can use:
```
mcp__B__task
```
**Parameters:**
- `prompt` (required): The task or question for the agent
- `new_session` (optional): Start fresh session (default: false)
- `system_prompt` (optional): Override system prompt for this request
**Example Usage:**
```
Main instance: "Please analyze the frontend performance"
→ Uses mcp__frontend__task with prompt "Analyze performance bottlenecks"
→ Frontend instance executes with its tools and returns results
```
### Session Info Tool
```
mcp__B__session_info
```
Returns current Claude session ID and working directory.
### Reset Session Tool
```
mcp__B__reset_session
```
Resets the Claude session for a fresh start.
## Commands
### Start Swarm
```bash
# Default configuration
claude-swarm
# Custom configuration
claude-swarm --config team.yml
claude-swarm -c my-swarm.yml
# Skip all permissions (dangerous!)
claude-swarm --vibe
# Non-interactive mode with prompt
claude-swarm -p "Build a login feature"
claude-swarm --prompt "Fix the bug" --stream-logs
# Resume session
claude-swarm --session-id 20241225_120000
claude-swarm --session-id ~/.claude-swarm/sessions/project/20241225_120000
```
### List Sessions
```bash
# List recent sessions (default: 10)
claude-swarm list-sessions
# List more sessions
claude-swarm list-sessions --limit 20
# List for specific project
claude-swarm list-sessions --project myapp
```
### Other Commands
```bash
# Initialize starter config
claude-swarm init
# Show version
claude-swarm version
# Start permission MCP server (for testing)
claude-swarm tools-mcp --allowed-tools 'Read,Edit,mcp__*'
# Internal MCP serve command (used by swarm)
claude-swarm mcp-serve -n NAME -d DIR -m MODEL [options]
```
## Session Management
### Session Structure
Sessions are stored in `~/.claude-swarm/sessions/{project}/{timestamp}/`:
```
20241225_143022/
├── config.yml          # Swarm configuration used
├── state/              # Instance states
│   ├── lead_abc123.json    # Lead instance state
│   └── frontend_def456.json # Frontend instance state
├── lead.mcp.json       # MCP configurations
├── frontend.mcp.json
├── session.log         # Human-readable logs
├── session.log.json    # JSONL format events
└── permissions.log     # Permission decisions
```
### Session Files
- **config.yml**: Copy of swarm configuration
- **state/*.json**: Claude session IDs for each instance
- **session.log**: Request/response tracking
- **session.log.json**: All events in JSONL format
- **permissions.log**: Tool permission checks
### Restoring Sessions (Experimental)
```bash
claude-swarm --session-id 20241225_143022
```
**Limitations:**
- Main instance conversation context not fully restored
- Only session IDs preserved, not full state
- Connected instances restore more reliably
## Debugging
### Enable Debug Output
```bash
claude-swarm --debug
```
### Check Logs
```bash
# Session logs
cat ~/.claude-swarm/sessions/PROJECT/TIMESTAMP/session.log
cat ~/.claude-swarm/sessions/PROJECT/TIMESTAMP/permissions.log
# JSONL events
cat ~/.claude-swarm/sessions/PROJECT/TIMESTAMP/session.log.json
```
### Common Issues
**"Configuration file not found"**
- Ensure `claude-swarm.yml` exists
- Or use `--config path/to/config.yml`
**"Main instance not found"**
- Check `main:` references valid instance key
**"Circular dependency detected"**
- Remove circular connections between instances
**"Tool not allowed"**
- Check `allowed_tools` includes the tool
- Check `disallowed_tools` doesn't block it
- Use `vibe: true` to skip all checks (dangerous)
**"MCP server failed to start"**
- Check the command/URL is correct
- Verify MCP server is installed
- Check logs for error details
## Common Patterns
### Full-Stack Team
```yaml
instances:
  architect:
    description: "System architect"
    connections: [frontend_lead, backend_lead, devops]
  frontend_lead:
    description: "Frontend team lead"
    connections: [ui_dev, ux_designer]
  backend_lead:
    description: "Backend team lead"
    connections: [api_dev, db_admin]
```
### Investigation Team
```yaml
instances:
  investigator:
    description: "Lead investigator"
    connections: [data_analyst, code_expert, test_runner]
  data_analyst:
    description: "Analyzes metrics and logs"
    allowed_tools: ["Bash(grep:*, awk:*)", Read]
  code_expert:
    description: "Reviews code changes"
    allowed_tools: [Read, Grep, Glob]
```
### Mixed Permissions
```yaml
instances:
  trusted_lead:
    description: "Trusted lead with full access"
    vibe: true  # Skip all permission checks
  restricted_worker:
    description: "Limited access worker"
    allowed_tools: [Read]  # Read-only access
  normal_worker:
    description: "Standard developer"
    allowed_tools: [Read, Edit, Write]
```
## Complete Example
### Performance Investigation Swarm
```yaml
version: 1
swarm:
  name: "Performance Investigation"
  main: coordinator
  instances:
    coordinator:
      description: "Coordinates performance investigation"
      directory: ~/projects/webapp
      model: opus
      connections: [metrics_analyst, code_reviewer, fix_implementer]
      allowed_tools: [Read]
      prompt: |
        You coordinate a performance investigation team.
        1. Use metrics_analyst to identify when/where issues occur
        2. Use code_reviewer to find root causes
        3. Use fix_implementer to create solutions
        
    metrics_analyst:
      description: "Analyzes performance metrics"
      directory: ~/projects/webapp/logs
      model: sonnet
      allowed_tools: [Read, "Bash(grep:*, awk:*, sort:*)"]
      prompt: |
        You analyze logs and metrics for performance issues.
        Focus on response times, error rates, and patterns.
        
    code_reviewer:
      description: "Reviews code for performance issues"
      directory: ~/projects/webapp/src
      model: opus
      allowed_tools: [Read, Grep, Glob]
      prompt: |
        You review code for performance bottlenecks.
        Look for N+1 queries, missing indexes, inefficient algorithms.
        
    fix_implementer:
      description: "Implements performance fixes"
      directory: ~/projects/webapp
      model: opus
      allowed_tools: [Read, Edit, Write, Bash]
      prompt: |
        You implement optimizations and fixes.
        Always add tests and measure improvements.
```
### Usage Flow
1. **User**: "The checkout page is slow"
2. **Coordinator** → **metrics_analyst**: "Find checkout performance metrics"
3. **Metrics analyst** returns: "Latency spike at 2pm, 3x increase"
4. **Coordinator** → **code_reviewer**: "What changed around 2pm?"
5. **Code reviewer** returns: "HTTP client gem updated, removed connection pooling"
6. **Coordinator** → **fix_implementer**: "Add connection pooling configuration"
7. **Fix implementer**: Creates fix and tests
## How It Works
1. **Configuration Parsing**: Validates YAML and expands paths
2. **MCP Generation**: Creates MCP configs in `.claude-swarm/`
3. **Permission Setup**: Adds permission MCP server (unless vibe mode)
4. **Instance Launch**: Starts main instance with connections
5. **Task Delegation**: Main instance uses mcp__instance__task tools
6. **Session Tracking**: All activity logged to session directory
## Development
```bash
# Setup
bin/setup
# Run tests
rake test
# Lint code
rake rubocop -A
# Console
bin/console
# Install locally
bundle exec rake install
# Release to RubyGems
bundle exec rake release
```
## Architecture
- **CLI** (`cli.rb`): Thor-based commands
- **Configuration** (`configuration.rb`): YAML parser/validator
- **McpGenerator** (`mcp_generator.rb`): Creates MCP JSON configs
- **Orchestrator** (`orchestrator.rb`): Launches main instance
- **ClaudeCodeExecutor** (`claude_code_executor.rb`): Executes Claude
- **ClaudeMcpServer** (`claude_mcp_server.rb`): Inter-instance MCP
- **PermissionMcpServer** (`permission_mcp_server.rb`): Tool permissions
## Environment Variables
- `CLAUDE_SWARM_HOME`: Override session storage location (default: ~/.claude-swarm)
- `ANTHROPIC_MODEL`: Default Claude model if not specified
## Security Considerations
- Tool restrictions enforced through configuration
- Vibe mode bypasses ALL restrictions - use carefully
- Session files may contain sensitive data
- Each instance runs with its directory context
- MCP servers inherit instance tool configurations
## Limitations
- Tree hierarchy only (no circular dependencies)
- Session restoration is experimental
- Main instance context not fully preserved
- All paths expand relative to execution directory
- MCP servers must support required protocol
## Best Practices
1. **Clear Descriptions**: Help agents understand their roles
2. **Focused Tools**: Give each instance only needed tools
3. **Directory Context**: Place instances in relevant directories
4. **Prompt Engineering**: Use prompts to guide behavior
5. **Test Configurations**: Start simple, add complexity gradually
6. **Monitor Logs**: Check session logs for issues
7. **Use Vibe Sparingly**: Only for trusted operations