Performance Analysis

Basic Bottleneck Detection

npx claude-flow bottleneck detect

Generate Performance Report

npx claude-flow analysis performance-report --format html --include-metrics

Analyze and Auto-Fix

npx claude-flow bottleneck detect --fix --threshold 15

Core Capabilities

1. Bottleneck Detection

Command Syntax

npx claude-flow bottleneck detect [options]

Options

• --swarm-id, -s <id> - Analyze specific swarm (default: current)
• --time-range, -t <range> - Analysis period: 1h, 24h, 7d, all (default: 1h)
• --threshold <percent> - Bottleneck threshold percentage (default: 20)
• --export, -e <file> - Export analysis to file
• --fix - Apply automatic optimizations

Usage Examples

# Basic detection for current swarm
npx claude-flow bottleneck detect

# Analyze specific swarm over 24 hours
npx claude-flow bottleneck detect --swarm-id swarm-123 -t 24h

# Export detailed analysis
npx claude-flow bottleneck detect -t 24h -e bottlenecks.json

# Auto-fix detected issues
npx claude-flow bottleneck detect --fix --threshold 15

# Low threshold for sensitive detection
npx claude-flow bottleneck detect --threshold 10 --export critical-issues.json

Metrics Analyzed

Communication Bottlenecks:

• Message queue delays
• Agent response times
• Coordination overhead
• Memory access patterns
• Inter-agent communication latency

Processing Bottlenecks:

• Task completion times
• Agent utilization rates
• Parallel execution efficiency
• Resource contention
• CPU/memory usage patterns

Memory Bottlenecks:

• Cache hit rates
• Memory access patterns
• Storage I/O performance
• Neural pattern loading times
• Memory allocation efficiency

Network Bottlenecks:

• API call latency
• MCP communication delays
• External service timeouts
• Concurrent request limits
• Network throughput issues

Output Format

🔍 Bottleneck Analysis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Summary
├── Time Range: Last 1 hour
├── Agents Analyzed: 6
├── Tasks Processed: 42
└── Critical Issues: 2

🚨 Critical Bottlenecks
1. Agent Communication (35% impact)
   └── coordinator → coder-1 messages delayed by 2.3s avg

2. Memory Access (28% impact)
   └── Neural pattern loading taking 1.8s per access

⚠️ Warning Bottlenecks
1. Task Queue (18% impact)
   └── 5 tasks waiting > 10s for assignment

💡 Recommendations
1. Switch to hierarchical topology (est. 40% improvement)
2. Enable memory caching (est. 25% improvement)
3. Increase agent concurrency to 8 (est. 20% improvement)

✅ Quick Fixes Available
Run with --fix to apply:
- Enable smart caching
- Optimize message routing
- Adjust agent priorities

2. Performance Profiling

Real-time Detection

Automatic analysis during task execution:

• Execution time vs. complexity
• Agent utilization rates
• Resource constraints
• Operation patterns

Common Bottleneck Patterns

Time Bottlenecks:

• Tasks taking > 5 minutes
• Sequential operations that could parallelize
• Redundant file operations
• Inefficient algorithm implementations

Coordination Bottlenecks:

• Single agent for complex tasks
• Unbalanced agent workloads
• Poor topology selection
• Excessive synchronization points

Resource Bottlenecks:

• High operation count (> 100)
• Memory constraints
• I/O limitations
• Thread pool saturation

MCP Integration

// Check for bottlenecks in Claude Code
mcp__claude-flow__bottleneck_detect({
  timeRange: "1h",
  threshold: 20,
  autoFix: false
})

// Get detailed task results with bottleneck analysis
mcp__claude-flow__task_results({
  taskId: "task-123",
  format: "detailed"
})

Result Format:

{
  "bottlenecks": [
    {
      "type": "coordination",
      "severity": "high",
      "description": "Single agent used for complex task",
      "recommendation": "Spawn specialized agents for parallel work",
      "impact": "35%",
      "affectedComponents": ["coordinator", "coder-1"]
    }
  ],
  "improvements": [
    {
      "area": "execution_time",
      "suggestion": "Use parallel task execution",
      "expectedImprovement": "30-50% time reduction",
      "implementationSteps": [
        "Split task into smaller units",
        "Spawn 3-4 specialized agents",
        "Use mesh topology for coordination"
      ]
    }
  ],
  "metrics": {
    "avgExecutionTime": "142s",
    "agentUtilization": "67%",
    "cacheHitRate": "82%",
    "parallelizationFactor": 1.2
  }
}

3. Report Generation

Command Syntax

npx claude-flow analysis performance-report [options]

Options

• --format <type> - Report format: json, html, markdown (default: markdown)
• --include-metrics - Include detailed metrics and charts
• --compare <id> - Compare with previous swarm
• --time-range <range> - Analysis period: 1h, 24h, 7d, 30d, all
• --output <file> - Output file path
• --sections <list> - Comma-separated sections to include

Report Sections

1. Executive Summary

   • Overall performance score
   • Key metrics overview
   • Critical findings

2. Swarm Overview

   • Topology configuration
   • Agent distribution
   • Task statistics

3. Performance Metrics

   • Execution times
   • Throughput analysis
   • Resource utilization
   • Latency breakdown

4. Bottleneck Analysis

   • Identified bottlenecks
   • Impact assessment
   • Optimization priorities

5. Comparative Analysis (when --compare used)

   • Performance trends
   • Improvement metrics
   • Regression detection

6. Recommendations

   • Prioritized action items
   • Expected improvements
   • Implementation guidance

Usage Examples

# Generate HTML report with all metrics
npx claude-flow analysis performance-report --format html --include-metrics

# Compare current swarm with previous
npx claude-flow analysis performance-report --compare swarm-123 --format markdown

# Custom output with specific sections
npx claude-flow analysis performance-report \
  --sections summary,metrics,recommendations \
  --output reports/perf-analysis.html \
  --format html

# Weekly performance report
npx claude-flow analysis performance-report \
  --time-range 7d \
  --include-metrics \
  --format markdown \
  --output docs/weekly-performance.md

# JSON format for CI/CD integration
npx claude-flow analysis performance-report \
  --format json \
  --output build/performance.json

Sample Markdown Report

# Performance Analysis Report

## Executive Summary
- **Overall Score**: 87/100
- **Analysis Period**: Last 24 hours
- **Swarms Analyzed**: 3
- **Critical Issues**: 1

## Key Metrics
| Metric | Value | Trend | Target |
|--------|-------|-------|--------|
| Avg Task Time | 42s | ↓ 12% | 35s |
| Agent Utilization | 78% | ↑ 5% | 85% |
| Cache Hit Rate | 91% | → | 90% |
| Parallel Efficiency | 2.3x | ↑ 0.4x | 2.5x |

## Bottleneck Analysis
### Critical
1. **Agent Communication Delay** (Impact: 35%)
   - Coordinator → Coder messages delayed by 2.3s avg
   - **Fix**: Switch to hierarchical topology

### Warnings
1. **Memory Access Pattern** (Impact: 18%)
   - Neural pattern loading: 1.8s per access
   - **Fix**: Enable memory caching

## Recommendations
1. **High Priority**: Switch to hierarchical topology (40% improvement)
2. **Medium Priority**: Enable memory caching (25% improvement)
3. **Low Priority**: Increase agent concurrency to 8 (20% improvement)

4. Optimization Recommendations

Automatic Fixes

When using --fix, the following optimizations may be applied:

1. Topology Optimization

• Switch to more efficient topology (mesh → hierarchical)
• Adjust communication patterns
• Reduce coordination overhead
• Optimize message routing

2. Caching Enhancement

• Enable memory caching
• Optimize cache strategies
• Preload common patterns
• Implement cache warming

3. Concurrency Tuning

• Adjust agent counts
• Optimize parallel execution
• Balance workload distribution
• Implement load balancing

4. Priority Adjustment

• Reorder task queues
• Prioritize critical paths
• Reduce wait times
• Implement fair scheduling

5. Resource Optimization

• Optimize memory usage
• Reduce I/O operations
• Batch API calls
• Implement connection pooling

Performance Impact

Typical improvements after bottleneck resolution:

• Communication: 30-50% faster message delivery
• Processing: 20-40% reduced task completion time
• Memory: 40-60% fewer cache misses
• Network: 25-45% reduced API latency
• Overall: 25-45% total performance improvement

Advanced Usage

Continuous Monitoring

# Monitor performance in real-time
npx claude-flow swarm monitor --interval 5

# Generate hourly reports
while true; do
  npx claude-flow analysis performance-report \
    --format json \
    --output logs/perf-$(date +%Y%m%d-%H%M).json
  sleep 3600
done

CI/CD Integration

# .github/workflows/performance.yml