Skip to content

docs: acp clients #5800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dianed-square merged 2 commits into from
Nov 18, 2025
Merged

docs: acp clients #5800

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
91f2571
update acp clients
dianed-square Nov 18, 2025
7807cd2
revise label and add additional resources
dianed-square Nov 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 31 additions & 28 deletions documentation/docs/guides/acp-clients.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,43 @@
---
sidebar_position: 105
title: Using Goose in ACP Clients
sidebar_label: Goose in ACP Clients
title: Using goose in ACP Clients
sidebar_label: goose in ACP Clients
---

Client applications that support the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) can connect natively to Goose. This integration allows you to seamlessly interact with Goose directly from the client.
Client applications that support the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) can connect natively to goose. This integration allows you to seamlessly interact with goose directly from the client.

:::warning Experimental Feature
ACP is an emerging specification that enables clients to communicate with AI agents like Goose. This feature has limited adoption and may evolve as the protocol develops.
ACP is an emerging specification that enables clients to communicate with AI agents like goose. This feature has limited adoption and may evolve as the protocol develops.
:::

## How It Works
After you configure Goose as an agent in the ACP client, you gain access to Goose's core agent functionality, including its extensions and tools.
After you configure goose as an agent in the ACP client, you gain access to goose's core agent functionality, including its extensions and tools.

The client manages the Goose lifecycle automatically, including:
The client manages the goose lifecycle automatically, including:

- **Initialization**: The client runs the `goose acp` command to initialize the connection
- **Communication**: The client communicates with Goose over stdio using JSON-RPC
- **Multiple Sessions**: The client manages multiple concurrent Goose conversations simultaneously
- **Communication**: The client communicates with goose over stdio using JSON-RPC
- **Multiple Sessions**: The client manages multiple concurrent goose conversations simultaneously

:::info Session Persistence
ACP sessions are not currently persisted between client restarts or accessible from Goose session history.
ACP sessions are saved to goose's session history where you can access and manage them using goose. However, these sessions aren't persisted in ACP clients, so you'll need to start a new conversation each time you restart the client.
:::

## Zed Editor Setup
## Setup in ACP Clients
Any editor or IDE that supports ACP can connect to goose as an agent server. Check the [official ACP clients list](https://agentclientprotocol.com/overview/clients) for available clients with links to their documentation.

[Zed](https://zed.dev/) is the primary ACP-compatible editor. Here's how to integrate Goose:
### Example: Zed Editor Setup

### 1. Prerequisites
ACP was originally developed by [Zed](https://zed.dev/). Here's how to configure goose in Zed:

Ensure you have both Zed and Goose CLI installed:
#### 1. Prerequisites

Ensure you have both Zed and goose CLI installed:

- **Zed**: Download from [zed.dev](https://zed.dev/)
- **Goose CLI**: Follow the [installation guide](/docs/getting-started/installation)
- **goose CLI**: Follow the [installation guide](/docs/getting-started/installation)

- ACP support requires version 1.8.0 or later - check with `goose --version`.
- ACP support works best with version 1.14.2 or later - check with `goose --version`.

- Temporarily run `goose acp` to test that ACP support is working:

Expand All @@ -45,18 +48,18 @@ Ensure you have both Zed and Goose CLI installed:

Press `Ctrl+C` to exit the test.

### 2. Configure Goose as a Custom Agent
#### 2. Configure goose as a Custom Agent

Add Goose to your Zed settings:
Add goose to your Zed settings:

1. Open Zed
2. Press `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows) to open settings
2. Press `Cmd+Option+,` (macOS) or `Ctrl+Alt+,` (Linux/Windows) to open the settings file
3. Add the following configuration:

```json
{
"agent_servers": {
"Goose 🪿": {
"goose CLI 🪿": {
Copy link
Contributor

@blackgirlbytes blackgirlbytes Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm why the cli part is added?

Copy link
Contributor Author

@dianed-square dianed-square Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To sync the label with the other agents. Otherwise it just would say "New goose 🪿" now (used to be "New Goose 🪿 Thread").
image

"command": "goose",
"args": ["acp"],
"env": {}
Expand All @@ -66,32 +69,32 @@ Add Goose to your Zed settings:
}
```

You should now be able to interact with Goose directly in Zed. Your ACP sessions use the same extensions that are enabled in your Goose configuration, and your tools (Developer, Computer Controller, etc.) work the same way as in regular Goose sessions.
You should now be able to interact with goose directly in Zed. Your ACP sessions use the same extensions that are enabled in your goose configuration, and your tools (Developer, Computer Controller, etc.) work the same way as in regular goose sessions.

### 3. Start Using Goose in Zed
#### 3. Start Using goose in Zed

1. **Open the Agent Panel**: Click the sparkles agent icon in Zed's status bar
2. **Create New Thread**: Click the `+` button to show thread options
3. **Select Goose**: Choose `New Goose 🪿 Thread` to start a new conversation with Goose
4. **Start Chatting**: Interact with Goose directly from the agent panel
3. **Select goose**: Choose `New goose CLI 🪿` to start a new conversation with goose
4. **Start Chatting**: Interact with goose directly from the agent panel

### Advanced Configuration
#### Advanced Configuration

By default, Goose will use the provider and model defined in your [configuration file](/docs/guides/config-files). You can override this for specific ACP configurations using the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment variables.
By default, goose will use the provider and model defined in your [configuration file](/docs/guides/config-files). You can override this for specific ACP configurations using the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment variables.

The following Zed settings example configures two Goose agent instances. This is useful for:
The following Zed settings example configures two goose agent instances. This is useful for:
- Comparing model performance on the same task
- Using cost-effective models for simple tasks and powerful models for complex ones

```json
{
"agent_servers": {
"Goose 🪿": {
"goose CLI 🪿": {
Copy link
Contributor

@blackgirlbytes blackgirlbytes Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why is it added here as well? is that actually needed? and could we take out the 🪿

I think these are both just how it will show up in zed

"command": "goose",
"args": ["acp"],
"env": {}
},
"Goose (GPT-4o)": {
"goose CLI (GPT-4o)": {
"command": "goose",
"args": ["acp"],
"env": {
Expand Down
Loading