Skip to main content

Sharing a Goose Agent

A shared Agent in Goose is like a collaborative workspace where multiple people can work with the AI assistant together in real-time. Think of it similar to a shared Google Doc, but for AI assistance.

Create a shared Agent​

When you create an Agent to be shared, you are creating a host Agent. When your host terminates, the shared Agents are disconnected and collaborators can no longer see activity in the host.

Setup recipe​

To create a custom session (whether using the desktop app or CLI), you'll need:

  • Instructions for the AI
  • Activities it should perform
  • A custom prompt (optional)

The CLI calls this a "recipe." The desktop app shows these same options in the Agent Created dialog when you create a new shared session.

tip

Both tools need the same information, they just use different names for it.

Agent setup instructions​

When you share your Goose Agent setup (either through the command line or desktop app), you'll get a chance to review and edit the setup instructions. These instructions come from your current session, but they might need some extra details to work well for others.

Here's an example: Let's say you were working with Goose to make debug a new application and you need help with the debug logs. In this case, you should add a note like this to your instructions:

"I asked Goose to review the debug logs from this application: https://github.com/square/connect-api-examples/tree/master/connect-examples/v2/node_orders-payments. The log files are in this folder: https://github.com/square/connect-api-examples/blob/master/my_app/v2/logs/"

This tells the new shared Agent (or new local session) what the context is for your debugging collaboration. The critical context that the shared Agent (or session) needs is the location of the application source code and the folder where log files are written. With this context, the teammate you are working with can ask Goose to clone the GitHub repo, open the project in an IDE, and build the project.

Agent setup activities​

When you work with Goose, it keeps track of everything you do together. Before sharing your setup with others, you should review this list of activities. Think of it like cleaning up your workspace before inviting colleagues over:

  • Look at the list of activities when creating your shared setup
  • Pick only the activities that matter for your project
  • Remove any activities that aren't relevant for your teammates

For example: If you used Goose for both writing the application UI and helping you debug it, but only want to share the debugging part, you can remove the coding the application activities.

To create a shared Agent using the CLI, you need a recipe. Think of a Goose "recipe" like a blueprint - it contains the instructions to recreate your agent for someone else. Here's what you need to know:

  • A recipe is different from sharing a live agent session
  • The recipe tells Goose how to build a copy of your agent
  • It includes things like:
    • Instructions for how the agent should behave
    • What activities the agent can do

When you use the Goose desktop app to share an agent, it shows you a window where you can review and customize these settings before creating the recipe. With the CLI, the /recipe command creates a .yaml file that you can edit to customize the shared Agent that you want to create.

Note: This is like sharing a cooking recipe with a friend - you're not giving them your actual meal, but the instructions to make the same thing themselves!

In your terminal with a Goose session running, input the following:

( O)> /recipe

Goose generates recipe.yaml and saves it for you as shown in the following output:

Generating Recipe
Saved recipe to .../my-shared-project/goose/recipe.yaml

Recipe.yaml specification​

The .yaml file contains an editable set of fields that let you customize the shared Agent that gets created.

---
# Required fields
version: 1.0.0
title: $title
description: $description

instructions: $instructions # instructions to be added to the system prompt

# Optional fields
prompt: $prompt             # if set, the initial prompt for the run/session

extensions:
- $extensions
context:
- $context
activities:
- $activities
author:
contact: $contact
metadata: $metadata

You can edit the instructions and activities fields. Instructions can be edited to add context that isn't in the session that you are creating the shared Agent from. You can also add additional activites such as "Please ask users for their zipcode so you can provide their local weather forecast."

Send the file to the Goose CLI user that wants to start a shared Agent. For more information about the recipe prompt completion command, see the recipe CLI prompt.

Start the shared Agent​

When another Goose CLI user sends you a recipe file, save it in the directory where you want to start your shared Agent. From your terminal, navigate to the directory where you saved the file, and run:

goose run --<RECIPE_FILE_NAME>

The Goose CLI loads the recipe and creates a session with all of the components shared in the original session. For infomration about the Goose run command, see the run CLI command.

Accessing conversation history in shared sessions​

When you join a shared session, you automatically get access to:

  • The full conversation history (chat messages) from when the session started
  • All tool outputs and results
  • Any files or content created during the session

How It Works​

When you click the shared link, you'll join the active session. The conversation history will automatically load in your Goose window. You'll see all messages and interactions in real-time and can scroll up to view earlier parts of the conversation.

Important Notes​

The history is synchronized live - you'll see new messages as they happen. You don't need to take any special steps to access the history. The conversation remains available as long as the session is active. Once the host ends the session, the shared access ends.

Troubleshooting​

If you're having trouble accessing the conversation history when joining a shared session, you might want to:

  • Make sure you're using the most recent version of Goose
  • Try refreshing your session
  • Check with the host to ensure the session is still active

Remember that the shared session ends when the host closes it, so make sure to save any important information you need before the session ends.

Tool outputs in a shared session​

In a shared session, participants can see:

  • All conversation messages
  • Tool outputs and results
  • Files or content created during the session
  • Active extensions and their configurations

How tool outputs work in shared sessions​

When any participant uses a tool, all members can see:

  • The tool being called
  • The parameters used
  • The results/output of the tool

These outputs appear in the conversation just like messages and they're synchronized in real-time for all participants.

Important Notes​

  • Tool outputs are treated as part of the conversation history
  • All participants can see the results, even if they didn't initiate the tool use
  • The outputs remain visible as long as the session is active
  • Like other shared content, tool outputs are only available during the active session

This means that when you're in a shared session, you have full visibility into all tool interactions and their results, making it effective for collaborative troubleshooting or working together on tasks that require tool use.

File access in shared sessions​

Files created during a session are meant to be accessible to all participants. However, a file that is created in one shared Agent instance is not created in parallel on the other instances. To give everyone access to the file, we suggest any of the following strategies:

  • Ask the Host: When a collaborator creates a file, ask them to:

    1. Share the file's location or path
    2. Confirm how they intend to share access to the file

  • Use Shared Tools: When files need to be shared:

    1. Use collaborative tools like Google Drive (if the extension is available)
    2. Share file contents directly in the conversation where possible
    3. Consider using version control systems for code files

  • Document Important Files:

    1. Keep track of important files created during the session
    2. Save or copy relevant content before the session ends

What gets shared?​

You might start a project in a Goose session and realize your teammate needs access to that context through a shared agent. But at the same time, you may have shared things with Goose that you’d rather keep private.

Shared components​

The shared agent includes these components:

  • Conversation history (all messages)
  • Tool outputs and results
  • Files or content created during the session
  • Active extensions and their configurations
  • Project context (when working within a project)

Private components​

The following components are not included in a shared agent:

  • Global memories (stored in ~/.config/goose/memory)
  • Local memories (stored in .goose/memory)
  • Personal API keys or credentials
  • System-level configurations

Common use cases​

There are many reasons why you might want to create a shared agent. The following shared agent use cases are just a starting point.

Team Collaboration​

  • Working together on coding projects
  • Troubleshooting technical issues
  • Brainstorming sessions
  • Training & Onboarding

Teaching new team members​

  • Demonstrating workflows
  • Sharing best practices
  • Pair Programming

Real-time code collaboration​

  • Code reviews
  • Debugging sessions