name	performance-analysis
version	1.0.0
description	Comprehensive performance analysis, bottleneck detection, and optimization recommendations for Claude Flow swarms
category	monitoring
tags	["performance","bottleneck","optimization","profiling","metrics","analysis"]
author	Claude Flow Team

Performance Analysis Skill

Comprehensive performance analysis suite for identifying bottlenecks, profiling swarm operations, generating detailed reports, and providing actionable optimization recommendations.

Overview

This skill consolidates all performance analysis capabilities:

Bottleneck Detection: Identify performance bottlenecks across communication, processing, memory, and network
Performance Profiling: Real-time monitoring and historical analysis of swarm operations
Report Generation: Create comprehensive performance reports in multiple formats
Optimization Recommendations: AI-powered suggestions for improving performance

Quick Start

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

Executive Summary
- Overall performance score
- Key metrics overview
- Critical findings
Swarm Overview
- Topology configuration
- Agent distribution
- Task statistics
Performance Metrics
- Execution times
- Throughput analysis
- Resource utilization
- Latency breakdown
Bottleneck Analysis
- Identified bottlenecks
- Impact assessment
- Optimization priorities
Comparative Analysis (when --compare used)
- Performance trends
- Improvement metrics
- Regression detection
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
name: Performance Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions$checkout@v2
      - name: Run Performance Analysis
        run: |
          npx claude-flow analysis performance-report \
            --format json \
            --output performance.json
      - name: Check Performance Thresholds
        run: |
          npx claude-flow bottleneck detect \
            --threshold 15 \
            --export bottlenecks.json
      - name: Upload Reports
        uses: actions$upload-artifact@v2
        with:
          name: performance-reports
          path: |
            performance.json
            bottlenecks.json

Custom Analysis Scripts

// scripts$analyze-performance.js
const { exec } = require('child_process');
const fs = require('fs');

async function analyzePerformance() {
  // Run bottleneck detection
  const bottlenecks = await runCommand(
    'npx claude-flow bottleneck detect --format json'
  );

  // Generate performance report
  const report = await runCommand(
    'npx claude-flow analysis performance-report --format json'
  );

  // Analyze results
  const analysis = {
    bottlenecks: JSON.parse(bottlenecks),
    performance: JSON.parse(report),
    timestamp: new Date().toISOString()
  };

  // Save combined analysis
  fs.writeFileSync(
    'analysis$combined-report.json',
    JSON.stringify(analysis, null, 2)
  );

  // Generate alerts if needed
  if (analysis.bottlenecks.critical.length > 0) {
    console.error('CRITICAL: Performance bottlenecks detected!');
    process.exit(1);
  }
}

function runCommand(cmd) {
  return new Promise((resolve, reject) => {
    exec(cmd, (error, stdout, stderr) => {
      if (error) reject(error);
      else resolve(stdout);
    });
  });
}

analyzePerformance().catch(console.error);

Best Practices

1. Regular Analysis

Run bottleneck detection after major changes
Generate weekly performance reports
Monitor trends over time
Set up automated alerts

2. Threshold Tuning

Start with default threshold (20%)
Lower for production systems (10-15%)
Higher for development (25-30%)
Adjust based on requirements

3. Fix Strategy

Always review before applying --fix
Test fixes in development first
Apply fixes incrementally
Monitor impact after changes

4. Report Integration

Include in documentation
Share with team regularly
Track improvements over time
Use for capacity planning

5. Continuous Optimization

Learn from each analysis
Build performance budgets
Establish baselines
Set improvement goals

Troubleshooting

Common Issues

High Memory Usage

# Analyze memory bottlenecks
npx claude-flow bottleneck detect --threshold 10

# Check cache performance
npx claude-flow cache manage --action stats

# Review memory metrics
npx claude-flow memory usage

Slow Task Execution

# Identify slow tasks
npx claude-flow task status --detailed

# Analyze coordination overhead
npx claude-flow bottleneck detect --time-range 1h

# Check agent utilization
npx claude-flow agent metrics

Poor Cache Performance

# Analyze cache hit rates
npx claude-flow analysis performance-report --sections metrics

# Review cache strategy
npx claude-flow cache manage --action analyze

# Enable cache warming
npx claude-flow bottleneck detect --fix

Integration with Other Skills

swarm-orchestration: Use performance data to optimize topology
memory-management: Improve cache strategies based on analysis
task-coordination: Adjust scheduling based on bottlenecks
neural-training: Train patterns from performance data

Related Commands

npx claude-flow swarm monitor - Real-time monitoring
npx claude-flow token usage - Token optimization analysis
npx claude-flow cache manage - Cache optimization
npx claude-flow agent metrics - Agent performance metrics
npx claude-flow task status - Task execution analysis