ACP Editor Integration

AigenLabs Agent can run as an ACP server, letting ACP-compatible editors talk to AigenLabs over stdio and render:

• chat messages
• tool activity
• file diffs
• terminal commands
• approval prompts
• streamed thinking / response chunks

ACP is a good fit when you want AigenLabs to behave like an editor-native coding agent instead of a standalone CLI or messaging bot.

What AigenLabs exposes in ACP mode

AigenLabs runs with a curated aigenlabs-acp toolset designed for editor workflows. It includes:

• file tools: read_file, write_file, patch, search_files
• terminal tools: terminal, process
• web/browser tools
• memory, todo, session search
• skills
• execute_code and delegate_task
• vision

It intentionally excludes things that do not fit typical editor UX, such as messaging delivery and cronjob management.

Installation

Install AigenLabs normally, then add the ACP extra:

pip install -e '.[acp]'

This installs the agent-client-protocol dependency and enables:

• aigenlabs acp
• aigenlabs-acp
• python -m acp_adapter

For Zed registry installs, Zed launches AigenLabs through the official ACP Registry entry. That entry uses a uvx distribution that runs:

uvx --from 'aigenlabs-agent[acp]==<version>' aigenlabs-acp

Make sure uv is available on PATH before using the registry install path.

Launching the ACP server

Any of the following starts AigenLabs in ACP mode:

aigenlabs acp

aigenlabs-acp

python -m acp_adapter

AigenLabs logs to stderr so stdout remains reserved for ACP JSON-RPC traffic.

For non-interactive checks:

aigenlabs acp --version
aigenlabs acp --check

Browser tools (optional)

Browser tools (browser_navigate, browser_click, etc.) depend on the agent-browser npm package and Chromium, which aren't part of the Python wheel. Install them with:

aigenlabs acp --setup-browser           # interactive (prompts before ~400 MB download)
aigenlabs acp --setup-browser --yes     # accept the download non-interactively

This is the standalone command. The Zed registry's terminal-auth flow (aigenlabs acp --setup) also offers the browser bootstrap as a follow-up question after model selection, so most users never need to run --setup-browser directly.

What it does:

• Installs Node.js 22 LTS into ~/.aigenlabs/node/ if missing
• npm install -g agent-browser @askjo/camofox-browser into that prefix (no sudo needed — npm's --prefix points at the user-writable AigenLabs-managed Node)
• Installs Playwright Chromium, or uses a detected system Chrome/Chromium when available

The bootstrap is idempotent — re-running it is fast and skips work that's already done.

Editor setup

VS Code

Install the ACP Client extension.

To connect:

1. Open the ACP Client panel from the Activity Bar.
2. Select AigenLabs Agent from the built-in agent list.
3. Connect and start chatting.

If you want to define AigenLabs manually, add it through VS Code settings under acp.agents:

{
  "acp.agents": {
    "AigenLabs Agent": {
      "command": "aigenlabs",
      "args": ["acp"]
    }
  }
}

Zed

Zed v0.221.x and newer installs external agents through the official ACP Registry.

1. Open the Agent Panel.
2. Click Add Agent, or run the zed: acp registry command.
3. Search for AigenLabs Agent.
4. Install it and start a new AigenLabs external-agent thread.

Prerequisites:

• Configure AigenLabs provider credentials first with aigenlabs model, or set them in ~/.aigenlabs/.env / ~/.aigenlabs/config.yaml.
• Install uv so the registry launcher can run uvx --from 'aigenlabs-agent[acp]==<version>' aigenlabs-acp.

For local development before the registry entry is available, use a custom agent server in Zed settings:

{
  "agent_servers": {
    "aigenlabs-agent": {
      "type": "custom",
      "command": "aigenlabs",
      "args": ["acp"]
    }
  }
}

JetBrains

Use an ACP-compatible plugin and point it at:

/path/to/aigenlabs-agent/acp_registry

Registry manifest

The source copy of AigenLabs' official ACP Registry metadata lives at:

acp_registry/agent.json
acp_registry/icon.svg

The upstream registry PR copies those files into the top-level aigenlabs-agent/ directory in agentclientprotocol/registry.

The registry entry uses a uvx distribution that points directly at the aigenlabs-agent PyPI release:

uvx --from 'aigenlabs-agent[acp]==<version>' aigenlabs-acp

The registry CI verifies that the pinned version exists on PyPI, so the manifest's version and uvx package pin must always match pyproject.toml. scripts/release.py keeps them in lockstep automatically.

Configuration and credentials

ACP mode uses the same AigenLabs configuration as the CLI:

• ~/.aigenlabs/.env
• ~/.aigenlabs/config.yaml
• ~/.aigenlabs/skills/
• ~/.aigenlabs/state.db

Provider resolution uses AigenLabs' normal runtime resolver, so ACP inherits the currently configured provider and credentials. AigenLabs also advertises a terminal auth method (--setup) for first-run registry clients; this opens AigenLabs' interactive model/provider setup.

Session behavior

ACP sessions are tracked by the ACP adapter's in-memory session manager while the server is running.

Each session stores:

• session ID
• working directory
• selected model
• current conversation history
• cancel event

The underlying AIAgent still uses AigenLabs' normal persistence/logging paths, but ACP list/load/resume/fork are scoped to the currently running ACP server process.

Working directory behavior

ACP sessions bind the editor's cwd to the AigenLabs task ID so file and terminal tools run relative to the editor workspace, not the server process cwd.

Approvals

Dangerous terminal commands can be routed back to the editor as approval prompts. ACP approval options are simpler than the CLI flow:

• allow once
• allow always
• deny

On timeout or error, the approval bridge denies the request.

Session-scoped edit auto-approval

ACP exposes a third tier between allow once and allow always: Allow for session. Picking it from the editor's permission prompt records the approval inside the current ACP session only — every subsequent matching command in that session goes through without prompting, but a new ACP session (or restarting the editor) resets the slate and re-prompts the first time.

Option	Editor label	Scope	Persisted across restarts
allow_once	Allow once	This one tool call	No
allow_session	Allow for session	All matching calls in this ACP session	No — cleared when the session ends
allow_always	Allow always	All future sessions	Yes (written to the AigenLabs permanent allowlist)
deny	Deny	This one tool call	No

allow_session is the right default for an editor workflow where you trust an agent for the duration of a task but don't want to grant a long-lived allowlist entry. The safety trade-off is straightforward: the broader the scope, the less the editor will interrupt you, and the more damage a misbehaving agent (or prompt injection) can do before you notice. Start with allow_once for unfamiliar commands; promote to allow_session once you've seen the agent run the same pattern correctly a few times; reserve allow_always for truly idempotent commands you trust forever (e.g. git status).

The ACP bridge maps these options onto AigenLabs' internal approval semantics — allow_always writes a permanent allowlist entry the same way the CLI does, while allow_session only affects the in-process approval cache for the current ACP session.

Troubleshooting

ACP agent does not appear in the editor

Check:

• In Zed, open the ACP Registry with zed: acp registry and search for AigenLabs Agent.
• For manual/local development, verify the custom agent_servers command points to aigenlabs acp.
• AigenLabs is installed and on your PATH.
• The ACP extra is installed (pip install -e '.[acp]').
• uv is installed if launching from the official Zed registry entry.

ACP starts but immediately errors

Try these checks:

aigenlabs acp --version
aigenlabs acp --check
aigenlabs doctor
aigenlabs status

Missing credentials

ACP mode uses AigenLabs' existing provider setup. Configure credentials with:

aigenlabs model

or by editing ~/.aigenlabs/.env. Registry clients can also trigger AigenLabs' terminal auth flow, which runs the same interactive provider/model setup.

Zed registry launcher cannot find uv

Install uv from the official uv installation docs, then retry the AigenLabs Agent thread from Zed.

See also

• ACP Internals
• Provider Runtime Resolution
• Tools Runtime