Skip to main content

Health Check & Setup Verification

The :LovelaceHealth command is your first stop for verifying that the Neovim extension is properly configured and connected to the Localhost daemon.

Running the Health Check

After installing the extension, verify your setup:

vim
:LovelaceHealth

Expected Output

A successful health check displays:

# Lovelace Health Check

## Daemon Connection
**Status**: ✓ Connected
**Socket Path**: /tmp/lovelace-localhost.sock

## Authentication
**Status**: ✓ Authenticated
**User**: user@example.com

## Agent Workers
**Active Workers**: 3
**Idle Workers**: 2
**Busy Workers**: 1

What Each Section Means

Daemon Connection:

  • Shows whether the plugin can communicate with the Localhost daemon
  • Displays the Unix socket path being used for communication
  • Connection is required for all Lovelace operations

Authentication:

  • Indicates whether you're authenticated with Lovelace
  • Shows your user email if authenticated
  • Required for submitting tasks

Agent Workers:

  • Shows the current state of the agent pool
  • Idle workers are available for new tasks
  • Busy workers are currently executing tasks

Common Health Check Scenarios

✅ Fully Operational

All sections show green checkmarks (✓). You're ready to submit tasks.

⚠️ Connected but Not Authenticated

## Daemon Connection
**Status**: ✓ Connected

## Authentication
**Status**: ✗ Not Authenticated

Solution: Run the authentication flow:

vim
:LovelaceAuth

❌ Daemon Not Running

## Daemon Connection
**Status**: ✗ Failed to connect
**Error**: Connection refused (ECONNREFUSED)

Solution: Start the Localhost daemon:

bash
# Start daemon
localhost-ctl start

# Verify it's running
localhost-ctl status

# Then re-run health check

❌ Socket Path Incorrect

## Daemon Connection
**Status**: ✗ Failed to connect
**Socket Path**: /wrong/path/to/socket.sock

Solution: Configure the correct socket path:

lua
require("lovelace").setup({
  daemon = {
    socket_path = "/tmp/lovelace-localhost.sock"  -- Correct path
  }
})

Troubleshooting Connection Issues

Daemon Status Check

Verify the daemon is running and accessible:

bash
# Check daemon status
localhost-ctl status

# Check socket file exists
ls -la /tmp/lovelace-localhost.sock

# Verify permissions
# Socket should be readable/writable by your user

Socket Path Discovery

The plugin searches for the socket in this order:

  1. Config setting: daemon.socket_path in your setup
  2. Environment variable: $LOVELACE_SOCKET
  3. Common locations:
    • /tmp/lovelace-localhost.sock
    • ~/.lovelace/localhost.sock
    • /var/run/lovelace/localhost.sock

Enable Debug Logging

For detailed connection diagnostics:

lua
require("lovelace").setup({
  log_level = "debug"
})

Then check Neovim messages:

vim
:messages

Look for lines like:

[Lovelace] Attempting connection to /tmp/lovelace-localhost.sock
[Lovelace] Connection failed: Connection refused
[Lovelace] Retrying in 1 second (attempt 2/3)

Auto-Start Configuration

The extension can automatically start the daemon if it's not running:

lua
require("lovelace").setup({
  daemon = {
    auto_start = true,  -- Try to start daemon automatically
    retry_count = 3,    -- Number of connection retries
  }
})

Auto-start behavior:

  1. Detects daemon is not running
  2. Executes localhost-ctl start
  3. Waits 2 seconds for startup
  4. Retries connection
  5. Shows error if still failing

Health Check Workflow

Use this workflow when troubleshooting:

  1. Run health check:

    vim
    :LovelaceHealth

  2. If daemon disconnected:

    bash
    localhost-ctl start
localhost-ctl status

  3. Re-run health check:

    vim
    :LovelaceHealth

  4. If not authenticated:

    vim
    :LovelaceAuth

  5. Verify success:

    vim
    :LovelaceHealth

Next Steps

Related Documentation