Your Name
389 lines
9.0 KiB
Markdown
389 lines
9.0 KiB
Markdown
# 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! 🎉 |