# 🚀 Claude Flow Plugin - Complete Enterprise AI Agent Orchestration

[![Version](https://img.shields.io/badge/version-2.5.0-blue.svg)](https://github.com/ruvnet/claude-flow)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-%3E%3D2.0.0-purple.svg)](https://claude.com/code)

> **Enterprise-grade AI agent orchestration plugin with 150+ commands, 74+ specialized agents, SPARC methodology, swarm coordination, GitHub integration, and neural training capabilities**

---

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Components](#components)
- [Usage](#usage)
- [MCP Integration](#mcp-integration)
- [Examples](#examples)
- [Documentation](#documentation)
- [Support](#support)

---

## 🌟 Overview

Claude Flow is the most comprehensive Claude Code plugin for enterprise AI agent orchestration. It provides a complete ecosystem for:

- **Multi-Agent Coordination**: 74+ specialized agents with swarm intelligence
- **SPARC Methodology**: Systematic development with 18 specialized modes
- **GitHub Automation**: 14+ tools for complete repository workflow automation
- **Neural Training**: 27+ models with WASM acceleration
- **150+ Commands**: Complete slash command library for all workflows
- **MCP Integration**: 110+ tools across 3 MCP servers

---

## ✨ Features

### 🐝 **Swarm Coordination**
- **4 Topologies**: Hierarchical, Mesh, Ring, Star
- **Auto-Spawning**: Intelligent agent creation based on task complexity
- **Auto-Optimization**: Dynamic topology adjustment for performance
- **100 Max Agents**: Scale to handle enterprise workloads
- **Cross-Session Memory**: Persistent context and learnings

### 🎯 **SPARC Methodology**
- **Specification**: Requirements analysis and planning
- **Pseudocode**: Algorithm design and logic flow
- **Architecture**: System design and component structure
- **Refinement**: TDD and iterative improvement
- **Code**: Implementation and optimization
- **18 Specialized Modes**: Complete development lifecycle coverage

### 🐙 **GitHub Integration**
- **PR Management**: Automated pull request workflows
- **Code Review Swarms**: Multi-agent code analysis
- **Issue Tracking**: Intelligent issue triage and assignment
- **Release Automation**: Coordinated multi-package releases
- **Workflow Automation**: Custom GitHub Actions integration
- **Multi-Repo Coordination**: Cross-repository synchronization

### 🧠 **Neural Training**
- **27+ Models**: Pre-trained patterns for common tasks
- **WASM Acceleration**: 2.8-4.4x speed improvement
- **SIMD Optimization**: Advanced vector processing
- **Pattern Learning**: Self-improving agent behaviors
- **Context Persistence**: Cross-session learning retention

### 🎨 **74+ Specialized Agents**

#### Core Development (5)
- `coder` - Code implementation specialist
- `planner` - Strategic planning and roadmaps
- `researcher` - Information gathering and analysis
- `reviewer` - Code quality and security review
- `tester` - Comprehensive test creation

#### Swarm Coordination (5)
- `hierarchical-coordinator` - Queen-led command structure
- `mesh-coordinator` - Peer-to-peer coordination
- `adaptive-coordinator` - Dynamic topology management
- `collective-intelligence-coordinator` - Distributed decision-making
- `swarm-memory-manager` - Cross-agent memory coordination

#### Consensus & Fault Tolerance (7)
- `byzantine-coordinator` - Byzantine fault tolerance
- `raft-manager` - Raft consensus protocol
- `gossip-coordinator` - Gossip-based consensus
- `crdt-synchronizer` - Conflict-free data replication
- `quorum-manager` - Dynamic quorum management
- `security-manager` - Comprehensive security protocols
- `performance-benchmarker` - Consensus performance testing

#### GitHub Automation (13)
- `pr-manager` - Pull request coordination
- `code-review-swarm` - Multi-agent code reviews
- `issue-tracker` - Issue management and triage
- `release-manager` - Release coordination
- `workflow-automation` - GitHub Actions management
- `repo-architect` - Repository structure optimization
- `multi-repo-swarm` - Cross-repository coordination
- `sync-coordinator` - Version alignment across repos
- And 5 more specialized GitHub agents...

#### Specialized Development (8)
- `backend-dev` - Backend API development
- `mobile-dev` - React Native mobile development
- `ml-developer` - Machine learning workflows
- `cicd-engineer` - CI/CD pipeline creation
- `api-docs` - OpenAPI/Swagger documentation
- `system-architect` - System design and architecture
- `code-analyzer` - Advanced code quality analysis
- `base-template-generator` - Boilerplate generation

#### SPARC Methodology (4)
- `specification` - Requirements analysis
- `pseudocode` - Algorithm design
- `architecture` - System architecture
- `refinement` - Iterative improvement

#### And 32 more specialized agents!

### 📦 **150+ Commands**

#### Coordination (6)
- `/coordination-swarm-init` - Initialize swarm with topology
- `/coordination-agent-spawn` - Create specialized agents
- `/coordination-task-orchestrate` - Coordinate task execution
- `/coordination-spawn` - Quick agent spawning
- `/coordination-orchestrate` - Advanced orchestration
- `/coordination-init` - Setup coordination environment

#### SPARC Methodology (18)
- `/sparc-modes` - List all SPARC modes
- `/sparc-coder` - Clean code implementation
- `/sparc-tdd` - Test-driven development
- `/sparc-architect` - Architecture design
- `/sparc-reviewer` - Code review mode
- `/sparc-tester` - Test creation mode
- `/sparc-analyzer` - Code analysis
- `/sparc-researcher` - Research mode
- `/sparc-optimizer` - Performance optimization
- `/sparc-debugger` - Debugging assistance
- `/sparc-designer` - UI/UX design mode
- `/sparc-documenter` - Documentation creation
- `/sparc-innovator` - Innovation and R&D
- `/sparc-orchestrator` - Workflow orchestration
- `/sparc-batch-executor` - Batch operations
- `/sparc-memory-manager` - Memory management
- `/sparc-workflow-manager` - Workflow management
- `/sparc-swarm-coordinator` - Swarm coordination

#### GitHub Integration (18)
- `/github-code-review` - Automated code reviews
- `/github-code-review-swarm` - Multi-agent reviews
- `/github-pr-manager` - PR lifecycle management
- `/github-pr-enhance` - PR enhancement automation
- `/github-issue-tracker` - Issue tracking
- `/github-issue-triage` - Intelligent issue triage
- `/github-repo-analyze` - Repository analysis
- `/github-repo-architect` - Repo structure optimization
- `/github-release-manager` - Release coordination
- `/github-release-swarm` - Multi-package releases
- `/github-workflow-automation` - GitHub Actions automation
- `/github-swarm-pr` - PR swarm management
- `/github-swarm-issue` - Issue swarm coordination
- `/github-multi-repo-swarm` - Cross-repo coordination
- `/github-sync-coordinator` - Version synchronization
- `/github-project-board-sync` - Project board integration
- `/github-modes` - GitHub integration modes
- `/github-swarm` - GitHub swarm orchestration

#### Hive Mind (11)
- `/hive-mind` - Initialize hive mind coordination
- `/hive-mind-init` - Setup hive mind topology
- `/hive-mind-spawn` - Spawn hive agents
- `/hive-mind-status` - Check hive status
- `/hive-mind-consensus` - Consensus protocols
- `/hive-mind-memory` - Shared memory management
- `/hive-mind-metrics` - Performance metrics
- `/hive-mind-sessions` - Session management
- `/hive-mind-resume` - Resume hive sessions
- `/hive-mind-stop` - Stop hive coordination
- `/hive-mind-wizard` - Guided setup wizard

#### Memory Management (5)
- `/memory-usage` - Memory storage and retrieval
- `/memory-persist` - Cross-session persistence
- `/memory-search` - Pattern-based search
- `/memory-neural` - Neural memory integration

#### Monitoring (5)
- `/monitoring-status` - System status overview
- `/monitoring-agents` - Agent status monitoring
- `/monitoring-agent-metrics` - Performance metrics
- `/monitoring-swarm-monitor` - Real-time swarm monitoring
- `/monitoring-real-time-view` - Live dashboard

#### Optimization (5)
- `/optimization-topology-optimize` - Auto-optimize topology
- `/optimization-auto-topology` - Automatic topology selection
- `/optimization-parallel-execution` - Parallel task execution
- `/optimization-parallel-execute` - Execute tasks in parallel
- `/optimization-cache-manage` - Cache management

#### Analysis (5)
- `/analysis-performance-report` - Performance reports
- `/analysis-performance-bottlenecks` - Bottleneck detection
- `/analysis-bottleneck-detect` - Real-time bottleneck analysis
- `/analysis-token-usage` - Token consumption analysis
- `/analysis-token-efficiency` - Token optimization

#### Automation (6)
- `/automation-smart-spawn` - Intelligent agent spawning
- `/automation-smart-agents` - Auto-agent selection
- `/automation-auto-agent` - Automated agent management
- `/automation-self-healing` - Self-healing workflows
- `/automation-session-memory` - Session persistence
- `/automation-workflow-select` - Workflow selection

#### Hooks (7)
- `/hooks-setup` - Configure hooks system
- `/hooks-overview` - Hooks documentation
- `/hooks-pre-task` - Pre-task hook setup
- `/hooks-post-task` - Post-task hook setup
- `/hooks-pre-edit` - Pre-edit hook setup
- `/hooks-post-edit` - Post-edit hook setup
- `/hooks-session-end` - Session end hook setup

#### Swarm Management (15)
- `/swarm` - Main swarm command
- `/swarm-init` - Initialize swarm
- `/swarm-spawn` - Spawn swarm agents
- `/swarm-status` - Swarm status
- `/swarm-monitor` - Real-time monitoring
- `/swarm-modes` - Available swarm modes
- `/swarm-strategies` - Execution strategies
- `/swarm-background` - Background swarm execution
- `/swarm-analysis` - Swarm analysis workflows
- `/swarm-research` - Research swarms
- `/swarm-development` - Development swarms
- `/swarm-testing` - Testing swarms
- `/swarm-maintenance` - Maintenance swarms
- `/swarm-optimization` - Optimization swarms
- `/swarm-examples` - Swarm examples

#### Workflows (5)
- `/workflows-create` - Create custom workflows
- `/workflows-execute` - Execute workflows
- `/workflows-export` - Export workflow definitions
- `/workflows-development` - Development workflows
- `/workflows-research` - Research workflows

#### Neural Training (5)
- `/training-neural-train` - Train neural patterns
- `/training-neural-patterns` - Pattern management
- `/training-pattern-learn` - Pattern learning
- `/training-model-update` - Model updates
- `/training-specialization` - Agent specialization

#### Flow Nexus (9)
- `/flow-nexus-swarm` - Cloud swarm orchestration
- `/flow-nexus-workflow` - Event-driven workflows
- `/flow-nexus-neural-network` - Distributed neural training
- `/flow-nexus-sandbox` - E2B sandbox management
- `/flow-nexus-app-store` - Application marketplace
- `/flow-nexus-challenges` - Coding challenges
- `/flow-nexus-payments` - Credit management
- `/flow-nexus-user-tools` - User management
- `/flow-nexus-login` - Authentication

#### And 50+ more commands!

---

## 🚀 Quick Start

### 1. Install Claude Code Plugin

In Claude Code:

```
/plugin add ruvnet/claude-flow
```

Or from local directory:

```bash
git clone https://github.com/ruvnet/claude-flow.git
cd claude-flow
```

Then in Claude Code:
```
/plugin add .
```

### 2. Restart Claude Code

```
/restart
```

### 3. Configure MCP Servers (Optional)

```bash
# Add MCP servers to Claude Code
claude mcp add claude-flow npx claude-flow@alpha mcp start
claude mcp add ruv-swarm npx ruv-swarm mcp start  # Optional
claude mcp add flow-nexus npx flow-nexus@latest mcp start  # Optional
```

### 4. Verify Installation

```bash
# Check plugin status
claude plugin list

# Test a command
# In Claude Code, type:
/coordination-swarm-init
```

---

## 📦 Installation

### Prerequisites

- **Claude Code CLI** >= 2.0.0
- **Node.js** >= 20.0.0
- **Git** (for GitHub integration features)
- Read/write permissions in project directory

### Method 1: Direct Installation (Recommended)

In Claude Code:
```
/plugin add ruvnet/claude-flow
/restart
```

### Method 2: Local Installation

```bash
# Clone the repository
git clone https://github.com/ruvnet/claude-flow.git
cd claude-flow/claude-plugin

# Run installation script
bash scripts/install.sh

# Or copy manually
cp -r commands ~/.claude/commands/
cp -r agents ~/.claude/agents/
```

### Method 3: NPX (One-Time Setup)

```bash
# Run setup via npx
npx claude-flow@alpha init --plugin

# This will:
# 1. Create .claude directory
# 2. Copy all commands and agents
# 3. Configure MCP servers
# 4. Setup hooks
```

---

## 🏗️ Components

### Directory Structure

```
claude-flow/
├── .claude-plugin/
│   ├── plugin.json          # Plugin metadata
│   ├── README.md            # This file
│   └── ...
├── commands/                 # 150+ slash commands
│   ├── coordination/         # Swarm coordination commands
│   ├── sparc/                # SPARC methodology commands
│   ├── github/               # GitHub integration commands
│   ├── hive-mind/            # Hive mind commands
│   ├── hooks/                # Hooks configuration commands
│   ├── memory/               # Memory management commands
│   ├── monitoring/           # Monitoring commands
│   ├── optimization/         # Optimization commands
│   ├── analysis/             # Analysis commands
│   ├── automation/           # Automation commands
│   ├── swarm/                # Swarm management commands
│   ├── workflows/            # Workflow commands
│   ├── training/             # Neural training commands
│   ├── flow-nexus/           # Flow Nexus integration
│   └── ...                   # And more!
├── agents/                   # 74+ specialized agents
│   ├── core/                 # Core development agents
│   ├── consensus/            # Consensus protocol agents
│   ├── github/               # GitHub automation agents
│   ├── swarm/                # Swarm coordination agents
│   ├── hive-mind/            # Hive mind agents
│   ├── sparc/                # SPARC methodology agents
│   ├── optimization/         # Optimization agents
│   ├── specialized/          # Domain-specific agents
│   ├── templates/            # Template agents
│   ├── testing/              # Testing agents
│   └── ...                   # And more!
├── hooks/                    # Hook scripts
│   ├── pre-tool-use.sh
│   ├── post-tool-use.sh
│   ├── pre-task.sh
│   ├── post-task.sh
│   ├── session-start.sh
│   └── session-end.sh
├── scripts/                  # Installation and setup scripts
│   ├── install.sh
│   ├── setup-mcp.sh
│   ├── verify.sh
│   └── uninstall.sh
└── docs/                     # Documentation
    ├── QUICKSTART.md
    ├── USER_GUIDE.md
    ├── API_REFERENCE.md
    ├── EXAMPLES.md
    └── TROUBLESHOOTING.md
```

---

## 💡 Usage

### Basic Swarm Coordination

```bash
# Initialize a hierarchical swarm
/coordination-swarm-init

# Spawn specialized agents
/coordination-agent-spawn

# Orchestrate a complex task
/coordination-task-orchestrate "Build REST API with authentication"
```

### SPARC Development Workflow

```bash
# Start with specification
/sparc-modes specification "User authentication system"

# Design architecture
/sparc-architect

# Implement with TDD
/sparc-tdd "Implement JWT authentication"

# Code review
/sparc-reviewer

# Optimize performance
/sparc-optimizer
```

### GitHub Automation

```bash
# Analyze repository
/github-repo-analyze

# Create PR with automated review
/github-pr-manager

# Multi-agent code review
/github-code-review-swarm

# Coordinate release across repos
/github-multi-repo-swarm
```

### Hive Mind Coordination

```bash
# Initialize hive mind
/hive-mind-init

# Spawn hive agents with consensus
/hive-mind-spawn

# Check consensus status
/hive-mind-consensus

# View shared memory
/hive-mind-memory
```

---

## 🔌 MCP Integration

Claude Flow integrates with 3 MCP servers providing 110+ tools:

### Claude Flow MCP (Required)

```json
{
  "mcpServers": {
    "claude-flow": {
      "command": "npx",
      "args": ["claude-flow@alpha", "mcp", "start"]
    }
  }
}
```

**Tools**: 40+ orchestration tools
- Swarm initialization and management
- Agent spawning and coordination
- Task orchestration
- Memory management
- Neural training
- Performance monitoring

### ruv-swarm MCP (Optional)

```json
{
  "mcpServers": {
    "ruv-swarm": {
      "command": "npx",
      "args": ["ruv-swarm", "mcp", "start"]
    }
  }
}
```

**Tools**: Enhanced coordination features
- WASM acceleration (2.8-4.4x speed)
- SIMD optimization
- Advanced topology management
- Byzantine fault tolerance

### Flow Nexus MCP (Optional - Requires Auth)

```json
{
  "mcpServers": {
    "flow-nexus": {
      "command": "npx",
      "args": ["flow-nexus@latest", "mcp", "start"]
    }
  }
}
```

**Tools**: 70+ cloud features
- E2B sandbox execution
- Distributed neural training
- Event-driven workflows
- Application marketplace
- Real-time collaboration

---

## 📚 Examples

### Example 1: Full-Stack Development with Swarm

```bash
# Initialize hierarchical swarm
/coordination-swarm-init

# The swarm automatically spawns:
# - backend-dev agent
# - coder agent for frontend
# - tester agent
# - reviewer agent

# Orchestrate the full-stack build
/coordination-task-orchestrate "Build a todo app with React frontend and Express backend"

# Monitor progress
/monitoring-swarm-monitor

# Get performance metrics
/analysis-performance-report
```

### Example 2: SPARC TDD Workflow

```bash
# Start with specification
/sparc-modes specification "Shopping cart with inventory management"

# Generate pseudocode
/sparc-modes pseudocode

# Design architecture
/sparc-architect

# TDD implementation
/sparc-tdd

# Automated review
/sparc-reviewer

# Performance optimization
/sparc-optimizer
```

### Example 3: GitHub PR Automation

```bash
# Analyze current PR
/github-pr-manager

# Multi-agent code review
/github-code-review-swarm

# Auto-fix issues
/github-pr-enhance

# Sync across repositories
/github-sync-coordinator

# Prepare release
/github-release-manager
```

---

## 📖 Documentation

- **[Quickstart Guide](docs/QUICKSTART.md)** - Get started in 5 minutes
- **[User Guide](docs/USER_GUIDE.md)** - Complete usage documentation
- **[API Reference](docs/API_REFERENCE.md)** - All commands and agents
- **[Examples](docs/EXAMPLES.md)** - Real-world usage examples
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions

---

## 🤝 Support

- **Documentation**: [GitHub Wiki](https://github.com/ruvnet/claude-flow/wiki)
- **Issues**: [GitHub Issues](https://github.com/ruvnet/claude-flow/issues)
- **Discussions**: [GitHub Discussions](https://github.com/ruvnet/claude-flow/discussions)
- **Website**: [Flow Nexus](https://flow-nexus.ruv.io)

---

## 📊 Performance

- **84.8%** SWE-Bench solve rate
- **32.3%** token reduction vs. sequential execution
- **2.8-4.4x** speed improvement with WASM acceleration
- **27+** neural models for pattern recognition
- **100** max concurrent agents

---

## 🔧 Advanced Configuration

### Custom Swarm Topology

```json
{
  "swarmCoordination": {
    "topology": "mesh",
    "maxAgents": 50,
    "autoSpawn": true,
    "autoOptimize": true
  }
}
```

### Enable Neural Training

```json
{
  "neuralTraining": {
    "enabled": true,
    "wasmAcceleration": true,
    "simdOptimization": true
  }
}
```

### Configure Hooks

```json
{
  "hooks": {
    "PreToolUse": { "enabled": true },
    "PostToolUse": { "enabled": true },
    "SessionEnd": { "enabled": true }
  }
}
```

---

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details

---

## 🌟 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=ruvnet/claude-flow&type=Date)](https://star-history.com/#ruvnet/claude-flow&Date)

---

**Made with ❤️ by rUv**

*Enterprise AI Agent Orchestration for Claude Code*