ACP Editor Integration

VibeOS can run as an ACP server, letting ACP-compatible editors talk to VibeOS 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 VibeOS to behave like an editor-native coding agent instead of a standalone CLI or messaging bot.

What VibeOS exposes in ACP mode

VibeOS runs with a curated vibeos-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 VibeOS normally, then add the ACP extra:

pip install -e '.[acp]'

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

• vibeos acp
• vibeos-acp
• python -m acp_adapter

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

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

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

Launching the ACP server

Any of the following starts VibeOS in ACP mode:

vibeos acp

vibeos-acp

python -m acp_adapter

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

For non-interactive checks:

vibeos acp --version
vibeos 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:

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

This is the standalone command. The Zed registry's terminal-auth flow (vibeos 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 ~/.vibeos/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 VibeOS-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 VibeOS from the built-in agent list.
3. Connect and start chatting.

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

{
  "acp.agents": {
    "VibeOS": {
      "command": "vibeos",
      "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 VibeOS.
4. Install it and start a new VibeOS external-agent thread.

Prerequisites:

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

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

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

JetBrains

Use an ACP-compatible plugin and point it at:

/path/to/vibeos-agent/acp_registry

Registry manifest

The source copy of VibeOS' 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 vibeos-agent/ directory in agentclientprotocol/registry.

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

uvx --from 'vibeos-agent[acp]==<version>' vibeos-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 VibeOS configuration as the CLI:

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

Provider resolution uses VibeOS' normal runtime resolver, so ACP inherits the currently configured provider and credentials. VibeOS also advertises a terminal auth method (--setup) for first-run registry clients; this opens VibeOS' 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 VibeOS' 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 VibeOS 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 VibeOS 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 VibeOS' 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 VibeOS.
• For manual/local development, verify the custom agent_servers command points to vibeos acp.
• VibeOS 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:

vibeos acp --version
vibeos acp --check
vibeos doctor
vibeos status

Missing credentials

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

vibeos model

or by editing ~/.vibeos/.env. Registry clients can also trigger VibeOS' 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 VibeOS thread from Zed.

See also

• ACP Internals
• Provider Runtime Resolution
• Tools Runtime