Claude Code Server Health Check Command - Smart persistent server monitoring

README.md

Claude Code Server Health Check Command

A smart, persistent server health monitoring slash command for Claude Code that learns and remembers your server characteristics.

🚀 Features

• Smart Discovery: Automatically identifies server type (web, database, application, mixed)
• Persistent Profiling: Remembers server characteristics for faster subsequent checks
• Optimized Checks: Runs targeted health checks based on server role
• Baseline Tracking: Tracks typical metrics for anomaly detection
• Quick & Full Modes: Fast checks for known servers, comprehensive scans when needed

📦 Installation

Quick Install (Recommended)

curl -fsSL https://gist.githubusercontent.com/neilberget/[GIST-ID]/raw/install.sh | bash

Manual Install

1. Create directories:

   mkdir -p ~/.claude/commands ~/.claude/server-profiles

2. Download and save check-server.md to ~/.claude/commands/

3. The command is ready to use in Claude Code!

📚 Usage

Basic Usage

/check-server <hostname>

Examples

/check-server play-db        # Quick check using saved profile
/check-server play-db --full # Full discovery and comprehensive check
/check-server web-01         # First run will discover and profile

🧠 How It Works

First Run (Discovery Mode)

• Detects installed services (nginx, mysql, docker, etc.)
• Identifies server role (web, database, application, mixed)
• Creates a profile in ~/.claude/server-profiles/<hostname>.json
• Runs comprehensive health check

Subsequent Runs (Optimized Mode)

• Loads saved profile
• Runs targeted checks specific to server type
• Updates metrics and profile
• Much faster than full discovery

Server Profile Example

{
  "hostname": "play-db",
  "type": "database",
  "discovered_services": {
    "webserver": "none",
    "database": "mysql",
    "runtime": "none",
    "container": "none"
  },
  "optimized_checks": [
    "mysql -e 'SHOW STATUS WHERE Variable_name IN (\"Threads_connected\", \"Slow_queries\");'"
  ],
  "last_checked": "2025-08-22T15:20:00Z",
  "typical_metrics": {
    "avg_load": 0.10,
    "avg_memory_used_gb": 0.7
  }
}

🎯 Server Types & Checks

Database Server (MySQL/PostgreSQL)

• Connection count and active queries
• Slow query analysis
• Database-specific performance metrics
• Replication status (if applicable)

Web Server (Nginx/Apache)

• Service status and active connections
• Error rate from access logs
• SSL certificate status
• Disk space on web directories

Application Server

• Process monitoring
• Runtime-specific checks (PHP-FPM, Node.js, Python)
• Queue sizes and background jobs
• Application logs

Mixed/Custom

• Combines relevant checks from multiple types
• Custom commands based on discovered services

🔧 Customization

Force Full Discovery

Use --full flag to re-profile a server:

/check-server hostname --full

Manual Profile Editing

Edit profiles directly at ~/.claude/server-profiles/<hostname>.json

Adding Custom Checks

Add commands to the optimized_checks array in server profiles.

📁 File Structure

~/.claude/
├── commands/
│   └── check-server.md              # Command definition
└── server-profiles/
    ├── hostname1.json               # Server profile
    ├── hostname2.json               # Server profile
    └── ...

🆘 Troubleshooting

Command Not Found

Ensure the file is at ~/.claude/commands/check-server.md and restart Claude Code.

SSH Issues

Verify SSH key authentication is configured for your servers.

Profile Issues

Delete profile files in ~/.claude/server-profiles/ to force re-discovery.

🤝 Contributing

Found a bug or want to add a feature? Create an issue or submit a pull request!

📄 License

MIT License - Feel free to modify and distribute.

check-server.md

description	argument-hint	allowed-tools
Check server health with persistent learning of server characteristics	hostname [--full] (e.g., play-app, play-db)	Bash, TodoWrite, Read, Write, Edit

Perform a health check on server: $ARGUMENTS

Step 1: Check for Saved Server Profile

First, check if we have a saved profile for this server: @~/.claude/server-profiles/$ARGUMENTS.json

If the profile exists and --full is NOT in arguments, use optimized checks. If no profile exists OR --full flag is present, perform full discovery.

Step 2: Discovery Mode (First Run or --full)

If discovering server type, run:

! ssh $ARGUMENTS "which nginx apache2 httpd mysql mysqld psql postgres docker 2>/dev/null | head -10"
! ssh $ARGUMENTS "systemctl list-units --state=running --no-pager 2>/dev/null | grep -E 'nginx|apache|mysql|mariadb|postgres|docker|php-fpm|node|python' | cut -d' ' -f1"

Based on discovery, create/update profile at ~/.claude/server-profiles/$ARGUMENTS.json:

{
  "hostname": "server-name",
  "type": "web|database|application|mixed",
  "discovered_services": {
    "webserver": "nginx|apache|none",
    "database": "mysql|postgresql|none", 
    "runtime": "php-fpm|node|python|none",
    "container": "docker|none"
  },
  "optimized_checks": ["service-specific-commands"],
  "last_checked": "ISO-8601-timestamp",
  "typical_metrics": {
    "avg_load": 0.0,
    "avg_memory_used_gb": 0.0
  }
}

Step 3: Optimized Checks for Known Servers

For servers with profiles, run targeted checks:

If Web Server (nginx/apache):

• Service status and active connections
• Error rate from access logs
• Disk space on web root

If Database Server (mysql/postgresql):

• Connection count and slow queries
• Database specific performance metrics
• Replication lag if applicable

If Mixed/Application Server:

• All relevant service checks
• Process monitoring
• Queue sizes if applicable

Step 4: Core Health Checks (Always Run)

Essential checks regardless of server type:

1. System: uptime, load average
2. Memory: Free memory and swap usage
3. Disk: Usage on primary partition
4. Critical Alerts: Disk >90%, Memory <10%, Load >CPU count

Step 5: Update Profile and Report

After checks:

1. Update profile with latest timestamp and any new services found
2. Track baseline metrics for anomaly detection
3. Save profile back to ~/.claude/server-profiles/$ARGUMENTS.json

Output format:

• For known servers: Quick targeted summary
• For new/full scan: Comprehensive report with discovered services
• Always show: Health status (✅/⚠️/❌) and any critical issues

The profile system will make subsequent checks faster and more relevant to each specific server's role.

claude-check-server-install.sh

#!/bin/bash

# Claude Code Server Health Check Command Installer
# https://github.com/neilberget
# 
# This script installs the /check-server command for Claude Code
# It creates a smart health check command with server profiling

set -e

echo "🚀 Installing Claude Code /check-server command..."

# Create necessary directories
echo "Creating directories..."
mkdir -p ~/.claude/commands
mkdir -p ~/.claude/server-profiles

# Download and install the command file
echo "Installing check-server command..."
cat > ~/.claude/commands/check-server.md << 'EOF'
---
description: Check server health with persistent learning of server characteristics
argument-hint: hostname [--full] (e.g., play-app, play-db)
allowed-tools: Bash, TodoWrite, Read, Write, Edit
---

Perform a health check on server: $ARGUMENTS

## Step 1: Check for Saved Server Profile

First, check if we have a saved profile for this server:
@~/.claude/server-profiles/$ARGUMENTS.json

If the profile exists and --full is NOT in arguments, use optimized checks.
If no profile exists OR --full flag is present, perform full discovery.

## Step 2: Discovery Mode (First Run or --full)

If discovering server type, run:
```bash
! ssh $ARGUMENTS "which nginx apache2 httpd mysql mysqld psql postgres docker 2>/dev/null | head -10"
! ssh $ARGUMENTS "systemctl list-units --state=running --no-pager 2>/dev/null | grep -E 'nginx|apache|mysql|mariadb|postgres|docker|php-fpm|node|python' | cut -d' ' -f1"
```

Based on discovery, create/update profile at `~/.claude/server-profiles/$ARGUMENTS.json`:
```json
{
  "hostname": "server-name",
  "type": "web|database|application|mixed",
  "discovered_services": {
    "webserver": "nginx|apache|none",
    "database": "mysql|postgresql|none", 
    "runtime": "php-fpm|node|python|none",
    "container": "docker|none"
  },
  "optimized_checks": ["service-specific-commands"],
  "last_checked": "ISO-8601-timestamp",
  "typical_metrics": {
    "avg_load": 0.0,
    "avg_memory_used_gb": 0.0
  }
}
```

## Step 3: Optimized Checks for Known Servers

For servers with profiles, run targeted checks:

### If Web Server (nginx/apache):
- Service status and active connections
- Error rate from access logs
- Disk space on web root

### If Database Server (mysql/postgresql):
- Connection count and slow queries
- Database specific performance metrics
- Replication lag if applicable

### If Mixed/Application Server:
- All relevant service checks
- Process monitoring
- Queue sizes if applicable

## Step 4: Core Health Checks (Always Run)

Essential checks regardless of server type:
1. **System**: `uptime`, load average
2. **Memory**: Free memory and swap usage
3. **Disk**: Usage on primary partition
4. **Critical Alerts**: Disk >90%, Memory <10%, Load >CPU count

## Step 5: Update Profile and Report

After checks:
1. Update profile with latest timestamp and any new services found
2. Track baseline metrics for anomaly detection
3. Save profile back to `~/.claude/server-profiles/$ARGUMENTS.json`

Output format:
- For known servers: Quick targeted summary
- For new/full scan: Comprehensive report with discovered services
- Always show: Health status (✅/⚠️/❌) and any critical issues

The profile system will make subsequent checks faster and more relevant to each specific server's role.
EOF

echo "✅ Installation complete!"
echo ""
echo "📚 Usage:"
echo "  In Claude Code, type: /check-server <hostname>"
echo "  Examples:"
echo "    /check-server play-db        # Quick check using saved profile"
echo "    /check-server play-db --full # Full discovery and check"
echo ""
echo "📁 Files created:"
echo "  - ~/.claude/commands/check-server.md (command definition)"
echo "  - ~/.claude/server-profiles/ (server profiles directory)"
echo ""
echo "🔍 The command will:"
echo "  • Learn and remember server types (web, database, etc.)"
echo "  • Run optimized checks based on server role"
echo "  • Track baseline metrics for anomaly detection"
echo "  • Speed up subsequent health checks"