- 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
- Analyze specific swarm (default: current) --time-range, -t - Analysis period: 1h, 24h, 7d, all (default: 1h) --threshold - Bottleneck threshold percentage (default: 20) --export, -e - 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
- 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
- See Also
- Bottleneck Detection Guide
- Performance Report Guide
- Performance Bottlenecks Overview
- Swarm Monitoring Documentation
- Memory Management Documentation
- Version
-
- 1.0.0
- Last Updated
-
- 2025-10-19
- Maintainer
- Claude Flow Team