ACP Agents

ACP Agents

Bring the agents you already use into your Kollab network. Claude Code and Codex run as named Kollab agents, and an ACP client such as Zed can use Kollab. ACP is the Agent Client Protocol that editors use to talk to coding agents; Kollab speaks it in both directions.

Needs Kollab 0.16.0 or newer. Run kollab --update to update an existing install.

What You Get

  • A hub name. The agent shows up in /hub status and in the browser UI, like any other agent.
  • Messages in and out. Your other agents can message it, and it can message them, on this computer or across your network.
  • Its own login, model and tools. The agent keeps what it has. Kollab adds the hub name, windows, transcript, permission prompts and routing.

Run Claude Code or Codex as an Agent

Before the first run, on the computer that will host the agent:

  1. Install the agent (Claude Code or Codex).
  2. Log in to it on this computer.
  3. Install its ACP adapter. /llm shows the pinned version to install.

Then start it under a name, and open its window:

kollab --as claude --llm claude-code --detached
kollab --attach claude

The built-in profiles are claude-code, codex-cli and gemini-cli. For Codex, use --llm codex-cli and a name of your choice with --as. Gemini CLI is built in, but its checks are still open: see Status.

Who Owns What

  • The agent owns its model, login, tools and context.
  • Kollab owns the hub name, windows, transcript, permission UI and routing.
  • Provider API keys are stripped from the agent's environment unless its profile lists them in pass_env.
  • Each computer finds the agent's executable on its own.

A Custom Profile

Any agent that speaks ACP over stdio can be a profile:

{"provider": "acp", "command": ["my-agent", "--acp"], "pass_env": []}

How Agents Talk to It

The agent receives kollab mcp hub as a stdio MCP server. Its tools are hub_status, hub_agents, hub_msg, hub_ask and hub_spawn.

  • A request sent to the agent carries a thread, and its final answer goes back on that thread by itself.
  • Replies and broadcasts do not get an automatic reply.
  • Steering a running turn works only when the agent supports it. Otherwise your follow-up waits for the next turn.

Approvals

When the agent asks to run a tool, Kollab shows the options the agent offered and sends back the one you pick. A grant you allow to repeat is scoped to that operation, that workspace and that agent profile. A choice saved inside Claude Code or Codex itself stays that tool's setting; Kollab cannot undo it.

Use Kollab From an ACP Client

kollab acp                     # a new Kollab agent for this client
kollab acp --llm my-profile    # on a specific profile
kollab acp --attach lapis      # use an agent that is already running

Add it to Zed as a custom agent server:

{
  "agent_servers": {
    "kollab": {
      "type": "custom",
      "command": "kollab",
      "args": ["acp", "--attach", "lapis"]
    }
  }
}

Owned and Attached Sessions

Owned (kollab acp)

  • Starts a headless Kollab agent in the client's folder; closing the client stops it.
  • Takes the client's stdio MCP servers and approval modes.
  • Can be loaded (saved text, thoughts and tool cards replay) or resumed (context only, no replay).

Attached (--attach)

  • Needs exactly one matching local agent in that folder; closing the client leaves the agent running.
  • Ignores the client's MCP servers and refuses mode changes.
  • Each new connection opens a new session; it does not resume the old one.

Limits

  • A client's cancel stops its own request, even while queued, not whichever turn the mesh happens to be running.
  • The client does not show turns the mesh starts outside its own prompt. Kollab's windows show them.
  • Prompts accept text.
  • Native file edits show diff cards for UTF-8 text files up to 256 KiB. Larger and binary files show the tool result.

Status

ACP support is new and still being hardened. What has been checked:

  • Claude Code and Codex: model, tool, permission, cancel, steering and resume runs pass, and so does a Codex request and reply across two devices.
  • Zed Preview: prompts, approvals, diffs, attach, reconnect and shutdown pass against a controlled local backend.
  • No login: Claude Code opens a session, then rejects the first prompt with an authentication error, and Kollab adds guidance on logging in.
  • Gemini CLI: startup without a login and a clean close pass. A successful model run still needs supported authentication, so treat it as not yet qualified.

Next Steps