/health

name: health
description: Show agent health and metrics
type: command

Agent Health Command

Monitor agent health status, resource usage, and detect issues.

Usage

npx claude-flow agent health [agent-id] [options]

Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | `--watch` | `-w` | Continuous monitoring | false | | `--interval` | `-i` | Watch interval in seconds | 5 | | `--format` | | Output format (table, json) | table |

Examples

# Overall health check
npx claude-flow agent health

# Specific agent health
npx claude-flow agent health coder-lx7m9k2

# Continuous monitoring
npx claude-flow agent health --watch

# Custom interval
npx claude-flow agent health -w -i 10

# JSON output
npx claude-flow agent health --format json

Output

Agent Health Status

Overall: HEALTHY

+--------------------+---------+--------+--------+---------+
| Agent              | Status  | Memory | CPU    | Tasks   |
+--------------------+---------+--------+--------+---------+
| coder-lx7m9k2      | healthy | 45MB   | 2.3%   | 5/5     |
| researcher-abc123  | healthy | 38MB   | 1.8%   | 3/3     |
| tester-def456      | warning | 120MB  | 8.5%   | 12/14   |
+--------------------+---------+--------+--------+---------+

Alerts
  - tester-def456: High memory usage (120MB > 100MB threshold)
  - tester-def456: Task failure rate above threshold (14.3%)

Recommendations
  - Consider restarting tester-def456
  - Review failed tasks for error patterns

Health Status Values

| Status | Description | |--------|-------------| | `healthy` | All metrics within normal range | | `warning` | Some metrics approaching thresholds | | `critical` | Metrics exceeded critical thresholds | | `unknown` | Unable to determine health |

Health Checks

Resource Checks

• Memory usage vs threshold
• CPU utilization
• Active connections
• Queue depth

Performance Checks

• Response time
• Task success rate
• Error frequency
• Throughput

Connectivity Checks

• MCP server connection
• Memory backend
• Neural services
• Swarm coordination

Watch Mode

Continuous monitoring with real-time updates:

npx claude-flow agent health --watch

# Output updates every 5 seconds:
# [10:30:15] Agent Health: 3 healthy, 0 warning, 0 critical
# [10:30:20] Agent Health: 3 healthy, 0 warning, 0 critical
# [10:30:25] Agent Health: 2 healthy, 1 warning, 0 critical
#   - tester-def456: Memory usage increased to 115MB

Press `Ctrl+C` to stop watching.

JSON Output

{
  "overall": "healthy",
  "agents": [
    {
      "id": "coder-lx7m9k2",
      "status": "healthy",
      "metrics": {
        "memoryMB": 45,
        "cpuPercent": 2.3,
        "tasksCompleted": 5,
        "tasksTotal": 5
      }
    }
  ],
  "alerts": [],
  "recommendations": []
}

Related Commands

• `npx claude-flow agent status` - Detailed agent info
• `npx claude-flow agent metrics` - Performance metrics
• `npx claude-flow doctor` - System-wide health