# Agent Client Protocol

V3Code can host compatible external agents in native chat through the **Agent Client
Protocol (ACP)**. You choose the agent; it keeps its own identity and conversation while
V3Code keeps the editor, workspace context, and approval boundaries visible.

Compatible agents appear beside V3Code in the compact agent picker. Choosing one opens a
new native chat with that agent's identity, approvals, diffs, and advertised slash
commands instead of squeezing it into the current V3Code conversation.

## Before you begin

- Install the agent using its own documentation.
- Open the project folder you want that agent to work in.
- Keep V3Code up to date. ACP setup guidance described here is available in
  **1.4.9-0098** and later.

## Add an agent

![Agents settings showing an external agent with setup, chat, and per-agent access controls](/images/agent-settings-0098.png)

Choose Memory / Index and Browser access before opening a new agent chat. Launcher available does not prove sign-in is complete. Screenshot supplied September 17, 2026.

1. Start a new chat and open the agent menu.
2. Choose **Add agents** to open the relevant Settings screen.
3. Enable a listed agent, or choose **Add custom agent** and enter the command that starts
   its ACP stdio process.
4. Choose which editor capabilities new chats receive:
   - **Memory / Index** shares the workspace-scoped V3Code context bridge.
   - **Browser** shares the native browser through the authenticated bridge. Turn this on
     before opening the chat; existing chats do not gain it later.
5. Return to the agent menu and select the agent to begin a new conversation.

Selecting an agent creates a separate agent chat. It does not send the current chat
transcript to that agent, and it does not close your editor tabs.

If V3Code Terminal is already installed, **Add V3Code Terminal** registers its `v3code
acp` command. The button does not install the terminal or sign you in.

## Complete setup or sign-in deliberately

An agent marked **Launcher available** can be started from your machine, but it may
still need its own installation, account setup, or sign-in.

Use **Setup / sign in** when it is available. V3Code opens an integrated terminal and
can stage a single reviewed command for you. Read it before continuing, then press Enter
yourself if it is correct. V3Code does not run setup commands automatically, copy account
credentials, or complete a sign-in flow on your behalf.

If the setup screen is empty or the command is not familiar, use the agent's own
documentation instead of guessing a package command.

When an agent supports managed authentication, it may ask for consent inside chat before
starting its authentication method. Terminal-only sign-in still happens in that agent's
own tooling. V3Code does not automatically download agent binaries.

## Keep project context accurate

ACP chats are tied to the workspace they started in. Reading a file outside that folder
does not retarget V3Code's index, memory, or workspace-scoped context.

To work in another project:

1. Open that folder in V3Code, optionally in another window.
2. Start a **new** agent chat in that folder.
3. Wait for the index to report ready before expecting indexed search or workspace
   context to be available.

You can still use an agent while an index is building. It simply should not claim that
indexed project context is ready until V3Code says it is.

## When something is not working

- **The agent is listed but will not run:** complete its documented install or sign-in
  first. Launcher detection alone does not verify authentication.
- **The wrong project is in context:** open the correct folder and begin a new agent chat.
- **Indexed search is unavailable:** check index readiness, then let the local index
  finish before retrying the question.
- **An advertised slash command is missing:** start a new agent chat after setup. Commands
  are negotiated when the ACP session starts.
- **You need code intelligence in another client instead:** use the
  [MCP connection](/connect/other-agents), which is a separate local integration.

> Note:
>
> External agents are separate local programs and keep the operating-system permissions
> of the user who launched them. V3Code displays protocol-routed approvals and diffs; it
> is not an operating-system sandbox for the external process.