goose/docs/docs/toolkits.md

Toolkits

This page contains information about building and using toolkits in Goose. Toolkits are a way to extend Goose's capabilities by adding new tools and functionalities. You can create your own toolkits or use the existing ones provided by Goose.

Using Toolkits

Use goose toolkit list to list the available toolkits.

Toolkits defined in Goose

Using Goose with toolkits is simple. You can add toolkits to your profile in the profiles.yaml file. Here's an example of how to add my-toolkit toolkit to your profile:

my-profile:
  provider: openai
  processor: gpt-4o
  accelerator: gpt-4o-mini
  moderator: passive
  toolkits:
    - my-toolkit

Then run Goose with the specified profile:

goose session start --profile my-profile

Toolkits defined in Goose Plugins

1. First make sure that goose-plugins is intalled with Goose:

pipx install goose-ai --preinstall goose-plugins

2. Update the profiles.yaml file to include the desired toolkit:

my-profile:
  provider: openai
  processor: gpt-4o
  accelerator: gpt-4o-mini
  moderator: passive
  toolkits:
    - my-goose-plugins-toolkit

Building a Toolkit

To add a toolkit, in your code (which doesn't necessarily need to be in the Goose package thanks to plugin metadata!), create a class that derives from the Toolkit class.

Example toolkit class

Below is an example of a simple toolkit called Demo that derives from the Toolkit class. This toolkit provides an authenticate tool that outputs an authentication code for a user. It also provides system instructions for the model.

import os
import platform

from goose.toolkit.base import Toolkit, tool


class Demo(Toolkit):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    # Provide any additional tools as needed!
    # The docstring of the tool provides instructions to the LLM, so they are important to tune
    # you do not have to provide any tools, but any function decorated with @tool will be available
    @tool
    def authenticate(self, user: str):
        """Output an authentication code for this user

        Args:
            user (str): The username to authenticate for
        """
        # notifier supports any rich renderable https://rich.readthedocs.io/en/stable/introduction.html#quick-start
        self.notifier.log(f"[bold red]auth: {str(hash(user))}[/]")

    # Provide any system instructions for the model
    # This can be generated dynamically, and is run at startup time
    def system(self) -> str:
        print("new")
        return f"""**You must preceed your first message by using the authenticate tool for the current user**

        ```
        platform: {platform.system()}
        cwd: {os.getcwd()}
        user: {os.environ.get('USER')}
        ```
        """

Exposing the new toolkit to Goose

To make the toolkit available, add it to the pyproject.toml file and then update your profiles.yaml file.

Update the pyproject.toml file

If you're adding the new toolkit to Goose or the Goose Plugins repo, simply find the [project.entry-points."goose.toolkit"] section in pyproject.toml and add a line like this:

[project.entry-points."goose.toolkit"]
developer = "goose.toolkit.developer:Developer"
github = "goose.toolkit.github:Github"
# Add a line like this - the key becomes the name used in profiles
demo = "goose.toolkit.demo:Demo"

If you are adding the toolkit to a different package, see the docs for goose-plugins for more information on how to create a plugins repository that can be used by Goose.

Update the profiles.yaml file

And then to set up a profile that uses it, add something to ~/.config/goose/profiles.yaml

default:
  provider: openai
  processor: gpt-4o
  accelerator: gpt-4o-mini
  moderator: passive
  toolkits:
    - name: developer
      requires: {}
demo:
  provider: openai
  processor: gpt-4o
  accelerator: gpt-4o-mini
  moderator: passive
  toolkits:
    - developer
    - demo

And now you can run goose with this new profile to use the new toolkit!

goose session start --profile demo

Note

If you're using a plugin from goose-plugins, make sure goose-plugins is installed in your environment. You can install it via pip:

pipx install goose-ai --preinstall goose-plugins

Available Toolkits in Goose

To see the available toolkits to you, run goose toolkit list, this will show the toolkits defined below as well as any other Goose modules you have installed (for example, goose-plugins).

Goose provides a variety of toolkits designed to help developers with different tasks. Here's an overview of each available toolkit and its functionalities:

1. Developer Toolkit

The Developer toolkit offers general-purpose development capabilities, including:

• System Configuration Details: Retrieves system configuration details.
• Task Management: Update the plan by overwriting all current tasks.
• File Operations:
  • patch_file: Patch a file by replacing specific content.
  • read_file: Read the content of a specified file.
  • write_file: Write content to a specified file.
• Shell Command Execution: Execute shell commands with safety checks.

2. GitHub Toolkit

The GitHub toolkit provides detailed configuration and procedural guidelines for GitHub operations.

3. Lint Toolkit

The Lint toolkit ensures that all toolkits have proper documentation. It performs the following checks:

• Toolkit must have a docstring.
• The first line of the docstring should contain more than 5 words and fewer than 12 words.
• The first letter of the docstring should be capitalized.

4. RepoContext Toolkit

The RepoContext toolkit provides context about the current repository. It includes:

• Repository Size: Get the size of the repository.
• Monorepo Check: Determine if the repository is a monorepo.
• Project Summarization: Summarize the current project based on the repository or the current project directory.

5. Screen Toolkit

The Screen toolkit assists users in taking screenshots for debugging or designing purposes. It provides:

• Take Screenshot: Capture a screenshot and provide the path to the screenshot file.
• System Instructions: Instructions on how to work with screenshots.

6. SummarizeRepo Toolkit

The SummarizeRepo toolkit helps in summarizing a repository. It includes:

• Summarize Repository: Clone the repository (if not already cloned) and summarize the files based on specified extensions.

7. SummarizeProject Toolkit

The SummarizeProject toolkit generates or retrieves a summary of a project directory based on specified file extensions. It includes:

• Get Project Summary: Generate or retrieve a summary of the project in the specified directory.

8. SummarizeFile Toolkit

The SummarizeFile toolkit helps in summarizing a specific file. It includes:

• Summarize File: Summarize the contents of a specified file with optional instructions.