ccswarm 0.2.2

AI-powered multi-agent orchestration system with session management
Documentation

ccswarm: AI Multi-Agent Orchestration System

🚀 Version 0.2.2 - Enhanced with Anthropic-inspired interleaved thinking, advanced LLM quality judge, and improved CI/CD compatibility!

Crates.io Rust License: MIT Downloads

ccswarm is an AI-powered multi-agent orchestration system that manages specialized AI agents using Claude Code, Aider, and other providers. It features session persistence, intelligent task delegation, auto-create functionality, and real-time monitoring through a Terminal UI.

🌟 Key Features (v0.2.2)

  • 🤖 Multi-Provider Support: Claude Code, Aider, OpenAI Codex, Custom tools
  • 💾 Session Persistence: 93% token reduction through conversation history
  • 🎯 Intelligent Delegation: Master Claude analyzes and assigns tasks optimally
  • 🚀 Auto-Create System: Generate complete applications from natural language
  • 📊 Enhanced TUI: Real-time monitoring with improved task management and filtering
  • 🔄 Git Worktree Isolation: Parallel development without conflicts
  • ✅ Auto-Accept Mode: Safe automated execution with risk assessment
  • 🔒 Execution Mode: Runs with --dangerously-skip-permissions by default
  • 🔍 LLM Quality Judge: Advanced code evaluation using Claude with multi-dimensional scoring
  • 📚 Command Documentation: Comprehensive docs in .claude/commands/
  • 🎛️ Improved Session Pool: Better load balancing and resource management
  • 🔧 Enhanced Config System: More flexible provider and agent configuration

🚀 Quick Start

Note: Don't have Claude Code or API keys? Check out our Standalone Deployment Guide to run ccswarm without any AI dependencies!

1. Installation

# Install from crates.io
cargo install ccswarm

# Or build from source
git clone https://github.com/nwiizo/ccswarm.git
cd ccswarm
cargo build --release
cargo install --path .

2. Initialize Project

# Basic initialization
ccswarm init --name "MyProject" --agents frontend,backend,devops

# With specific template
ccswarm init --name "AiderProject" --template aider-focused

3. Start System

# Terminal 1: Start orchestrator
ccswarm start

# Terminal 2: Start TUI for monitoring
ccswarm tui

4. Create Applications

# Generate TODO app
ccswarm auto-create "Create TODO app" --output ./my_app

# Generate blog
ccswarm auto-create "Create blog with auth" --output ./blog

🏗️ Architecture

Session-Persistent Architecture

┌─────────────────────────────────────────┐
│         Master Claude                   │ ← Orchestration & Delegation
│     ├─ Task Assignment                  │
│     ├─ Quality Review (30s interval)    │
│     └─ Remediation Task Generation      │
├─────────────────────────────────────────┤
│     Session-Persistent Manager          │ ← 93% Token Reduction
│     ├─ Session Pool & Reuse            │
│     ├─ Conversation History (50 msgs)   │
│     └─ Batch Task Processing           │
├─────────────────────────────────────────┤
│     Git Worktree Manager                │ ← Isolated Development
├─────────────────────────────────────────┤
│     Multi-Provider Agent Pool           │
│     ├─ Claude Code (default)           │
│     ├─ Aider                           │
│     ├─ OpenAI Codex                    │
│     └─ Custom Tools                    │
├─────────────────────────────────────────┤
│     Real-time Monitoring (TUI)          │ ← Live Status Updates
└─────────────────────────────────────────┘

Agent Roles

pub enum AgentRole {
    Frontend,  // UI development only
    Backend,   // API development only
    DevOps,    // Infrastructure only
    QA,        // Testing only
    Master,    // Orchestration (no coding)
}

📋 Core Commands

📖 Full command documentation available in .claude/commands/

Basic Operations

# Initialize project
ccswarm init --name "Project" --agents frontend,backend

# Start system
ccswarm start

# Launch TUI (enhanced in v0.2.0)
ccswarm tui

# Check status
ccswarm status --detailed

# Stop orchestrator
ccswarm stop

Task Management

# Add task (enhanced in v0.2.0)
ccswarm task "Create login form" --priority high --type feature

# Delegate task with improved analysis
ccswarm delegate analyze "Add authentication" --verbose
ccswarm delegate task "Add auth" --agent backend --priority high

# View delegation statistics
ccswarm delegate stats --period 24h

Auto-Create Applications (Enhanced)

# TODO app with modern stack
ccswarm auto-create "Create TODO app" --output ./todo

# Blog with advanced features
ccswarm auto-create "Blog with auth and comments" --output ./blog

# E-commerce with full stack
ccswarm auto-create "Online shop with cart" --output ./shop

# Custom template support (v0.2.0)
ccswarm auto-create "Project description" --template custom --output ./app

🎮 Terminal UI (TUI)

Start with ccswarm tui:

Key Bindings

  • Tab/Shift+Tab - Switch tabs
  • ↑↓/jk - Navigate
  • Enter - Select/Activate
  • c - Command mode
  • t - Add task
  • q - Quit

Command Mode (c key) - Enhanced in v0.2.0

task <description> [high|medium|low] [feature|bug|test|docs|refactor]
agent <type>
session list|attach|pause|resume|stats
filter <pattern>
worktree list|clean
monitor <agent>
review status|history
help

Smart Task Parsing

task Fix login bug [high] [bug]
task Add docs [docs]
task Create dashboard [medium] [feature]

⚙️ Configuration

ccswarm.json Structure

{
  "project": {
    "name": "MyProject",
    "master_claude_instructions": "Orchestrate agents efficiently"
  },
  "agents": [
    {
      "name": "frontend-specialist",
      "role": "Frontend",
      "provider": "claude_code",
      "claude_config": {
        "model": "claude-3.5-sonnet",
        "dangerous_skip": true,
        "think_mode": "think_hard"
      },
      "auto_accept": {
        "enabled": true,
        "risk_threshold": 5
      }
    }
  ],
  "coordination": {
    "method": "JSON_FILES",
    "delegation_strategy": "Hybrid"
  },
  "session_management": {
    "persistent_sessions": true,
    "max_sessions_per_role": 3
  }
}

Provider Configuration

Claude Code (Default)

{
  "provider": "claude_code",
  "claude_config": {
    "model": "claude-3.5-sonnet",
    "dangerous_skip": true,
    "think_mode": "think_hard"
  }
}

Aider

{
  "provider": "aider",
  "config": {
    "model": "claude-3-5-sonnet",
    "auto_commit": true,
    "edit_format": "diff"
  }
}

🎯 Master Delegation System

Delegation Strategies

  • ContentBased: Keyword matching
  • LoadBalanced: Workload distribution
  • ExpertiseBased: Historical performance
  • WorkflowBased: Task dependencies
  • Hybrid (default): Combined approach

Delegation Commands

# Analyze task
ccswarm delegate analyze "Create responsive nav" --verbose

# Manual delegation
ccswarm delegate task "Add API endpoint" --agent backend

# View statistics
ccswarm delegate stats --period 24h

🚀 Auto-Create System

Supported Applications

  • TODO apps with CRUD
  • Blogs with authentication
  • E-commerce platforms
  • Real-time chat apps
  • Custom applications

Generated Structure

my_app/
├── index.html       # React app
├── app.js          # Components
├── server.js       # Express API
├── package.json    # Dependencies
├── Dockerfile      # Container
├── README.md       # Documentation
└── .gitignore      # Git config

🔧 Session Management

Session Features

  • Persistent conversation history
  • Session pooling and reuse
  • Batch task execution
  • Auto-scaling

Session Commands

# List sessions
ccswarm session list

# Attach to session
ccswarm session attach <session-id>

# Pause/Resume
ccswarm session pause <session-id>
ccswarm session resume <session-id>

🛡️ Safety Features (Enhanced)

Auto-Accept Mode

  • Risk assessment (1-10 scale)
  • Enhanced file protection patterns
  • Emergency stop capability
  • Comprehensive audit trails
  • Pre/post execution validation

Execution Mode

By default, ccswarm runs with dangerous_skip: true, which adds the --dangerously-skip-permissions flag to Claude Code commands for automated execution.

New in v0.2.0

  • Improved risk assessment algorithms
  • Better handling of sensitive files
  • Enhanced validation patterns

🔍 LLM-as-Judge Quality Review (v0.2.2)

Advanced Code Evaluation

Master Claude now uses sophisticated LLM-based evaluation to assess code quality across 8 dimensions:

  1. Multi-Dimensional Scoring (0.0-1.0)

    • Correctness: Does the code implement requirements correctly?
    • Maintainability: Is it well-structured and easy to modify?
    • Test Quality: Are tests comprehensive with good coverage?
    • Security: Does it follow security best practices?
    • Performance: Are there optimization opportunities?
    • Documentation: Is the code properly documented?
    • Architecture: Does it follow good design patterns?
    • Error Handling: Is error handling robust?

  2. Issue Severity Classification

    • Critical: Must fix immediately (e.g., security vulnerabilities)
    • High: Should fix before deployment (e.g., missing auth)
    • Medium: Should address soon (e.g., low test coverage)
    • Low: Nice to fix (e.g., minor documentation gaps)

  3. Intelligent Remediation

    • LLM generates detailed, context-aware fix instructions
    • Suggestions tailored to agent specialization
    • Tracks confidence levels for each evaluation
    • Provides specific code examples and best practices

Example Quality Evaluation

{
  "overall_score": 0.78,
  "dimensions": {
    "correctness": 0.90,
    "test_quality": 0.65,
    "security": 0.75,
    "documentation": 0.70
  },
  "issues": [
    {
      "severity": "high",
      "category": "TestCoverage",
      "description": "Test coverage is 65%, below 85% requirement",
      "suggested_fix": "Add unit tests for error cases"
    }
  ],
  "feedback": "Good implementation but needs more comprehensive testing",
  "passes_standards": false,
  "confidence": 0.92
}

Review Workflow

Task Completed → LLM Quality Review → Detailed Evaluation → Remediation Task
                     ↓                      ↓                      ↓
                 Score ≥ 0.85          Issues Found          Smart Fix Instructions
                     ↓                      ↓                      ↓
                 Task Approved         Agent Fixes            Re-evaluate

📊 Monitoring

Real-time Metrics

  • Agent health status
  • Task completion rates
  • Session utilization
  • Performance tracking

Debug Mode

# Verbose logging
RUST_LOG=debug ccswarm start

# Session debugging
RUST_LOG=ccswarm::session=trace ccswarm start

# View tmux sessions
tmux ls

🧪 Testing

# All tests
cargo test

# Specific module
cargo test session
cargo test identity
cargo test quality_review  # New in v0.2.0

# Integration tests
cargo test --test integration_tests

# Examples (relocated to demos/)
cargo run --example todo_app_builder     # See demos/todo-app/
cargo run --example monitoring_demo      # See demos/multi-agent/
cargo run --example session_demo         # See demos/session-persistence/
cargo run --example auto_create_demo     # See demos/auto-create/

🚨 Troubleshooting

Common Issues

Session not found

ccswarm session list
ccswarm session create --agent frontend

Provider errors

# Check API keys
echo $ANTHROPIC_API_KEY

# Verify provider config
ccswarm config show

Worktree conflicts

ccswarm worktree list
ccswarm worktree clean

🛠️ Development

Adding Custom Providers

  1. Implement ProviderExecutor trait
  2. Add to ProviderType enum
  3. Update configuration parsing
  4. Add provider-specific configuration options

v0.2.0 Architecture Improvements

  • Enhanced session pool management
  • Improved task routing algorithms
  • Better error recovery mechanisms
  • Extended provider API support

🚀 Standalone Deployment (No AI Dependencies)

ccswarm can run without Claude Code or other AI providers! Check out the STANDALONE_DEPLOYMENT.md guide for:

  • Simulation Mode: Run with simulated agents for testing and learning
  • Built-in Templates: Generate complete applications without AI providers
  • Docker Deployment: Containerized setup for easy deployment
  • Custom Providers: Create your own agent implementations
  • Offline Operation: Full functionality without internet connection

Quick Standalone Example

# Start in simulation mode
CCSWARM_SIMULATION=true ccswarm start

# Generate a complete TODO app without AI
ccswarm auto-create "Create TODO app" --output ./my-app

# Run the generated app
cd my-app && npm install && npm start

For detailed instructions, examples, and Docker configurations, see STANDALONE_DEPLOYMENT.md.

Contributing

# Fork and clone
git clone https://github.com/yourusername/ccswarm.git

# Run tests
cargo test

# Format code
cargo fmt
cargo clippy -- -D warnings

# Check documentation
cargo doc --no-deps --open

📄 License

MIT License - see LICENSE

🙏 Acknowledgments

  • Anthropic for Claude and Claude Code
  • Rust community for excellent libraries
  • Contributors and early adopters

📝 Release Notes (v0.2.0)

New Features

  • Enhanced quality review system with iteration tracking
  • Improved TUI with better task filtering and management
  • Comprehensive command documentation in .claude/commands/
  • Better session pool management and load balancing
  • Extended provider configuration options

Improvements

  • More robust error handling and recovery
  • Enhanced auto-create templates
  • Better git worktree management
  • Improved delegation algorithms
  • Performance optimizations

Bug Fixes

  • Fixed session persistence edge cases
  • Resolved TUI rendering issues
  • Corrected task priority handling
  • Fixed provider timeout issues

Experience the power of AI agent orchestration with ccswarm v0.2.0 🚀