# CleverClaude Quick Start Guide

Get up and running with CleverClaude in minutes! This guide walks you through creating your first AI agent swarm.

## 📋 Prerequisites

- Python 3.11+ 
- Git (optional, for development)
- Redis server (for production usage)
- PostgreSQL (for production usage)

## 🚀 Installation

### Option 1: Quick Install with uv (Recommended)

```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install CleverClaude
uv pip install cleverclaude

# Verify installation
cleverclaude --version
```

### Option 2: Standard pip Install

```bash
pip install cleverclaude
```

### Option 3: Development Install

```bash
git clone https://github.com/your-org/cleverclaude.git
cd cleverclaude
uv venv
source .venv/bin/activate
uv pip install -e .[dev]
```

## 🏁 Your First CleverClaude Project

### Step 1: Initialize a New Project

```bash
# Create a new CleverClaude project
cleverclaude init my-first-project

# Navigate to the project directory
cd my-first-project

# Explore the generated structure
ls -la
```

This creates:
```
my-first-project/
├── .cleverclaude/          # Configuration directory
│   ├── config.yaml        # Main configuration
│   ├── data/              # Data storage
│   ├── logs/              # Application logs
│   └── cache/             # Cache directory
├── agents/                # Custom agent definitions
├── tasks/                 # Task definitions
├── workflows/             # Workflow templates
├── memory/                # Persistent memory
├── examples/              # Example code
│   ├── basic_agent.py     # Single agent example
│   ├── swarm_coordination.py  # Multi-agent swarm
│   └── task_orchestration.py  # Complex workflows
├── .env.example           # Environment variables
└── docker-compose.yml     # Optional Docker setup
```

### Step 2: Configure Your Environment

```bash
# Copy environment template
cp .env.example .env

# Edit configuration (optional)
nano .cleverclaude/config.yaml
```

Basic configuration:
```yaml
app:
  name: "My First Project"
  environment: "development"
  debug: true

agents:
  max_agents: 10
  default_timeout: 300

swarm:
  default_topology: "mesh"
  max_swarm_size: 5

api:
  host: "127.0.0.1"
  port: 8000
```

### Step 3: Start CleverClaude

```bash
# Start the orchestration system
cleverclaude start

# Or start in the background
cleverclaude start --daemon

# Check if it's running
cleverclaude status
```

You should see:
```
🧠 CleverClaude System Status

System Health:     ✅ Healthy
Uptime:           00:01:23
Version:          2.0.0

Agents:           0 active, 0 total
Swarms:           0 active, 0 total  
Tasks:            0 completed, 0 running

API Server:       http://127.0.0.1:8000
Documentation:    http://127.0.0.1:8000/docs
```

## 👨‍💻 Run Your First Example

### Example 1: Single Agent Task

```bash
# Run the basic agent example
python examples/basic_agent.py
```

Or create your own:

```python
# my_first_agent.py
import asyncio
from cleverclaude import AgentManager, settings
from cleverclaude.agents.types import AgentType

async def main():
    # Initialize agent manager
    manager = AgentManager(settings.agents, None)
    await manager.initialize()
    
    # Create a researcher agent
    agent_id = await manager.create_agent(
        agent_type=AgentType.RESEARCHER,
        name="My First Agent",
        capabilities={"research", "analysis", "documentation"}
    )
    
    print(f"✅ Created agent: {agent_id}")
    
    # Execute a task
    task = {
        "id": "first_task",
        "type": "research_query",
        "data": {
            "query": "What are the benefits of AI agent coordination?",
            "scope": "general",
            "depth": "standard"
        }
    }
    
    result = await manager.execute_task(task, agent_id=agent_id)
    print(f"📋 Task completed: {result['status']}")
    
    # Clean up
    await manager.destroy_agent(agent_id)
    await manager.shutdown()

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

### Example 2: Multi-Agent Swarm

```python
# my_first_swarm.py
import asyncio
from cleverclaude import SwarmCoordinator, AgentManager, settings
from cleverclaude.agents.types import AgentType
from cleverclaude.coordination.types import SwarmTask, TaskPriority

async def main():
    # Initialize systems
    agent_manager = AgentManager(settings.agents, None)
    await agent_manager.initialize()
    
    coordinator = SwarmCoordinator(settings.swarm, None, agent_manager)
    await coordinator.initialize()
    
    # Create swarm
    swarm_id = await coordinator.create_swarm(
        name="My First Swarm",
        topology="mesh"
    )
    
    # Add agents
    agents = []
    for i, agent_type in enumerate([AgentType.RESEARCHER, AgentType.ANALYST, AgentType.CODER]):
        agent_id = await agent_manager.create_agent(
            agent_type=agent_type,
            name=f"Agent-{i+1}"
        )
        agents.append(agent_id)
        await coordinator.add_agent(swarm_id, agent_id, role="worker")
    
    print(f"✅ Created swarm with {len(agents)} agents")
    
    # Submit tasks
    tasks = []
    for i in range(3):
        task = SwarmTask(
            task_type="analysis",
            priority=TaskPriority.NORMAL,
            data={
                "analysis_type": "data_analysis",
                "dataset": {"records": [f"data_{j}" for j in range(5)]},
                "task_number": i
            }
        )
        task_id = await coordinator.submit_task(swarm_id, task)
        tasks.append(task_id)
    
    print(f"📋 Submitted {len(tasks)} tasks")
    
    # Wait for completion
    await asyncio.sleep(3)
    
    # Get metrics
    metrics = await coordinator.get_swarm_metrics(swarm_id)
    print(f"📊 Swarm metrics:")
    print(f"   Completed tasks: {metrics.completed_tasks}")
    print(f"   Efficiency: {metrics.efficiency_score:.1f}%")
    
    # Cleanup
    await coordinator.destroy_swarm(swarm_id)
    await coordinator.shutdown()
    await agent_manager.shutdown()

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

## 🔧 Using the CLI

### Basic Commands

```bash
# Get help
cleverclaude --help

# Initialize project with specific template
cleverclaude init --template production my-prod-project

# Start with custom configuration
cleverclaude start --config-dir ./custom-config --port 9000

# Monitor system in real-time
cleverclaude status --watch --interval 5

# Get detailed status in JSON
cleverclaude status --format json
```

### Configuration Management

```bash
# Validate configuration
cleverclaude config validate

# Show current configuration
cleverclaude config show

# Update configuration
cleverclaude config set agents.max_agents 20
cleverclaude config set swarm.default_topology hierarchical
```

## 🌐 Using the Web Interface

When CleverClaude is running, you can access:

- **Main Dashboard**: http://127.0.0.1:8000
- **API Documentation**: http://127.0.0.1:8000/docs
- **Metrics**: http://127.0.0.1:8000/metrics
- **Health Check**: http://127.0.0.1:8000/health

## 🔍 Monitoring and Debugging

### Check System Health

```bash
# Basic status
cleverclaude status

# Detailed system information
cleverclaude status --format table --verbose

# Watch for changes
cleverclaude status --watch
```

### View Logs

```bash
# View recent logs
tail -f .cleverclaude/logs/cleverclaude.log

# Filter by level
grep ERROR .cleverclaude/logs/cleverclaude.log

# View structured JSON logs
cat .cleverclaude/logs/cleverclaude.log | jq '.'
```

### Performance Monitoring

```bash
# Monitor system performance
cleverclaude monitor

# Get performance report
cleverclaude monitor --report --timeframe 1h
```

## 🚀 Next Steps

Now that you have CleverClaude running, explore these advanced topics:

1. **[Agent Development](agents.md)**: Create custom agent types
2. **[Swarm Patterns](swarms.md)**: Learn advanced coordination strategies
3. **[MCP Tools](mcp.md)**: Leverage the 87+ tool ecosystem
4. **[Workflow Automation](workflows.md)**: Build complex task pipelines
5. **[Production Deployment](deployment.md)**: Scale for production usage

## ❓ Troubleshooting

### Common Issues

**"Command not found: cleverclaude"**
```bash
# Make sure CleverClaude is in your PATH
which cleverclaude

# Or run directly with Python
python -m cleverclaude --help
```

**"Connection refused" errors**
```bash
# Check if services are running
cleverclaude status

# Restart services
cleverclaude start --force-restart
```

**"Permission denied" on configuration**
```bash
# Fix permissions
chmod -R 755 .cleverclaude/
```

For more troubleshooting, see the [Troubleshooting Guide](troubleshooting.md).

## 🤝 Getting Help

- **Documentation**: [docs.cleverclaude.ai](https://docs.cleverclaude.ai)
- **GitHub Issues**: [Report bugs or request features](https://github.com/your-org/cleverclaude/issues)
- **Discord Community**: [Join the discussion](https://discord.gg/cleverclaude)
- **Examples Repository**: [More examples and tutorials](https://github.com/your-org/cleverclaude-examples)

Happy orchestrating! 🎉