Daemon Management
Logs & Debugging
Troubleshoot issues with whisp.
Logs & Debugging
Troubleshoot issues with whisp.
Viewing Logs
Log Location
By default, logs are written to:
- Linux:
~/.local/share/whisp/whisp.log - macOS:
~/Library/Logs/whisp.log
View Recent Logs
# Linux - view last 50 lines
tail -n 50 ~/.local/share/whisp/whisp.log
# Linux - follow logs in real-time
tail -f ~/.local/share/whisp/whisp.log
# macOS - view last 50 lines
tail -n 50 ~/Library/Logs/whisp.log
# macOS - follow logs in real-time
tail -f ~/Library/Logs/whisp.logLive Debug Mode
For real-time debugging, run the daemon in foreground mode:
# Run in foreground (shows all logs in terminal)
whisp start --foreground
# With verbose output
whisp -v start --foregroundPress Ctrl+C to stop the foreground daemon.
Diagnostic Commands
Whisp provides built-in diagnostic tools:
# Quick status check
whisp status
# Comprehensive health check
whisp doctor
# Detailed metrics and uptime
whisp healthUsing whisp doctor
The doctor command checks your entire setup:
whisp doctorIt verifies:
- Daemon status (running/stopped)
- Socket connectivity
- Configuration file validity
- Config file permissions (should be 0600)
- API key presence for your provider
- Required tools (
python3,nc)
Using whisp health
Get detailed runtime metrics:
whisp healthShows:
- Uptime
- Request count and error count
- Active connections
- Memory usage (Linux)
- Current provider
Common Issues
Daemon Won't Start
Check if already running:
whisp status
# If running, stop it first:
whisp stopCheck socket availability:
# Check if socket exists
ls -la /tmp/whisp.sock
# If stale socket exists, stop and restart:
whisp stop && whisp startCheck API key:
whisp doctor
# Look for "API key: ✓" or "API key: ✗"Commands Not Working
Check daemon is running:
whisp statusRun diagnostic check:
whisp doctor
# This will identify configuration or connectivity issuesCheck logs for errors:
# Linux
tail -n 20 ~/.local/share/whisp/whisp.log
# macOS
tail -n 20 ~/Library/Logs/whisp.logSlow Responses
Check your internet connection:
ping api.openai.comTry a faster model:
whisp config set model gpt-5-nano-2025-08-07
whisp restartCheck response metrics:
whisp metrics
# Look at avg_response_ms and P95/P99 percentilesSocket Connection Issues
Customize socket path:
# Set custom socket location
export WHISP_SOCKET=/path/to/custom.sock
whisp restartCheck socket permissions:
ls -la /tmp/whisp.sock
# Should be owned by your user with 0700 permissionsDebug Mode
Run whisp in full debug mode for troubleshooting:
# Foreground with verbose output
whisp -v start --foregroundThis shows:
- All incoming requests
- LLM API calls and responses
- Timing information
- Any errors or warnings
Getting Help
If you're still stuck:
- Check GitHub Issues
- Open a new issue with your logs
- Join the Discussions