What is wavecap-health?

The WaveCap Health skill is a comprehensive diagnostic and monitoring tool designed to ensure the continuous availability and performance of the WaveCap backend. It empowers users to perform real-time health checks, track stream activity, analyze system logs, and troubleshoot service-level issues, effectively reducing downtime through proactive system oversight.

When should I use wavecap-health?

wavecap-health is useful in the following scenarios: • Real-time Health Monitoring: Quickly verify if the WaveCap backend server is operational and responding to API requests. • Stream Status & Error Diagnosis: Identify specific streams that are stuck, inactive, or reporting errors to maintain seamless data processing. • System Log Analysis: Retrieve and filter recent backend logs to pinpoint the root cause of service failures or configuration conflicts. • Process & Port Verification: Check if the backend process is running and monitor port 8000 to ensure network accessibility. • Service Recovery: Manage and restart the WaveCap macOS Launch Agent directly when the system becomes unresponsive.

name	wavecap-health
description	Check WaveCap server health and system status. Use when the user asks about server status, wants to diagnose issues, check if the backend is running, or get a system overview.

WaveCap Health Skill

Use this skill to check WaveCap server health and diagnose system issues.

Quick Health Check

curl -s http://localhost:8000/api/health | jq

Expected response when healthy:

{"status": "ok"}

If this fails with connection refused, the backend server is not running.

Comprehensive System Status

Get a full system overview including all streams and their states:

curl -s "http://localhost:8000/api/streams?includeTranscriptions=false" | jq '{
  total_streams: length,
  by_status: (group_by(.status) | map({status: .[0].status, count: length})),
  by_source: (group_by(.source) | map({source: .[0].source, count: length})),
  streams: [.[] | {id, name, status, error, source, enabled, lastActivityAt}]
}'

Diagnose Stream Errors

Find streams with errors:

curl -s "http://localhost:8000/api/streams?includeTranscriptions=false" | jq '[.[] | select(.error != null)] | .[] | {id, name, status, error}'

Check Stream Activity

Find streams by last activity time:

curl -s "http://localhost:8000/api/streams?includeTranscriptions=false" | jq '[.[] | select(.lastActivityAt != null)] | sort_by(.lastActivityAt) | reverse | .[] | {name, status, lastActivityAt}'

Check Inactive Streams

Find enabled streams that haven't had activity recently:

curl -s "http://localhost:8000/api/streams?includeTranscriptions=false" | jq --arg cutoff "$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" '[.[] | select(.enabled == true and (.lastActivityAt == null or .lastActivityAt < $cutoff))] | .[] | {id, name, status, lastActivityAt}'

Backend Logs

Check the backend log file for errors:

tail -100 /Users/thw/Projects/WaveCap/state/backend.log | grep -i error

Recent log entries:

tail -50 /Users/thw/Projects/WaveCap/state/backend.log

Check Running Processes

Verify the backend process is running:

pgrep -f "uvicorn.*wavecap" && echo "Backend is running" || echo "Backend is NOT running"

Check what's listening on port 8000:

lsof -i :8000 | head -5

Server Configuration

View current server config:

curl -s http://localhost:8000/api/ui-config | jq

View logging config:

curl -s http://localhost:8000/api/logging-config | jq

Common Issues

Connection Refused

Backend server is not running
Check service status: launchctl list | grep wavecap
Start service: launchctl load ~/Library/LaunchAgents/com.wavecap.server.plist

Stream Stuck in "queued"

May be waiting for concurrent process slot
Check whisper.maxConcurrentProcesses in config

Stream in "error" State

Check the error field in stream response
Common causes: invalid URL, network issues, audio format problems
Try resetting the stream

No Recent Transcriptions

Check stream status is transcribing
Verify audio source is active
Check for silence detection thresholds in config

Restart Backend

WaveCap runs as a macOS Launch Agent. Use launchctl to manage it:

# Check service status
launchctl list | grep wavecap

# Restart the service
launchctl unload ~/Library/LaunchAgents/com.wavecap.server.plist && launchctl load ~/Library/LaunchAgents/com.wavecap.server.plist

For more service management options (start, stop, logs, troubleshooting), use the wavecap-service skill.

API Response Codes

Code	Meaning
200	Success
401	Authentication required
403	Forbidden (wrong role)
404	Resource not found
422	Validation error
500	Server error

wavecap-health

When & Why to Use This Skill

Use Cases