:LovelaceAgents

View all agent workers and their current states, including resource usage and task counts.

Command Signature

:LovelaceAgents

Alias: :LAgents

Description

The :LovelaceAgents command displays the agent worker pool that executes your tasks. It shows each agent's status (busy/idle), memory usage, task count, and creation time.

What it shows:

• Agent UUIDs (unique identifiers)
• Current status (busy/idle/stopped)
• Task execution count
• Memory usage
• Agent creation time

When to use:

• Checking available agent capacity
• Monitoring system resource usage
• Troubleshooting slow task execution
• Understanding workload distribution

Usage

Basic Usage

:LovelaceAgents

Opens a split window with all agent workers organized by status.

From Lua

require("lovelace.commands").agents()

Output Format

Agents are grouped by status:

# Agent Workers

## Busy Workers (1)
- 550e8400-e29b-41d4-a716-446655440000
  - Status: busy
  - Task Count: 5
  - Memory: 256 MB
  - Created: 2025-12-28 10:30:00

## Idle Workers (2)
- 550e8401-e29b-41d4-a716-446655440001
  - Status: idle
  - Task Count: 3
  - Memory: 128 MB
  - Created: 2025-12-28 10:25:00

- 550e8402-e29b-41d4-a716-446655440002
  - Status: idle
  - Task Count: 1
  - Memory: 105 MB
  - Created: 2025-12-28 10:20:00

Agent Information Fields

Agent UUID

Format: 550e8400-e29b-41d4-a716-446655440000

Purpose: Unique identifier for the agent worker

Usage: Reference in task status output, troubleshooting

Status

Task Count

Total number of tasks this agent has completed since creation.

Typical values:

• New agent: 0-2 tasks
• Active agent: 5-20 tasks
• Long-running agent: 50+ tasks

What it indicates:

• High task count = experienced, reliable agent
• Low task count = newly spawned or recently restarted

Memory Usage

Current memory consumption of the agent process.

Typical values:

• Idle: 100-200 MB
• Busy (simple task): 200-400 MB
• Busy (complex task): 400 MB - 1 GB
• Peak: Up to 1.5 GB for very complex tasks

Warning signs:

• Memory > 2 GB: Agent may be struggling
• Memory increasing over time: Potential memory leak

Created Timestamp

When the agent worker was spawned.

Typical lifetime:

• Short-lived: Minutes to hours (spawned on-demand)
• Long-lived: Days to weeks (persistent agent pool)

Agent States Explained

Busy Agents

Current State: Executing a task

What they're doing:

• Processing your task description
• Analyzing code context
• Generating changes or suggestions
• Running validation checks

Monitor progress:

:LovelaceTasks
" Find task assigned to this agent

:LovelaceTaskStatus task_abc123
" Check task progress

Idle Agents

Current State: Waiting for task assignment

What they're doing:

• Listening for new tasks from daemon
• Maintaining connection to task queue
• Ready for immediate pickup

Next action: Will automatically pick up next queued task

Stopped Agents

Current State: Terminated or crashed

Possible causes:

• Out of memory (OOM)
• Task exceeded timeout
• Daemon restart
• System shutdown

Recovery: Daemon automatically spawns replacement agents

Agent Pool Capacity

How Many Agents?

Typical agent pool size depends on system resources:

Checking Capacity

:LovelaceAgents

Look at the section headers:

• ## Busy Workers (3) - 3 agents working
• ## Idle Workers (2) - 2 agents available

Available capacity: Number of idle workers

When All Agents Are Busy

Symptom: Tasks stay in "queued" state longer

What happens:

1. New task enters queue
2. Daemon waits for agent to become idle
3. Task assigned when agent finishes current work

Solution: Wait for tasks to complete, or contact administrator to increase agent pool size

Monitoring Agent Health

Memory Usage Trends

Watch for agents using excessive memory:

:LovelaceAgents
" Check memory column regularly

Red flags:

• Agent > 1.5 GB memory
• Memory increasing over multiple checks
• Multiple agents showing high memory

Action: Report to daemon administrator if memory usage seems excessive

Task Distribution

Verify tasks are distributed evenly:

:LovelaceAgents
" Check task count for each agent

Healthy distribution (5 agents):

Agent 1: 12 tasks
Agent 2: 11 tasks
Agent 3: 10 tasks
Agent 4: 11 tasks
Agent 5: 9 tasks

Unhealthy distribution:

Agent 1: 30 tasks  ← Taking most work
Agent 2: 2 tasks
Agent 3: 1 task
Agent 4: 0 tasks
Agent 5: 0 tasks

Agent Lifetime

Older agents (days/weeks old) are generally more stable:

Created: 2025-12-15 08:00:00  ← 13 days old, very stable
Created: 2025-12-28 10:30:00  ← 30 minutes old, new

Concern: If agents are constantly new (< 1 hour old), they may be crashing frequently.

Troubleshooting

No Agents Available

Symptom: :LovelaceAgents shows empty list or all stopped

Solutions:

1. Check daemon status:

   bash

   localhost-ctl status
   

2. Restart daemon (spawns fresh agents):

   bash

   localhost-ctl restart
   

3. Check daemon logs:

   bash

   localhost-ctl logs | grep agent
   

All Agents Busy for Extended Period

Symptom: All agents show "busy" for 5+ minutes

Possible causes:

• Complex tasks taking long time
• Tasks stuck/hanging
• Insufficient agent pool size

Solutions:

1. Check task status:

   vim

   :LovelaceTasks
   " Verify tasks are making progress
   

2. Cancel hung tasks:

   vim

   :LovelaceCancel task_abc123
   

3. Request more agents from daemon administrator

Agent Memory Leaks

Symptom: Agent memory grows continuously without decreasing

Example:

Check 1 (10:00): 250 MB
Check 2 (10:15): 450 MB
Check 3 (10:30): 680 MB
Check 4 (10:45): 920 MB

Action: Report to daemon administrator with agent UUID

Agent Lifecycle

Agent Spawn

Agents are created:

• On daemon startup
• When pool size drops below minimum
• On demand (if configured)

Agent Execution

1. Agent connects to daemon
2. Listens for task assignments
3. Executes tasks in sequence
4. Reports progress and results
5. Returns to idle state

Agent Termination

Agents are terminated:

• After configured lifetime (e.g., 24 hours)
• On daemon shutdown
• If out of memory
• If unresponsive (timeout)

Automatic replacement: Daemon spawns new agent to maintain pool size

When to Check Agent Status

Regular Monitoring Scenarios

Before submitting important tasks:

:LovelaceAgents
" Verify idle workers available

When tasks are queued too long:

:LovelaceAgents
" Check if all agents busy

After submitting batch tasks:

:LovelaceAgents
" Monitor agent utilization

Troubleshooting Scenarios

Task submission failures:

:LovelaceAgents
" Check if any agents available

Slow task execution:

:LovelaceAgents
" Check agent memory and load

Daemon connectivity issues:

:LovelaceAgents
" Verify agent pool is healthy

Advanced Usage

Programmatic Access

local lovelace = require("lovelace")
local connection = lovelace.get_connection()

connection:call("agents.list", {}, function(result, error)
  if result then
    for _, agent in ipairs(result.agents) do
      print(agent.id .. ": " .. agent.status)
      print("  Tasks: " .. agent.task_count)
      print("  Memory: " .. agent.memory_mb .. " MB")
    end
  end
end)

Custom Agent Monitoring

-- Check if agents are available before task submission
local function has_idle_agents()
  local agents = require("lovelace").get_agents()
  for _, agent in ipairs(agents) do
    if agent.status == "idle" then
      return true
    end
  end
  return false
end

-- Only submit task if agents available
if has_idle_agents() then
  require("lovelace.commands").task("My task")
else
  vim.notify("No idle agents, please wait...")
end

Related Commands

Next Steps

• :LovelaceTasks - View task queue and assignments
• Agent Management Guide - Complete agent pool documentation
• Task Monitoring Guide - Track task execution
• Troubleshooting - Common agent issues

Related Documentation

• Agent Management Guide - Understanding agent worker pool
• Task Monitoring Guide - Monitor task execution
• Configuration Deep Dive - Agent-related settings