wavecap-service

Manage WaveCap as a macOS service. Use when the user wants to start, stop, restart the service, check service status, view service logs, or manage the launchd configuration.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

The WaveCap Service Management skill for Claude automates macOS service administration using launchd. It provides a streamlined workflow for starting, stopping, and restarting the WaveCap backend, while offering advanced tools for log analysis, health monitoring, and troubleshooting system-level configurations to ensure high availability.

Use Cases

  • Service Lifecycle Management: Effortlessly control the WaveCap service state (start, stop, restart) to ensure the backend is running when needed without manual terminal commands.
  • Real-time Log Analysis: Monitor application logs and error streams (stdout/stderr) to quickly diagnose crashes, performance bottlenecks, or unexpected behavior.
  • System Integration and Persistence: Configure launchd plist settings to manage auto-start behavior or transition the service from a user agent to a system-wide Launch Daemon.
  • Automated Health Checks: Verify service responsiveness via API health endpoints and port monitoring to ensure the environment is ready for production or development use.
namewavecap-service
descriptionManage WaveCap as a macOS service. Use when the user wants to start, stop, restart the service, check service status, view service logs, or manage the launchd configuration.

WaveCap Service Management Skill

Use this skill to manage WaveCap as a macOS Launch Agent service.

Service Configuration

  • Plist location: ~/Library/LaunchAgents/com.wavecap.server.plist
  • Service name: com.wavecap.server
  • Logs: ~/Library/Logs/wavecap-server.log and wavecap-server-error.log

Service Status

Check if the service is running:

launchctl list | grep wavecap

Output format: PID EXIT_CODE LABEL

  • If PID is a number and EXIT_CODE is 0: service is running
  • If PID is - and EXIT_CODE is non-zero: service exited with error

Quick status check:

launchctl list com.wavecap.server 2>/dev/null && echo "Service is loaded" || echo "Service is not loaded"

Start Service

Load and start the service:

launchctl load ~/Library/LaunchAgents/com.wavecap.server.plist

Stop Service

Unload and stop the service:

launchctl unload ~/Library/LaunchAgents/com.wavecap.server.plist

Restart Service

Stop then start:

launchctl unload ~/Library/LaunchAgents/com.wavecap.server.plist && launchctl load ~/Library/LaunchAgents/com.wavecap.server.plist

View Logs

Recent stdout (application logs):

tail -50 ~/Library/Logs/wavecap-server.log

Recent stderr (errors):

tail -50 ~/Library/Logs/wavecap-server-error.log

Follow logs in real-time:

tail -f ~/Library/Logs/wavecap-server.log

Check for errors:

grep -i error ~/Library/Logs/wavecap-server-error.log | tail -20

Verify Server is Responding

After starting, verify the server is healthy:

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

Expected: {"status": "ok"}

Troubleshooting

Service Won't Start

  1. Check error log:

    cat ~/Library/Logs/wavecap-server-error.log
    
  2. Verify plist syntax:

    plutil -lint ~/Library/LaunchAgents/com.wavecap.server.plist
    
  3. Try running manually to see errors:

    /Users/thw/Projects/WaveCap/backend/.venv/bin/python -m wavecap_backend
    

Service Keeps Restarting

Check exit codes in error log. Common issues:

  • Missing dependencies (ffmpeg not in PATH)
  • Port 8000 already in use
  • Configuration errors

Find what's using port 8000:

lsof -i :8000

View Plist Configuration

cat ~/Library/LaunchAgents/com.wavecap.server.plist

Clear Logs

: > ~/Library/Logs/wavecap-server.log
: > ~/Library/Logs/wavecap-server-error.log

Service Behavior

  • RunAtLoad: Starts automatically when you log in
  • KeepAlive: Automatically restarts if it crashes
  • WorkingDirectory: /Users/thw/Projects/WaveCap/backend

Disable Auto-Start

To stop the service from starting on login (but keep the plist):

launchctl unload -w ~/Library/LaunchAgents/com.wavecap.server.plist

To re-enable:

launchctl load -w ~/Library/LaunchAgents/com.wavecap.server.plist

Remove Service Completely

launchctl unload ~/Library/LaunchAgents/com.wavecap.server.plist
rm ~/Library/LaunchAgents/com.wavecap.server.plist

Convert to Launch Daemon (System-Wide)

To run at boot (even without user login), convert to a Launch Daemon:

# Stop agent
launchctl unload ~/Library/LaunchAgents/com.wavecap.server.plist

# Move to system location
sudo mv ~/Library/LaunchAgents/com.wavecap.server.plist /Library/LaunchDaemons/

# Set permissions
sudo chown root:wheel /Library/LaunchDaemons/com.wavecap.server.plist
sudo chmod 644 /Library/LaunchDaemons/com.wavecap.server.plist

# Load daemon
sudo launchctl load /Library/LaunchDaemons/com.wavecap.server.plist

Note: The plist may need a UserName key added to run as your user instead of root.