Configuration Deep Dive

The Lovelace Neovim extension provides extensive configuration options for customizing daemon connection, UI behavior, task submission, keybindings, and logging. This guide covers all available configuration options in detail.

Configuration Overview

All configuration is done through the setup() function:

lua

require("lovelace").setup({
  daemon = { ... },
  ui = { ... },
  tasks = { ... },
  keymaps = { ... },
  log_level = "info",
})

Configuration Philosophy:

Sensible defaults - Works out of the box without configuration
Progressive customization - Only configure what you need to change
Clear documentation - Every option has clear purpose and defaults

Daemon Configuration

Configure how the extension connects to the Localhost daemon.

lua

daemon = {
  -- Socket path for JSON-RPC communication
  socket_path = nil,  -- Auto-discover if nil (default: /tmp/lovelace-localhost.sock)

  -- Auto-start daemon if not running
  auto_start = true,   -- Default: true

  -- Connection retry attempts before failing
  retry_count = 3,     -- Default: 3
}

Socket Path Discovery

When socket_path = nil (default), the extension searches for the socket in this order:

Environment variable: LOVELACE_SOCKET
Common locations:
- /tmp/lovelace-localhost.sock (macOS/Linux default)
- ~/.lovelace/localhost.sock (user-specific)
- /var/run/lovelace/localhost.sock (system-wide)

Override socket path:

lua

daemon = {
  socket_path = "/custom/path/to/socket.sock"
}

Auto-Start Behavior

When auto_start = true and the daemon is not running:

Attempts to start daemon: Runs localhost-ctl start
Waits for startup: 2-second grace period
Retries connection: Uses configured retry count
Shows error if failed: Notification with instructions

Disable auto-start:

lua

daemon = {
  auto_start = false  -- Manual daemon management
}

Use when:

You manage the daemon lifecycle separately
Running in environments where auto-start is not allowed
Debugging daemon connection issues

Retry Strategy

The extension uses exponential backoff for connection retries:

Attempt	Delay	Total Time
1	Immediate	0s
2	1 second	1s
3	2 seconds	3s
4+	3 seconds	3s + (n-3)*3s

Adjust retry count:

lua

daemon = {
  retry_count = 5  -- More attempts for slow networks
}

UI Configuration

Customize how task results and progress are displayed.

lua

ui = {
  -- How to display task results
  result_window = "split",  -- "split", "vsplit", "float", "tab"

  -- Progress notification style
  progress_style = "notify",  -- "notify", "statusline", "both"

  -- Float window dimensions (0.0-1.0 = percentage of screen)
  float_width = 0.8,   -- 80% of screen width
  float_height = 0.8,  -- 80% of screen height

  -- Window border style
  float_border = "rounded",  -- "none", "single", "double", "rounded", "solid", "shadow"
}

Result Window Types

Type	Behavior	Use When
`split`	Horizontal split below current window	Default workflow
`vsplit`	Vertical split to the right	Wide screens, side-by-side
`float`	Centered floating window	Focus on results, no clutter
`tab`	New tab page	Separate workspace for results

Example configurations:

lua

-- Floating windows for cleaner UI
ui = {
  result_window = "float",
  float_width = 0.9,
  float_height = 0.85,
  float_border = "double"
}

-- Vertical split for side-by-side comparison
ui = {
  result_window = "vsplit"
}

-- New tab for complete isolation
ui = {
  result_window = "tab"
}

Progress Notification Styles

Style	Behavior	Use When
`notify`	Show vim.notify() messages	Default, works everywhere
`statusline`	Update statusline indicator	Custom statusline (lualine, etc.)
`both`	Notifications + statusline	Maximum visibility

Statusline Integration:

If using statusline or both, add to your statusline config:

lua

-- lualine example
require("lualine").setup({
  sections = {
    lualine_x = {
      function()
        return require("lovelace").get_status()
      end
    }
  }
})

Float Window Dimensions

Control floating window size with decimal values between 0.0 and 1.0:

0.8 = 80% of screen width/height
0.5 = 50% (half screen)
1.0 = 100% (full screen)

Small screens:

lua

ui = {
  float_width = 0.95,   -- 95% width
  float_height = 0.90,  -- 90% height
}

Large screens:

lua

ui = {
  float_width = 0.6,    -- 60% width (more compact)
  float_height = 0.7,   -- 70% height
}

Border Styles

Visual examples of border styles:

"none"     No border
"single"   ┌─────┐
"double"   ╔═════╗
"rounded"  ╭─────╮
"solid"    ████████
"shadow"   ┌─────┐ (with drop shadow)

Task Configuration

Configure task submission behavior and context collection.

lua

tasks = {
  -- Automatically collect file/selection context
  auto_collect_context = true,  -- Default: true

  -- Default workspace (nil = use current workspace)
  default_workspace = nil,
}

Auto-Collect Context

Controls what context is included when submitting tasks.

When auto_collect_context = true (default):

Current file path included
Selection range included (if visual mode)
Buffer content included
Working directory included

When auto_collect_context = false:

Only task description sent
No file or selection context
Useful for general questions or planning

Example use cases:

lua

-- Disable for architecture planning
tasks = {
  auto_collect_context = false
}

-- Enable for code-specific tasks (default)
tasks = {
  auto_collect_context = true
}

Default Workspace

Override automatic workspace detection:

lua

tasks = {
  default_workspace = "ws_abc123def456"  -- Force specific workspace
}

Use when:

Working on multiple related projects
Daemon workspace detection is incorrect
Consolidating tasks across directories

Workspace ID discovery:

vim

:LovelaceSession
" Output shows workspace ID

Keybindings Configuration

Customize default keybindings or disable them entirely.

lua

keymaps = {
  -- Enable default keybindings
  enabled = true,  -- Default: true

  -- Key prefix for all commands
  prefix = "<leader>l",  -- Default: "<leader>l"
}

Default Keybindings

When enabled = true, these keybindings are automatically created:

Keybinding	Command	Mode	Description
`<prefix>t`	`:LovelaceTask`	Visual	Submit task (selection)
`<prefix>T`	`:LovelaceTasks`	Normal	List all tasks
`<prefix>a`	`:LovelaceAgents`	Normal	Show agent workers
`<prefix>h`	`:LovelaceHealth`	Normal	Run health check

Custom Prefix Examples

Use <leader>a instead of <leader>l:

lua

keymaps = {
  prefix = "<leader>a"
}

Use <C-l> (Ctrl+L):

lua

keymaps = {
  prefix = "<C-l>"
}

Use function keys:

lua

keymaps = {
  prefix = "<F5>"
}
-- Results in <F5>t, <F5>T, <F5>a, <F5>h

Custom Keybindings

Disable defaults and define your own:

lua

require("lovelace").setup({
  keymaps = { enabled = false }
})

-- Define custom keybindings
vim.keymap.set("v", "<F5>", "<cmd>LovelaceTask<cr>", { desc = "Submit task" })
vim.keymap.set("n", "<F6>", "<cmd>LovelaceTasks<cr>", { desc = "List tasks" })
vim.keymap.set("n", "<F7>", "<cmd>LovelaceAgents<cr>", { desc = "Show agents" })
vim.keymap.set("n", "<F8>", "<cmd>LovelaceHealth<cr>", { desc = "Health check" })

Logging Configuration

Control verbosity of extension logging.

lua

log_level = "info"  -- "debug", "info", "warn", "error"

Log Levels

Level	Messages Shown	Use When
`debug`	All messages (very verbose)	Debugging issues
`info`	General information (default)	Normal usage
`warn`	Warnings and errors	Reduce noise
`error`	Only errors	Minimize logging

Viewing Logs

vim

:messages

Clearing Logs

vim

:messages clear

Debug Logging Example

Enable debug logging to troubleshoot connection issues:

lua

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

Then check logs:

vim

:messages
" Shows detailed connection attempts, JSON-RPC messages, etc.

Complete Configuration Examples

Minimal Configuration (Defaults)

lua

require("lovelace").setup({})

Everything works with sensible defaults - no configuration needed!

Power User Configuration

lua

require("lovelace").setup({
  daemon = {
    socket_path = "/custom/path/to/socket.sock",
    auto_start = false,  -- Manual daemon management
    retry_count = 5,     -- More retry attempts
  },

  ui = {
    result_window = "float",  -- Use floating windows
    progress_style = "both",   -- Notifications + statusline
    float_width = 0.9,         -- 90% width
    float_height = 0.85,       -- 85% height
    float_border = "double",   -- Double-line border
  },

  tasks = {
    auto_collect_context = true,
    default_workspace = "my-workspace-id",
  },

  keymaps = {
    enabled = true,
    prefix = "<leader>a",  -- Use <leader>a instead of <leader>l
  },

  log_level = "debug",  -- Verbose logging for troubleshooting
})

Lightweight Configuration

Minimal UI, manual controls:

lua

require("lovelace").setup({
  daemon = {
    auto_start = false  -- I'll start the daemon manually
  },

  ui = {
    result_window = "split",    -- Simple horizontal split
    progress_style = "notify",  -- Just notifications
  },

  tasks = {
    auto_collect_context = true
  },

  keymaps = {
    enabled = false  -- Define my own keybindings
  },

  log_level = "warn"  -- Only show warnings and errors
})

-- Custom minimal keybindings
vim.keymap.set("v", "<leader>t", "<cmd>LovelaceTask<cr>")
vim.keymap.set("n", "<leader>T", "<cmd>LovelaceTasks<cr>")

Floating-First Configuration

Optimized for floating windows and minimal distraction:

lua

require("lovelace").setup({
  ui = {
    result_window = "float",
    float_width = 0.85,
    float_height = 0.80,
    float_border = "rounded",
    progress_style = "notify"
  },

  keymaps = {
    prefix = "<C-l>"  -- Use Ctrl+L prefix
  }
})

Configuration by Use Case

Use Case: Remote Development

Working over SSH with limited terminal width:

lua

require("lovelace").setup({
  ui = {
    result_window = "tab",  -- Separate tab for results
    progress_style = "statusline"  -- Don't flood with notifications
  },

  daemon = {
    retry_count = 10  -- Network may be slow/unstable
  }
})

Use Case: Pair Programming

Large screen, side-by-side workflow:

lua

require("lovelace").setup({
  ui = {
    result_window = "vsplit",  -- Vertical split for side-by-side
    progress_style = "both"     -- Show everything
  },

  keymaps = {
    prefix = "<F5>"  -- Easy to remember and explain
  }
})

Use Case: Production Debugging

Verbose logging, controlled task submission:

lua

require("lovelace").setup({
  tasks = {
    auto_collect_context = false  -- Explicit context only
  },

  log_level = "debug",  -- Full logging

  ui = {
    result_window = "float",
    progress_style = "both"
  }
})

Troubleshooting Configuration Issues

Configuration Not Applied

Symptom: Changes to setup() don't seem to take effect

Solutions:

Reload Neovim:
vim
```
:qa
nvim
```
Check for syntax errors:
lua
```
-- Run manually to see errors
:lua require("lovelace").setup({ ... })
```
Verify setup() is called:
lua
```
-- In your init.lua or lazy.nvim config
require("lovelace").setup({
  -- Your config here
})
```

Keybindings Not Working

Symptom: <leader>lt doesn't submit tasks

Solutions:

Check leader key:
vim
```
:echo mapleader
" Should show your leader key (usually "\")
```
Verify keymaps enabled:
lua
```
require("lovelace").setup({
  keymaps = { enabled = true }  -- Must be true
})
```
Check for conflicts:
vim
```
:verbose map <leader>l
" Shows what's mapped to this key
```

Float Window Issues

Symptom: Float windows are too small or too large

Solutions:

Adjust dimensions:
lua
```
ui = {
  float_width = 0.9,   -- Try different values
  float_height = 0.85
}
```
Check terminal size:
vim
```
:echo &columns
:echo &lines
" Ensure terminal is large enough
```

Next Steps

Command Reference - Detailed documentation for all commands
Health Check Guide - Verify configuration is working
Troubleshooting - Common configuration issues
Workflow Examples - Real-world configuration patterns

Lovelace Developer Portal

Configuration Deep Dive

Configuration Overview

Daemon Configuration

Socket Path Discovery

Auto-Start Behavior

Retry Strategy

UI Configuration

Result Window Types

Progress Notification Styles

Float Window Dimensions

Border Styles

Task Configuration

Auto-Collect Context

Default Workspace

Keybindings Configuration

Default Keybindings

Custom Prefix Examples

Custom Keybindings

Logging Configuration

Log Levels

Viewing Logs

Clearing Logs

Debug Logging Example

Complete Configuration Examples

Minimal Configuration (Defaults)

Power User Configuration

Lightweight Configuration

Floating-First Configuration

Configuration by Use Case

Use Case: Remote Development

Use Case: Pair Programming

Use Case: Production Debugging

Troubleshooting Configuration Issues

Configuration Not Applied

Keybindings Not Working

Float Window Issues

Next Steps

Related Documentation

Lovelace Developer Portal