lovelace agents

Manage autonomous AI agents for background task execution

The agents command lets you view, monitor, and interact with AI agents running development tasks in the background. Agents can perform long-running operations like code analysis, test generation, or documentation creation while you continue with other work.

Overview

Agents are autonomous AI workers that execute complex, multi-step tasks independently. Unlike interactive chat sessions, agents:

Run in the background - Continue working while you do other things
Execute multi-step workflows - Plan and carry out complex operations
Persist across sessions - Keep running even if you close your terminal
Stream progress updates - Monitor execution in real-time
Store execution results - Review outcomes when tasks complete

The Lovelace CLI communicates with a local daemon that manages agent lifecycle, execution, and resource allocation.

Usage

bash

lovelace agents <subcommand> [options]

Subcommands

`lovelace agents list`

List all running and recent agents.

Usage:

bash

lovelace agents list [options]

Aliases: ls

Options:

Option	Description
`--json`	Output in JSON format

Interactive Example:

$ lovelace agents list

Running Agents (2):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ID: agent_code_analyzer_1
Task: Analyze codebase for security issues
Status: Running (45% complete)
Started: 5 minutes ago
Model: claude-sonnet-4-5

ID: agent_test_generator_2
Task: Generate unit tests for user service
Status: Running (12% complete)
Started: 2 minutes ago
Model: gpt-4

Completed Agents (3):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ID: agent_docs_generator_3
Task: Create API documentation
Status: Completed
Duration: 8 minutes
Completed: 1 hour ago

[...]

`lovelace agents status`

Show overall agent system status and health.

Usage:

bash

lovelace agents status

Interactive Example:

$ lovelace agents status

Agent System Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Daemon: Running
Version: 1.0.0
Uptime: 2 hours 34 minutes

Resource Usage:
  CPU: 15%
  Memory: 512 MB / 2 GB
  Disk: 1.2 GB

Active Agents: 2
Queued Tasks: 0
Completed Today: 5

Health: ✓ All systems operational

`lovelace agents logs`

View execution logs for a specific agent.

Usage:

bash

lovelace agents logs <agent-id> [options]

Options:

Option	Description
`-f, --follow`	Follow log output in real-time
`--lines <n>`	Number of lines to show (default: 50)

Interactive Example:

$ lovelace agents logs agent_code_analyzer_1 --follow

[2025-10-19 14:32:15] Agent started: code-analyzer
[2025-10-19 14:32:16] Loading project context from /Users/dev/my-project
[2025-10-19 14:32:17] Discovered 247 TypeScript files
[2025-10-19 14:32:18] Starting security analysis...
[2025-10-19 14:32:20] Analyzing authentication layer
[2025-10-19 14:32:22] Found potential SQL injection in user-service.ts:45
[2025-10-19 14:32:24] Analyzing API endpoints...
[2025-10-19 14:32:27] Checking for XSS vulnerabilities
[2025-10-19 14:32:30] Progress: 45% complete
[Live updating...]

`lovelace agents info`

Show detailed information about a specific agent.

Usage:

bash

lovelace agents info <agent-id>

Interactive Example:

$ lovelace agents info agent_code_analyzer_1

Agent Information
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ID: agent_code_analyzer_1
Type: code-analyzer
Status: Running

Task Details:
  Description: Analyze codebase for security issues
  Input: /Users/dev/my-project/src
  Output: /Users/dev/my-project/analysis/security-report.md

Execution:
  Started: 2025-10-19 14:32:15
  Duration: 5 minutes 23 seconds
  Progress: 45%
  Steps Completed: 12 / 27

Model Configuration:
  Provider: Anthropic
  Model: claude-sonnet-4-5
  Temperature: 0.7
  Max Tokens: 4096

Resource Usage:
  CPU: 8%
  Memory: 256 MB
  Tokens Used: 15,234 / 100,000

Common Use Cases

Code Analysis in Background

Run comprehensive codebase analysis while you continue developing:

$ lovelace agents list

(No agents running)

# Start analysis agent (via localhost CLI)
$ localhost agents start code-analyzer "Analyze for security issues" --input ./src

✓ Agent started: agent_code_analyzer_1

# Continue working...
$ git commit -m "Add user validation"

# Check progress later
$ lovelace agents status

Active Agents: 1
  • code-analyzer (78% complete)

Monitor Long-Running Tasks

Keep an eye on agent progress:

$ lovelace agents logs agent_test_generator_2 --follow

[2025-10-19 15:00:00] Starting test generation for user service
[2025-10-19 15:00:02] Analyzing function signatures...
[2025-10-19 15:00:05] Generating unit tests...
[2025-10-19 15:00:08] Created UserService.test.ts
[2025-10-19 15:00:10] Generating integration tests...
[Live stream continues...]

^C (Ctrl+C to stop following)

Review Completed Work

Check results from finished agents:

$ lovelace agents list

Completed Agents (1):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ID: agent_docs_generator_3
Task: Create API documentation
Status: Completed ✓
Output: /docs/api/
Completed: 10 minutes ago

$ cat /docs/api/user-service.md

# User Service API

[Auto-generated documentation...]

Agent Lifecycle

States

Agents progress through these states:

Starting - Agent is initializing and loading context
Running - Actively executing task steps
Completed - Successfully finished all steps
Failed - Encountered an error and stopped
Cancelled - Manually stopped before completion

Lifecycle Example

$ lovelace agents list

# Agent just started
ID: agent_xyz
Status: Starting (0%)
[Initializing context...]

# After 30 seconds
Status: Running (15%)
[Analyzing code structure...]

# After 5 minutes
Status: Running (67%)
[Generating documentation...]

# After 8 minutes
Status: Completed ✓
Duration: 8m 23s
Output: /docs/generated/

Agent Types

Common agent types you'll see:

Type	Purpose	Typical Duration
`code-analyzer`	Analyze code quality, security, architecture	5-15 minutes
`test-generator`	Generate unit and integration tests	10-30 minutes
`docs-generator`	Create documentation from code	5-20 minutes
`refactor-assistant`	Suggest code improvements	10-25 minutes
`security-scanner`	Find security vulnerabilities	5-15 minutes
`dependency-auditor`	Analyze and update dependencies	3-10 minutes

Interaction with localhost CLI

The lovelace agents command is read-only - it shows you what agents are running. To create, start, or stop agents, use the localhost CLI:

bash

# Create and start agents
localhost agents start <type> "task description" [options]

# Stop agents
localhost agents stop <agent-id>

# Configure agents
localhost agents config <agent-id> --set key=value

See the localhost CLI documentation for agent management operations.

JSON Output

Use --json flag for programmatic access:

bash

$ lovelace agents list --json

{
  "agents": [
    {
      "id": "agent_code_analyzer_1",
      "type": "code-analyzer",
      "status": "running",
      "progress": 45,
      "started_at": "2025-10-19T14:32:15Z",
      "task": {
        "description": "Analyze codebase for security issues",
        "input": "/Users/dev/my-project/src",
        "output": "/Users/dev/my-project/analysis/security-report.md"
      },
      "model": {
        "provider": "anthropic",
        "model": "claude-sonnet-4-5"
      }
    }
  ]
}

Environment Variables

Variable	Description	Default
`LOCALHOST_SOCKET`	Path to localhost daemon socket	`~/.lovelace/localhost.sock`
`LOCALHOST_PORT`	Port for localhost HTTP API	`3456`
`LOVELACE_AGENTS_DIR`	Directory for agent data	`~/.lovelace/agents`

Exit Codes

Code	Meaning
`0`	Command succeeded
`1`	Error communicating with daemon or listing agents
`2`	Invalid arguments
`3`	Daemon not running

Troubleshooting

Daemon Not Running

$ lovelace agents status

Error: Failed to connect to localhost daemon

Solution: Start the daemon first
$ localhost daemon start

No Agents Found

$ lovelace agents list

(No agents running)

# Start an agent using localhost CLI
$ localhost agents start code-analyzer "Task description"

Agent Stuck

$ lovelace agents info agent_xyz

Status: Running (23%)
Duration: 45 minutes

# If agent appears stuck, check logs
$ lovelace agents logs agent_xyz --follow

# Or stop it via localhost
$ localhost agents stop agent_xyz

Related Commands

lovelace chat - Interactive AI assistance (foreground)
lovelace workspace - Manage project context for agents
lovelace mcp - Extend agent capabilities with MCP tools

Related Guides

Agent Basics Guide - Complete guide to agent management
Hackathon Project Example - Using agents to build apps
localhost CLI Documentation - Creating and managing agents

See the Command Reference for all available commands.

Lovelace Developer Portal

lovelace agents

Overview

Usage

Subcommands

`lovelace agents list`

`lovelace agents status`

`lovelace agents logs`

`lovelace agents info`

Common Use Cases

Code Analysis in Background

Monitor Long-Running Tasks

Review Completed Work

Agent Lifecycle

States

Lifecycle Example

Agent Types

Interaction with localhost CLI

JSON Output

Environment Variables

Exit Codes

Troubleshooting

Daemon Not Running

No Agents Found

Agent Stuck

Related Commands

Related Guides

Lovelace Developer Portal