Editor Integration Guide

Complete guide to ACP (Agent Client Protocol) and editor integrations

Overview

The Lovelace CLI provides Agent Client Protocol (ACP) integration that allows code editors to use Lovelace as an AI-powered development assistant. ACP enables editors to seamlessly integrate with Lovelace's chat, analysis, and agent execution capabilities.

Understanding ACP

What is Agent Client Protocol?

Agent Client Protocol (ACP) is:

JSON-RPC over stdio - Standard communication protocol between editors and CLI
Editor-agnostic - Works with VS Code, Zed, Vim, Emacs, and any editor supporting subprocesses
Stateful sessions - Maintains conversation context across multiple requests
Full CLI access - Editors can access all Lovelace capabilities through structured API

ACP vs Direct CLI Usage

Method	Use Case	Benefits
Direct CLI	Terminal workflows, scripts, CI/CD	Full command-line interface, human-readable output
ACP Integration	Editor extensions, IDE plugins	Structured JSON responses, persistent sessions, seamless UX

ACP Server Management

Start ACP Server

bash

# Start ACP server on default port
lovelace acp start

# Start with custom configuration
lovelace acp start --port 8080 --host localhost

# Start with specific workspace
lovelace acp start --workspace my-project

# Start with authentication
lovelace acp start --require-auth

Server Status and Control

bash

# Check ACP server status
lovelace acp status

# Stop ACP server
lovelace acp stop

# Restart ACP server
lovelace acp restart

# View server logs
lovelace acp logs

Editor Integrations

VS Code Extension

Installation:

bash

# Install from marketplace
code --install-extension lovelace-ai.lovelace-vscode

# Or install from VSIX
code --install-extension lovelace-vscode-1.0.0.vsix

Configuration:

json

// settings.json
{
  "lovelace.acp.enabled": true,
  "lovelace.acp.port": 3000,
  "lovelace.acp.workspace": "auto",
  "lovelace.chat.provider": "anthropic",
  "lovelace.agents.autoStart": true
}

Features:

Chat Panel: Integrated AI chat with workspace context
Code Actions: Quick fixes and refactoring suggestions
Agent Tasks: Run analysis and generation tasks from editor
Workspace Sync: Automatic workspace synchronization

Zed Editor Integration

Installation:

bash

# Install Zed extension
zed extensions install lovelace-ai

# Configure in Zed settings

Configuration:

json

// settings.json
{
  "languages": {
    "TypeScript": {
      "language_servers": ["typescript-language-server", "lovelace-acp"]
    }
  },
  "lovelace": {
    "acp_port": 3000,
    "workspace_auto_detect": true
  }
}

Custom Editor Integration

For editors not yet supported, implement ACP client manually:

python

# Python example for custom editor
import json
import subprocess
from typing import Dict, Any

class LovelaceACPClient:
    def __init__(self, workspace_path: str):
        self.process = subprocess.Popen(
            ["lovelace", "acp", "start", "--workspace", workspace_path],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True
        )

    def send_request(self, method: str, params: Dict[str, Any]) -> Dict[str, Any]:
        request = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": method,
            "params": params
        }

        self.process.stdin.write(json.dumps(request) + "\n")
        self.process.stdin.flush()

        response = self.process.stdout.readline()
        return json.loads(response)

    def chat_message(self, message: str) -> str:
        response = self.send_request("chat/message", {
            "message": message,
            "include_context": True
        })
        return response["result"]["content"]

    def analyze_file(self, file_path: str) -> Dict[str, Any]:
        response = self.send_request("analysis/file", {
            "file_path": file_path,
            "include_suggestions": True
        })
        return response["result"]

ACP Protocol Reference

Core Methods

Chat Operations

json

// Start chat session
{
  "method": "chat/start",
  "params": {
    "workspace": "my-project",
    "provider": "anthropic",
    "context": ["workspace", "git"]
  }
}

// Send message
{
  "method": "chat/message",
  "params": {
    "session_id": "chat_123",
    "message": "Analyze the authentication flow",
    "include_context": true
  }
}

// Get chat history
{
  "method": "chat/history",
  "params": {
    "session_id": "chat_123",
    "limit": 50
  }
}

Analysis Operations

json

// Analyze current project
{
  "method": "analysis/project",
  "params": {
    "include_symbols": true,
    "include_dependencies": true,
    "scope": "current-branch"
  }
}

// Analyze specific file
{
  "method": "analysis/file",
  "params": {
    "file_path": "src/components/Button.tsx",
    "include_suggestions": true
  }
}

Agent Operations

json

// List available agents
{
  "method": "agents/list",
  "params": {
    "category": "analysis"
  }
}

// Execute agent task
{
  "method": "agents/execute",
  "params": {
    "agent": "analysis-worker",
    "task": "code-quality",
    "input": "./src/components/"
  }
}

// Get execution status
{
  "method": "agents/status",
  "params": {
    "execution_id": "exec_456"
  }
}

Workspace Operations

json

// Get workspace info
{
  "method": "workspace/info",
  "params": {}
}

// Sync workspace
{
  "method": "workspace/sync",
  "params": {
    "force": false
  }
}

// Switch workspace
{
  "method": "workspace/switch",
  "params": {
    "workspace": "different-project"
  }
}

Response Format

json

// Success response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "success",
    "data": { /* response data */ }
  }
}

// Error response
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Workspace not found",
    "data": {
      "error_type": "workspace_not_found",
      "workspace": "invalid-project"
    }
  }
}

Development Workflow Integration

Code Review Workflow

Editor triggers analysis:
json
```
{
  "method": "analysis/diff",
  "params": {
    "base": "main",
    "head": "feature-branch"
  }
}
```

ACP returns structured analysis:

json

{
  "result": {
    "files_changed": 5,
    "issues": [
      {
        "file": "src/auth.ts",
        "line": 42,
        "type": "security",
        "message": "Potential SQL injection vulnerability"
      }
    ],
    "suggestions": [
      {
        "file": "src/utils.ts",
        "type": "refactor",
        "message": "Consider extracting common validation logic"
      }
    ]
  }
}

Editor displays inline feedback

Interactive Development

json

// Request code generation
{
  "method": "chat/message",
  "params": {
    "message": "Generate unit tests for the Button component",
    "context": {
      "current_file": "src/components/Button.tsx",
      "selection": {
        "start": 1,
        "end": 50
      }
    }
  }
}

// Apply suggestions
{
  "method": "workspace/apply",
  "params": {
    "changes": [
      {
        "file": "src/components/Button.test.tsx",
        "action": "create",
        "content": "/* generated test content */"
      }
    ]
  }
}

Configuration

ACP Server Configuration

yaml

# ~/.lovelace/acp-config.yaml
server:
  host: "localhost"
  port: 3000
  timeout: 30000

authentication:
  required: false
  method: "token"

workspace:
  auto_detect: true
  default_context: ["workspace", "git"]

providers:
  default: "anthropic"
  fallback: "openai"

agents:
  auto_start_daemon: true
  max_concurrent: 3

logging:
  level: "info"
  file: "~/.lovelace/logs/acp.log"

Editor-Specific Settings

VS Code Configuration

json

{
  "lovelace.acp.enabled": true,
  "lovelace.acp.autoStart": true,
  "lovelace.acp.port": 3000,
  "lovelace.chat.showInSidebar": true,
  "lovelace.analysis.autoRun": true,
  "lovelace.agents.enableCodeActions": true,
  "lovelace.workspace.autoSync": true
}

Zed Configuration

json

{
  "lovelace": {
    "acp_enabled": true,
    "acp_port": 3000,
    "chat_panel": "right",
    "auto_analysis": true,
    "keybindings": {
      "chat_toggle": "cmd-shift-l",
      "analyze_file": "cmd-alt-a"
    }
  }
}

Troubleshooting

Connection Issues

ACP Server Not Starting:

bash

# Check if port is available
lsof -i :3000

# Start with verbose logging
lovelace acp start --verbose

# Check server logs
lovelace acp logs --tail

Editor Can't Connect:

bash

# Verify server is running
lovelace acp status

# Test connection manually
curl -X POST http://localhost:3000/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"workspace/info","id":1}'

# Check firewall settings
sudo ufw status

Authentication Issues

Token Authentication:

bash

# Verify authentication status
lovelace auth status

# Refresh tokens
lovelace auth refresh

# Generate ACP-specific token
lovelace auth token --scope acp

Performance Issues

Slow Responses:

bash

# Check agent daemon status
lovelace agents daemon status

# Monitor resource usage
lovelace acp monitor

# Adjust timeout settings
lovelace config set acp.timeout 60000

Memory Usage:

bash

# Monitor ACP server memory
ps aux | grep "lovelace acp"

# Restart server to clear memory
lovelace acp restart

# Adjust server configuration
lovelace config set acp.max_sessions 10

Best Practices

Integration Development

Handle Errors Gracefully: Always check for ACP server availability before making requests
Implement Timeouts: Set reasonable timeouts for all ACP requests
Cache Responses: Cache analysis results and workspace information when appropriate
Provide Feedback: Show loading states and progress for long-running operations

Security Considerations

Validate Inputs: Sanitize all user inputs before sending to ACP
Limit Scope: Use minimal required permissions for ACP operations
Secure Transport: Use encrypted connections in production environments
Token Management: Implement proper token refresh and expiration handling

Performance Optimization

Batch Requests: Combine multiple related operations into single requests
Lazy Loading: Only load workspace context when needed
Debounce Inputs: Debounce user inputs to avoid excessive API calls
Background Processing: Use background threads for non-blocking operations

Next Steps:

AI Chat & Analysis - Understanding chat capabilities accessible via ACP
Agent Execution - Agent workers available through ACP integration
Command Reference - Complete CLI command documentation

Lovelace Developer Portal

Editor Integration Guide

Overview

Understanding ACP

What is Agent Client Protocol?

ACP vs Direct CLI Usage

ACP Server Management

Start ACP Server

Server Status and Control

Editor Integrations

VS Code Extension

Zed Editor Integration

Custom Editor Integration

ACP Protocol Reference

Core Methods

Chat Operations

Analysis Operations

Agent Operations

Workspace Operations

Response Format

Development Workflow Integration

Code Review Workflow

Interactive Development

Configuration

ACP Server Configuration

Editor-Specific Settings

VS Code Configuration

Zed Configuration

Troubleshooting

Connection Issues

Authentication Issues

Performance Issues

Best Practices

Integration Development

Security Considerations

Performance Optimization

Lovelace Developer Portal