Performance Analysis

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 swarmnpx claude-flow bottleneck detect
# Analyze specific swarm over 24 hoursnpx claude-flow bottleneck detect --swarm-id swarm-123 -t 24h
# Export detailed analysisnpx claude-flow bottleneck detect -t 24h -e bottlenecks.json
# Auto-fix detected issuesnpx claude-flow bottleneck detect --fix --threshold 15
# Low threshold for sensitive detectionnpx 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 Bottlenecks1. 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 Bottlenecks1. Task Queue (18% impact)   └── 5 tasks waiting > 10s for assignment
💡 Recommendations1. 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 AvailableRun 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 Codemcp__claude-flow__bottleneck_detect({  timeRange: "1h",  threshold: 20,  autoFix: false})
// Get detailed task results with bottleneck analysismcp__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 metricsnpx claude-flow analysis performance-report --format html --include-metrics
# Compare current swarm with previousnpx claude-flow analysis performance-report --compare swarm-123 --format markdown
# Custom output with specific sectionsnpx claude-flow analysis performance-report \  --sections summary,metrics,recommendations \  --output reports$perf-analysis.html \  --format html
# Weekly performance reportnpx claude-flow analysis performance-report \  --time-range 7d \  --include-metrics \  --format markdown \  --output docs$weekly-performance.md
# JSON format for CI/CD integrationnpx 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### Critical1. **Agent Communication Delay** (Impact: 35%)   - Coordinator → Coder messages delayed by 2.3s avg   - **Fix**: Switch to hierarchical topology
### Warnings1. **Memory Access Pattern** (Impact: 18%)   - Neural pattern loading: 1.8s per access   - **Fix**: Enable memory caching
## Recommendations1. **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-timenpx claude-flow swarm monitor --interval 5
# Generate hourly reportswhile true; do  npx claude-flow analysis performance-report \    --format json \    --output logs$perf-$(date +%Y%m%d-%H%M).json  sleep 3600done

CI/CD Integration

# .github$workflows$performance.ymlname: Performance Analysison: [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.jsconst { 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 bottlenecksnpx claude-flow bottleneck detect --threshold 10
# Check cache performancenpx claude-flow cache manage --action stats
# Review memory metricsnpx claude-flow memory usage

Slow Task Execution

# Identify slow tasksnpx claude-flow task status --detailed
# Analyze coordination overheadnpx claude-flow bottleneck detect --time-range 1h
# Check agent utilizationnpx claude-flow agent metrics

Poor Cache Performance

# Analyze cache hit ratesnpx claude-flow analysis performance-report --sections metrics
# Review cache strategynpx claude-flow cache manage --action analyze
# Enable cache warmingnpx 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

See Also

• Bottleneck Detection Guide [blocked]
• Performance Report Guide [blocked]
• Performance Bottlenecks Overview [blocked]
• Swarm Monitoring Documentation [blocked]
• Memory Management Documentation [blocked]

Version: 1.0.0 Last Updated: 2025-10-19 Maintainer: Claude Flow Team