cleverclaude-core/docs/quickstart.md

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)

# 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

pip install cleverclaude

Option 3: Development Install

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

# 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

# Copy environment template
cp .env.example .env

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

Basic configuration:

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

# 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

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

Or create your own:

# 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

# 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

# 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

# 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

# Basic status
cleverclaude status

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

# Watch for changes
cleverclaude status --watch

View Logs

# 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

# 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: Create custom agent types
2. Swarm Patterns: Learn advanced coordination strategies
3. MCP Tools: Leverage the 87+ tool ecosystem
4. Workflow Automation: Build complex task pipelines
5. Production Deployment: Scale for production usage

❓ Troubleshooting

Common Issues

"Command not found: cleverclaude"

# Make sure CleverClaude is in your PATH
which cleverclaude

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

"Connection refused" errors

# Check if services are running
cleverclaude status

# Restart services
cleverclaude start --force-restart

"Permission denied" on configuration

# Fix permissions
chmod -R 755 .cleverclaude/

For more troubleshooting, see the Troubleshooting Guide.

🤝 Getting Help

• Documentation: docs.cleverclaude.ai
• GitHub Issues: Report bugs or request features
• Discord Community: Join the discussion
• Examples Repository: More examples and tutorials

Happy orchestrating! 🎉