Connect an ACP editor

Use the Bub application from an editor that supports the Agent Client Protocol. The bub-acp-server plugin connects the editor to the app’s existing model configuration, tools, and conversation history.

This guide uses Zed and starts the agent process over stdio. Check the CLI connection first, then add it to your editor.

Before you begin

You need:

• Bub installed in a Python environment where you can run bub --help.
• A working Bub model configuration. Confirm this outside the editor first with bub run.
• An editor or client that can launch a custom ACP agent. This tutorial uses Zed.

The ACP process reads the same Bub configuration and environment variables as bub run and bub chat.

1. Install the ACP server plugin

bub-acp-server lives in bubbuild/bub-contrib. Install it into the same environment that provides your bub command:

bub install bub-acp-server@main

Verify that the command is available:

bub acp --help

Expected output includes:

Usage: bub acp [OPTIONS]

If bub acp is missing, the plugin was installed into a different Python environment than the one your shell resolves as bub.

2. Check Bub before adding the editor

Run one turn from the same shell or environment that your editor will use:

bub run "Reply with one short sentence: hello from Bub."

Resolve any configuration or network errors here before connecting the editor.

If your Bub configuration is stored in a project .env, make sure the ACP process starts with that environment loaded. One portable way is to create a small wrapper script:

#!/usr/bin/env bash
set -euo pipefail
cd /path/to/your/project
set -a
. ./.env
set +a
exec bub acp

Use this wrapper only when you need it. If bub run already works from the editor’s environment, you can launch bub acp directly.

3. Configure Zed

Open Zed’s settings with zed: open settings and add a custom agent server:

{
  "agent_servers": {
    "Bub": {
      "type": "custom",
      "command": "bub",
      "args": ["acp"],
      "env": {}
    }
  }
}

If Zed cannot find bub, use an absolute path or the wrapper script from the previous step:

{
  "agent_servers": {
    "Bub": {
      "type": "custom",
      "command": "/path/to/bub-acp-wrapper",
      "args": [],
      "env": {}
    }
  }
}

Keep editor configuration and Bub configuration separate. Zed starts the ACP process and passes the environment you put under agent_servers.Bub.env; Bub still owns its model settings, tools, skills, tapes, and plugin configuration.

4. Start a Bub thread

Reload Zed after saving settings. Open the agent panel with cmd-? on macOS or ctrl-? on Linux and Windows, then use the + button to create a new thread and select Bub.

Send a small message such as:

HELLO

You should see Bub respond in the agent panel. Tool calls and streamed model text are forwarded as ACP session updates, so the editor can show activity while the turn is running.

When the editor reopens an existing thread, bub-acp-server loads the matching Bub tape and replays it through the same ACP streaming path used by live turns. That keeps restored user messages, assistant text, and tool events aligned with how Bub records the session.

Troubleshooting

Symptom	Check
bub acp is missing	Reinstall bub-acp-server into the environment that provides the bub executable used by the editor.
The editor says it cannot start Bub	Use an absolute command path, or point command at a wrapper script that activates the right environment.
Bub starts but reports a configuration error	Confirm bub run works in the same environment. If required settings are in .env, load that file before bub acp.
The editor cannot load or resume a thread	Confirm the editor is launching the same bub environment where bub acp --help works, and keep BUB_HOME stable across launches.
Previous threads disappear after restarting the editor	Keep the same Bub environment and BUB_HOME across launches. bub-acp-server stores ACP session metadata under Bub home and loads history from Bub tapes.
A turn starts but no activity is visible	Open Zed’s dev: open acp logs command and inspect the JSON-RPC messages between Zed and Bub.

Next steps

• Configure: Bub’s model and runtime settings.
• Turn pipeline: how Bub turns inbound messages into model calls and outbound messages.
• Build plugins: extend Bub with hooks, tools, and channels.