Skip to content

Latest commit

 

History

History
239 lines (173 loc) · 7.29 KB

editor-integration.mdx

File metadata and controls

239 lines (173 loc) · 7.29 KB
title description icon
Editor Integration (ACP)
Integrate Agent Relay with code editors using the Agent Client Protocol
code

Editor Integration with ACP

Agent Relay can be integrated with code editors like Zed, VS Code, Neovim, and other editors that support the Agent Client Protocol (ACP).

What is ACP?

The Agent Client Protocol is an open standard (created by Zed Industries) that enables AI agents to integrate with code editors. Think of it as LSP (Language Server Protocol), but for AI coding agents.

ACP provides:

  • Standardized communication between editors and AI agents
  • Session management for conversations
  • Tool permissions and file operations
  • Streaming responses

Architecture

The ACP bridge connects your editor to all your relay agents:

┌─────────────────┐     ACP (stdio)    ┌─────────────────┐
│   Zed Editor    │ ◄────────────────► │  relay-acp      │
│   (or other)    │   JSON-RPC 2.0     │  (bridge)       │
└─────────────────┘                    └────────┬────────┘
                                                │
                                       Relay Protocol
                                                │
                                       ┌────────▼────────┐
                                       │  Relay Daemon   │
                                       └────────┬────────┘
                                                │
                        ┌───────────────────────┼───────────────────────┐
                        │                       │                       │
                   Agent 1                 Agent 2                 Agent N
                   (Claude)                (Codex)                 (any CLI)

When you send a prompt from your editor:

  1. The editor sends the prompt via ACP to the bridge
  2. The bridge broadcasts to all connected relay agents
  3. Agents respond through the relay daemon
  4. The bridge streams responses back to the editor

Quick Start (Zed)

<video controls className="w-full aspect-video rounded-xl" src="/videos/zed-acp-agent-relay.mp4"

Your browser does not support the video tag.

1. Start the Daemon and Configure Zed

agent-relay up --zed

This starts the relay daemon and auto-configures Zed's ~/.config/zed/settings.json with the correct paths for your workspace.

2. Spawn Some Agents

Create agents that will respond to editor prompts:

# Spawn a code review agent
agent-relay spawn Reviewer claude "Review code changes and suggest improvements"

# Spawn an architect agent
agent-relay spawn Architect claude "Help with system design and architecture decisions"

3. Start Chatting

Open Zed's Agent Panel with Cmd+? (macOS) or Ctrl+? (Windows/Linux), select "Agent Relay", and start typing. You can:

  • Broadcast to all agents: Just type your message
  • Target specific agents: Use @AgentName (e.g., @Reviewer check this code)

Run Relay Commands from Zed

From the Zed Agent Panel you can issue relay CLI-style commands directly (the bridge intercepts them, no shell required):

  • agent-relay spawn Reviewer claude "Review the current changes"
  • agent-relay release Reviewer
  • agent-relay agents (lists connected agents)

Currently supported commands: spawn/create-agent, release, agents/who. All other messages are still broadcast to your connected agents. A quick help block is shown when a new conversation starts; type agent-relay help to see it again.

Troubleshooting

Bridge not connecting to daemon

Ensure the relay daemon is running:

agent-relay status

If not running, start it:

agent-relay up

No responses from agents

Check if any agents are connected:

agent-relay who

If no agents are listed, spawn some:

agent-relay spawn Worker claude "Help with coding tasks"

Other Editors (Advanced)

For editors other than Zed, you'll need to install the ACP bridge package and configure your editor manually.

Programmatic Usage

You can use the bridge programmatically in your own tools:

import { RelayACPAgent } from '@agent-relay/acp-bridge';

const agent = new RelayACPAgent({
  agentName: 'my-custom-bridge',
  socketPath: '/tmp/relay-daemon.sock',
  debug: true,
  capabilities: {
    supportsSessionLoading: false,
  },
});

await agent.start();

Configuration Options

Option Type Default Description
agentName string 'relay-acp' Name used when connecting to relay daemon
socketPath string auto Path to relay daemon socket
debug boolean false Enable debug logging
capabilities object - ACP capabilities to advertise

Installation

npm install -g @agent-relay/acp-bridge

Or build from source:

cd packages/acp-bridge
npm install
npm run build
npm link

Neovim

Requires an ACP-compatible Neovim plugin (e.g., acp.nvim):

require('acp').setup({
  agents = {
    {
      name = "Agent Relay",
      command = "relay-acp",
      args = {
        "--name", "nvim-bridge",
        "--socket", "/path/to/your/project/.agent-relay/relay.sock"
      }
    }
  }
})

VS Code

The vscode-acp extension brings ACP support to VS Code. Install it from the marketplace:

  1. Open VS Code Extensions (Cmd+Shift+X / Ctrl+Shift+X)
  2. Search for "vscode-acp"
  3. Click Install

Current limitation: The extension auto-detects agents from a built-in list (Claude Code, OpenCode, Codex, Gemini, etc.) and doesn't yet support custom agents like Agent Relay. You can use any of the supported agents, which will work alongside your relay agents if they're running.

We're working with the vscode-acp maintainer to add custom agent support. Track progress at omercnet/vscode-acp.

Other ACP-Compatible Editors

For any editor that supports the Agent Client Protocol, configure it to run:

relay-acp --name my-editor-bridge --socket /path/to/.agent-relay/relay.sock

The bridge communicates via stdio using newline-delimited JSON (ACP protocol).

Manual Zed Configuration

If you prefer not to use --zed, add this to ~/.config/zed/settings.json:

{
  "agent_servers": {
    "Agent Relay": {
      "type": "custom",
      "command": "relay-acp",
      "args": [
        "--name", "zed-bridge",
        "--socket", "/path/to/your/project/.agent-relay/relay.sock",
        "--debug"
      ],
      "env": {}
    }
  }
}

Related