Agent Management Guide

Agent workers are the processes that execute your tasks. This guide explains how to view, understand, and monitor the agent worker pool that powers task execution.

Viewing Agent Workers

List all agent workers and their current states:

vim

:LovelaceAgents

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

Understanding Agent Information

Each agent displays these key metrics:

Agent UUID

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

Purpose: Unique identifier for the agent worker

Usage: Reference in task status output, troubleshooting

Status

Status	Meaning	Availability
busy	Currently executing a task	Not available for new tasks
idle	Available and waiting for tasks	Ready for task assignment
stopped	Terminated or crashed	Not available, needs restart

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:

vim

: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:

System RAM	Recommended Agents	Max Concurrent Tasks
8 GB	2-3 agents	2-3 tasks
16 GB	3-5 agents	3-5 tasks
32 GB+	5-10 agents	5-10 tasks

Checking Capacity

vim

: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:

New task enters queue
Daemon waits for agent to become idle
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:

vim

: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:

vim

: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 Agent Issues

No Agents Available

Symptom: :LovelaceAgents shows empty list or all stopped

Solutions:

Check daemon status:
bash
```
localhost-ctl status
```
Restart daemon (spawns fresh agents):
bash
```
localhost-ctl restart
```
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:

Check task status:
vim
```
:LovelaceTasks
" Verify tasks are making progress
```
Cancel hung tasks:
vim
```
:LovelaceCancel task_abc123
```
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

Agent connects to daemon
Listens for task assignments
Executes tasks in sequence
Reports progress and results
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:

vim

:LovelaceAgents
" Verify idle workers available

When tasks are queued too long:

vim

:LovelaceAgents
" Check if all agents busy

After submitting batch tasks:

vim

:LovelaceAgents
" Monitor agent utilization

Troubleshooting Scenarios

Task submission failures:

vim

:LovelaceAgents
" Check if any agents available

Slow task execution:

vim

:LovelaceAgents
" Check agent memory and load

Daemon connectivity issues:

vim

:LovelaceAgents
" Verify agent pool is healthy

Advanced: Agent Architecture

Agent-Daemon Communication

┌─────────────────┐
│  Neovim Plugin  │
│  (Your Editor)  │
└────────┬────────┘
         │ JSON-RPC
         ▼
┌─────────────────┐
│     Daemon      │
│   Task Queue    │
└────────┬────────┘
         │ Work Assignment
         ▼
┌─────────────────┐
│  Agent Workers  │
│  (Task Exec)    │
└─────────────────┘

Task Assignment

Daemon uses a work queue pattern:

Tasks enter queue on submission
Idle agents poll for work
First idle agent gets next queued task
Agent marks itself busy
Agent executes task
Agent reports completion
Agent returns to idle state

Next Steps

Task Monitoring - Track task progress and status
Task Submission - Submit tasks to agents
:LovelaceAgents Reference - Full command documentation
Troubleshooting - Common agent issues

Lovelace Developer Portal