From c9037391aa0dd7f443eb0f13b521e3c47694a56a Mon Sep 17 00:00:00 2001 From: Diane Diaz Date: Wed, 24 Sep 2025 08:53:28 -0700 Subject: [PATCH 1/2] acp support --- documentation/docs/guides/acp-clients.md | 105 ++++++++++++++++++ .../docs/guides/goose-cli-commands.md | 16 +++ 2 files changed, 121 insertions(+) create mode 100644 documentation/docs/guides/acp-clients.md diff --git a/documentation/docs/guides/acp-clients.md b/documentation/docs/guides/acp-clients.md new file mode 100644 index 000000000000..5aa46dfda549 --- /dev/null +++ b/documentation/docs/guides/acp-clients.md @@ -0,0 +1,105 @@ +--- +sidebar_position: 25 +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. + +:::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. +::: + +## 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. + +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 + +:::info Session Persistence +ACP sessions are not currently persisted between client restarts or accessible from Goose session history. +::: + +## Zed Editor Setup + +[Zed](https://zed.dev/) is the primary ACP-compatible editor. Here's how to integrate Goose: + +### 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) + + - ACP support requires version 1.8.0 or later - check with `goose --version`. + + - Temporarily run `goose acp` to test that ACP support is working: + + ``` + ~ goose acp + Goose ACP agent started. Listening on stdio... + ``` + + Press `Ctrl+C` to exit the test. + +### 2. Configure Goose as a Custom Agent + +Add Goose to your Zed settings: + +1. Open Zed +2. Press `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows) to open settings +3. Add the following configuration: + +```json +{ + "agent_servers": { + "Goose 🪿": { + "command": "goose", + "args": ["acp"], + "env": {} + } + }, + // more 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. + +### 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 + +### Advanced Configuration + +By default, Goose will use the provider and model defined in your [configuration file](/docs/guides/config-file). You can override these settings for specific ACP configurations using the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment variables. + +The following 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 🪿": { + "command": "goose", + "args": ["acp"], + "env": {} + }, + "Goose (GPT-4o)": { + "command": "goose", + "args": ["acp"], + "env": { + "GOOSE_PROVIDER": "openai", + "GOOSE_MODEL": "gpt-4o" + } + } + }, + // more settings +} +``` diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index 8a7cc2e6148d..01aa660b00e0 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -341,6 +341,22 @@ goose mcp --- +#### acp +Run Goose as an Agent Client Protocol (ACP) agent server over stdio. This enables Goose to work with ACP-compatible clients like Zed. + +ACP is an emerging protocol specification that standardizes communication between AI agents and client applications, making it easier for clients to integrate with various AI agents. + +**Usage:** +```bash +goose acp +``` + +:::info +This command is automatically invoked by ACP-compatible clients and is not typically run directly by users. The client manages the lifecycle of the `goose acp` process. See [Using Goose in ACP Clients](/docs/guides/acp-clients) for details. +::: + +--- + ### Project Management #### project From d74feb20114c3e6b1f1fdb8c90ca32a009e04759 Mon Sep 17 00:00:00 2001 From: Diane Diaz Date: Wed, 24 Sep 2025 10:17:48 -0700 Subject: [PATCH 2/2] clarify zed settings --- documentation/docs/guides/acp-clients.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/docs/guides/acp-clients.md b/documentation/docs/guides/acp-clients.md index 5aa46dfda549..1840f5b924c5 100644 --- a/documentation/docs/guides/acp-clients.md +++ b/documentation/docs/guides/acp-clients.md @@ -77,9 +77,9 @@ You should now be able to interact with Goose directly in Zed. Your ACP sessions ### Advanced Configuration -By default, Goose will use the provider and model defined in your [configuration file](/docs/guides/config-file). You can override these settings 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-file). You can override this for specific ACP configurations using the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment variables. -The following 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