Quick Start

Get up and running with the Lovelace Neovim extension in minutes. This guide walks you through submitting your first task to an AI agent worker.

Prerequisites

Before starting, ensure you have:

✅ Neovim 0.9.0 or later installed
✅ Lovelace Neovim extension installed (Installation Guide)
✅ Localhost daemon running (localhost-ctl status)
✅ Authenticated with Lovelace (:LovelaceAuth)

Your First Task

Let's submit a simple refactoring task to demonstrate the workflow.

1. Open a File

Open any JavaScript or TypeScript file in Neovim:

bash

nvim src/example.js

Or if you don't have a file handy, create a simple example:

javascript

// src/example.js
function calculateTotal(items) {
  var total = 0;
  for (var i = 0; i < items.length; i++) {
    total = total + items[i].price;
  }
  return total;
}

2. Select Code

Enter visual mode and select the code you want to refactor:

vim

V5j  # Select 5 lines (or however many your function has)

Your selection should be highlighted in visual mode.

3. Submit Task

With the code selected, submit a task:

vim

:LovelaceTask

You can also use the default keybinding (if configured):

vim

<leader>lt  # Default: \lt

4. Enter Task Description

You'll be prompted to enter a description for your task. Be specific about what you want:

Refactor this function to use modern JavaScript: const/let instead of var, arrow functions, and reduce() instead of for loop

Tips for good task descriptions:

Be specific about what you want changed
Mention the technology/framework if relevant
Include any constraints or requirements
Reference specific patterns or best practices

5. Wait for Completion

The extension will:

Submit your task to the daemon
Show a notification when an agent picks it up
Display progress notifications as the agent works
Open results automatically when complete

You can continue working in Neovim while the task executes - all operations are non-blocking.

6. Review Results

When the task completes, a split window opens automatically showing:

Diff view: Original code vs. refactored code
Syntax highlighting: Properly formatted for your language
Explanation: Agent's reasoning (if provided)

Example result:

javascript

// Refactored version
const calculateTotal = (items) => {
  return items.reduce((total, item) => total + item.price, 0);
};

7. Apply or Reject Changes

In the result buffer, you have several options:

Key	Action
`a`	Apply changes to original file
`d`	Dismiss and keep original
`c`	Copy to clipboard only
`q`	Close result window

Press a to apply the changes to your file.

8. Verify the Result

Your file now contains the refactored code. You can verify by running your tests or checking the functionality:

bash

# Example: Run tests
npm test

# Example: Check syntax
eslint src/example.js

Next Steps

Now that you've submitted your first task, explore more advanced workflows:

Task Submission Guide - Learn advanced task submission patterns
Task Monitoring - Track and manage running tasks
Agent Management - View and manage agent workers
Workflow Examples - Real-world usage patterns

Common Workflows

Here are some common tasks you can try next:

Code Analysis

Select a complex function and ask:

Analyze this function for potential bugs, edge cases, and performance issues

Documentation Generation

Select a function and ask:

Add comprehensive JSDoc comments explaining parameters, return value, and usage examples

Test Generation

Select a function and ask:

Generate comprehensive unit tests using Jest, covering success cases, edge cases, and error handling

Code Explanation

Select unfamiliar code and ask:

Explain what this code does, step by step, including any design patterns used

Troubleshooting

Task Submission Hangs

Symptom: Task submission doesn't return or shows no progress

Solution:

Check daemon status:
vim
```
:LovelaceHealth
```
View task list to see if task was queued:
vim
```
:LovelaceTasks
```
Check for agent workers:
vim
```
:LovelaceAgents
```

No Agent Workers Available

Symptom: Task stays in "queued" state

Solution: Ensure agent workers are running. Check with:

vim

:LovelaceAgents

If no agents are listed, start the agent worker service or contact your Lovelace platform administrator.

Authentication Expired

Symptom: Tasks fail with authentication error

Solution: Re-authenticate:

vim

:LovelaceAuth

For more troubleshooting help, see the Troubleshooting Guide.

Lovelace Developer Portal