# CleverClaude Documentation

Welcome to CleverClaude - an advanced AI agent orchestration system that enables sophisticated multi-agent coordination, swarm intelligence, and task automation.

## 📚 Documentation Index

- [Installation Guide](installation.md) - Get CleverClaude up and running
- [Quick Start](quickstart.md) - Your first CleverClaude project
- [Architecture Overview](architecture.md) - System design and components
- [CLI Reference](cli-reference.md) - Complete command-line interface guide
- [API Documentation](api-reference.md) - HTTP API endpoints and usage
- [Agent Management](agents.md) - Creating and managing AI agents
- [Swarm Coordination](swarms.md) - Multi-agent swarm orchestration
- [MCP Integration](mcp.md) - Model Context Protocol tools and usage
- [Configuration](configuration.md) - System configuration options
- [Testing Guide](testing.md) - Running and writing tests
- [Deployment](deployment.md) - Production deployment strategies
- [Examples](examples/) - Code examples and tutorials
- [Migration Guide](migration.md) - Migrating from claude-flow
- [Contributing](contributing.md) - How to contribute to the project
- [Troubleshooting](troubleshooting.md) - Common issues and solutions

## 🌟 Key Features

### Multi-Agent Orchestration
- **Agent Types**: Researcher, Coder, Analyst, Coordinator, Reviewer, Tester
- **Lifecycle Management**: Create, pause, resume, destroy agents
- **Task Assignment**: Intelligent task routing based on capabilities
- **Health Monitoring**: Real-time agent performance tracking

### Swarm Coordination
- **Multiple Topologies**: Mesh, Hierarchical, Star, Ring architectures
- **Dynamic Scaling**: Auto-scale swarms based on workload
- **Load Balancing**: Intelligent task distribution
- **Fault Tolerance**: Automatic failure detection and recovery

### MCP Integration
- **87+ Tools**: Comprehensive tool ecosystem for AI operations
- **Protocol Support**: Full MCP (Model Context Protocol) implementation
- **Tool Discovery**: Dynamic tool loading and metadata
- **Batch Operations**: Execute multiple tools concurrently

### Modern Architecture
- **Async-First**: Built on Python AsyncIO for high performance
- **Type Safe**: Comprehensive type hints with Pydantic validation
- **Configurable**: YAML-based configuration with environment overrides
- **Observable**: Structured logging with performance metrics

## 🚀 Quick Example

```python
import asyncio
from cleverclaude import CleverClaudeApp, AgentManager, SwarmCoordinator

async def main():
    # Initialize CleverClaude
    app = CleverClaudeApp()
    await app.initialize()
    
    # Create agents
    researcher = await app.agents.create_agent(
        agent_type="researcher",
        name="Research Agent",
        capabilities={"research", "analysis", "documentation"}
    )
    
    # Create swarm
    swarm_id = await app.swarms.create_swarm(
        name="Research Swarm",
        topology="mesh"
    )
    
    # Add agent to swarm
    await app.swarms.add_agent(swarm_id, researcher)
    
    # Execute task
    task = {
        "type": "research_query",
        "data": {
            "query": "Latest developments in AI agent coordination",
            "scope": "academic_papers",
            "depth": "comprehensive"
        }
    }
    
    result = await app.swarms.submit_task(swarm_id, task)
    print(f"Research completed: {result}")

if __name__ == "__main__":
    asyncio.run(main())
```

## 📦 Installation

```bash
# Install with uv (recommended)
uv pip install cleverclaude

# Or with pip
pip install cleverclaude

# Development installation
git clone https://github.com/your-org/cleverclaude.git
cd cleverclaude
uv pip install -e .[dev]
```

## 🛠️ CLI Usage

```bash
# Initialize new project
cleverclaude init my-project

# Start the orchestration system
cleverclaude start

# Check system status
cleverclaude status

# Monitor real-time metrics
cleverclaude monitor --watch
```

## 📖 Learn More

- **[Architecture Guide](architecture.md)**: Deep dive into system design
- **[Agent Development](agents.md)**: Creating custom agent types
- **[Swarm Patterns](swarms.md)**: Advanced coordination strategies  
- **[MCP Tools](mcp.md)**: Leveraging the 87+ tool ecosystem
- **[Production Deployment](deployment.md)**: Scaling CleverClaude

## 🤝 Community

- **GitHub**: [CleverClaude Repository](https://github.com/your-org/cleverclaude)
- **Documentation**: [docs.cleverclaude.ai](https://docs.cleverclaude.ai)
- **Discord**: [CleverClaude Community](https://discord.gg/cleverclaude)
- **Issues**: [Bug Reports & Feature Requests](https://github.com/your-org/cleverclaude/issues)

## 📄 License

CleverClaude is released under the MIT License. See [LICENSE](../LICENSE) for details.