Vibe-Check Troubleshooting & Diagnosis

Purpose: Help users diagnose and fix vibe-check configuration and operational issues

---

When to Use This Skill

Invoke this troubleshooting flow when the user:

• Asks "is vibe-check working?"
• Says "check my vibe-check setup"
• Requests "troubleshoot vibe-check"
• Reports issues like "vibe-check isn't recording" or "stats aren't showing up"
• Asks about vibe-check configuration

---

Diagnostic Steps

1. Get Current Status

First, run the status command to understand the current state:

vibe-check status

This will show:

• Service status: Is vibe-check running?
• Database location and size: Where is data stored?
• Log file location: Where to find error messages
• Local backup status: Is it processing conversations?
• Remote sync status: Is it syncing to the server (if enabled)?
• Claude integration: Are MCP and skills installed?

2. Read Configuration

Check the configuration file (location shown in status output, typically ~/.vibe-check/config.json):

cat ~/.vibe-check/config.json

Key things to verify:

• monitor.conversation_dir: Should be ~/.claude/projects (where Claude Code stores conversations)
• sqlite.enabled: Should be true for local storage
• sqlite.database_path: Should be ~/.vibe-check/vibe_check.db
• api.enabled: Whether remote sync is enabled (optional)

3. Check for Common Issues

Based on the status output, diagnose common problems:

Issue: "Not running"

• Solution: Start it with vibe-check start
• Check if it stays running or crashes immediately
• If crashes, check logs: vibe-check logs

Issue: "Database not created yet"

• Cause: Service hasn't started or no conversations have been captured
• Solution:
  1. Start the service: vibe-check start
  2. Use Claude Code to create a conversation
  3. Check status again: vibe-check status

Issue: "0 events in database"

• Cause: Monitor is running but not capturing conversations
• Check:
  • Is conversation_dir pointing to the right location?
  • Are there .jsonl files in ~/.claude/projects/?
  • Check logs for errors: vibe-check logs

Issue: "MCP: ❌ Not installed"

• Cause: MCP plugin not installed (limits Claude integration)
• Solution: Run the plugin installer:

  ./scripts/install-plugin.sh
  

Issue: "Skills: ⚠️ X/7 installed"

• Cause: Some skills are missing
• Solution: Run the plugin installer:

  ./scripts/install-plugin.sh
  

Issue: "Remote sync pending"

• Cause: API sync is enabled but events aren't uploading
• Check:
  • Is the API endpoint reachable?
  • Is the API key valid? Run vibe-check auth status
  • Check logs for API errors: vibe-check logs

4. Review Documentation (If Needed)

For deeper understanding of the codebase, review the project documentation:

cat /Users/wanderingstan/Developer/vibe-check/CLAUDE.md

This contains:

• Project structure
• Database schema
• Key components
• Common patterns

---

Response Format

When helping troubleshoot, follow this flow:

1. Run status check - Execute vibe-check status and analyze output
2. Identify issues - Point out what's wrong based on status
3. Provide solutions - Give specific commands to fix issues
4. Verify fixes - After user applies fixes, check status again
5. Explain configuration - If everything is working, explain current setup

Example Response

Let me check your vibe-check setup.

[Runs vibe-check status]

I see a few issues:

1. ❌ Service is not running
   Fix: Run `vibe-check start`

2. ⚠️  Only 5/7 skills are installed
   Fix: Run `./scripts/install-plugin.sh` to install missing skills

3. ⚠️  Remote sync is enabled but no API key is set
   Fix: Run `vibe-check auth login` to authenticate

Would you like me to help you fix these issues?

---

Advanced Troubleshooting

Check Logs for Errors

If the issue isn't obvious from status:

vibe-check logs -n 100

Look for:

• Python exceptions or tracebacks
• File permission errors
• Database lock errors
• API connection failures

Verify Database Integrity

If database exists but seems corrupted:

sqlite3 ~/.vibe-check/vibe_check.db "PRAGMA integrity_check;"

Check File Permissions

Ensure vibe-check can read conversation files:

ls -la ~/.claude/projects/*.jsonl | head -5

Files should be readable by the current user.

---

What NOT to Do

• Don't suggest deleting the database unless absolutely necessary (user will lose all history)
• Don't modify config manually unless user confirms - always explain changes first
• Don't assume the issue - always check status first

---

Related Commands

• vibe-check start - Start the monitor
• vibe-check stop - Stop the monitor
• vibe-check restart - Restart the monitor
• vibe-check logs - View logs
• vibe-check auth login - Authenticate for remote sync
• ./scripts/install-plugin.sh - Install/update MCP and skills