aljaz/goose
1
0
Fork 0
mirror of https://github.com/aljazceru/goose.git synced 2025-12-17 22:24:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat: V1.0 (#734)

Browse Source 
Co-authored-by: Michael Neale <michael.neale@gmail.com>
Co-authored-by: Wendy Tang <wendytang@squareup.com>
Co-authored-by: Jarrod Sibbison <72240382+jsibbison-square@users.noreply.github.com>
Co-authored-by: Alex Hancock <alex.hancock@example.com>
Co-authored-by: Alex Hancock <alexhancock@block.xyz>
Co-authored-by: Lifei Zhou <lifei@squareup.com>
Co-authored-by: Wes <141185334+wesrblock@users.noreply.github.com>
Co-authored-by: Max Novich <maksymstepanenko1990@gmail.com>
Co-authored-by: Zaki Ali <zaki@squareup.com>
Co-authored-by: Salman Mohammed <smohammed@squareup.com>
Co-authored-by: Kalvin C <kalvinnchau@users.noreply.github.com>
Co-authored-by: Alec Thomas <alec@swapoff.org>
Co-authored-by: lily-de <119957291+lily-de@users.noreply.github.com>
Co-authored-by: kalvinnchau <kalvin@block.xyz>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Rizel Scarlett <rizel@squareup.com>
Co-authored-by: bwrage <bwrage@squareup.com>
Co-authored-by: Kalvin Chau <kalvin@squareup.com>
Co-authored-by: Alice Hau <110418948+ahau-square@users.noreply.github.com>
Co-authored-by: Alistair Gray <ajgray@stripe.com>
Co-authored-by: Nahiyan Khan <nahiyan.khan@gmail.com>
Co-authored-by: Alex Hancock <alexhancock@squareup.com>
Co-authored-by: Nahiyan Khan <nahiyan@squareup.com>
Co-authored-by: marcelle <1852848+laanak08@users.noreply.github.com>
Co-authored-by: Yingjie He <yingjiehe@block.xyz>
Co-authored-by: Yingjie He <yingjiehe@squareup.com>
Co-authored-by: Lily Delalande <ldelalande@block.xyz>
Co-authored-by: Adewale Abati <acekyd01@gmail.com>
Co-authored-by: Ebony Louis <ebony774@gmail.com>
Co-authored-by: Angie Jones <jones.angie@gmail.com>
Co-authored-by: Ebony Louis <55366651+EbonyLouis@users.noreply.github.com>
This commit is contained in:
Bradley Axen
2025-01-24 13:04:43 -08:00
committed by GitHub
parent eccb1b2261
commit 1c9a7c0b05
688 changed files with 71147 additions and 19132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
documentation/docs/guides/_category_.json Normal file
View File

@@ -0,0 +1,8 @@
{
"label": "Guides",
"position": 4,
"link": {
"type": "generated-index",
"description": "Learn essential tips and recommendations for using Goose"
}
}

24
documentation/docs/guides/file-management.md Normal file
View File

@@ -0,0 +1,24 @@
---
sidebar_position: 5
---
# File Management
As an autonomous agent, Goose is designed to carry out tasks following specified instructions. This may sometimes involve working with local files. It's essential to follow best practices for safe file modification to monitor changes and revert any where necessary.
Here are a few tips to help you manage file operations effectively while maintaining the integrity and safety of your codebase.
### Version Control
Always use a version control system like Git to track changes to your codebase. This prevents accidental overwriting and allows you to revert back to previous states easily. Ensure you commit changes before running Goose on your codebase. Use branches to separate experimental changes from the main codebase.
### Validation and Testing
Implement validation and testing steps before and after Goose modifies any files. Run your unit tests to verify changes made by Goose. Use a staging environment to ensure changes integrate well with the entire system.
### Change Review
Manually review or use automated code reviews to ensure the quality of generated code or changes. Integrate tools such as diff tools to visualize changes made by Goose. Implement a review process with team members or CI/CD pipelines.
### Codebase Organization
Structure your codebase into well-defined modules or subdirectories to manage them efficiently. Use a modular approach to isolate parts of the code Goose needs to access. You can also provide specific directories or file paths you want Goose to work on.

106
documentation/docs/guides/goose-cli-commands.md Normal file
View File

@@ -0,0 +1,106 @@
---
sidebar_position: 2
---
# CLI Commands
Goose provides a command-line interface (CLI) with several commands for managing sessions, configurations and extensions. Below is a list of the available commands and their descriptions:
## Commands
### help
Used to display the help menu
**Usage:**
```bash
goose --help
```
### version
Used to check the current Goose version you have installed
**Usage:**
```bash
goose --version
```
### agents
Used to list all available agents
**Usage:**
```bash
goose agents
```
### mcp
Run an enabled MCP server specified by `<name>` (e.g. 'Google Drive')
**Usage:**
```bash
goose mcp <name>
```
### session [options]
Start or resume sessions with the following options.
**Options:**
- **`-n, --name <NAME>`**
Name for the new chat session (e.g. `'project-x'`)
```bash
goose session --name <name>
```
- **`-r, --resume`**
Resume a previous session (last used or specified by `--name`)
```bash
goose session --name <name> --resume
```
- **`--with-extension <COMMAND>`**
Starts the session with the specified extension. Can also include environment variables (e.g., `'GITHUB_TOKEN=xyz npx -y @modelcontextprotocol/server-github'`).
```bash
goose session --name <name> --with-extension <command>
```
- **`--with-builtin <NAME>`**
Starts the session with the specified [built-in extension](../configuration/managing-extensions.md#built-in-extensions) enabled. (e.g. 'developer')
```bash
goose session --with-builtin <name>
```
### run [options]
Execute commands from an instruction file or stdin
- **`-i, --instructions <FILE>`**: Path to instruction file containing commands
- **`-t, --text <TEXT>`**: Input text to provide to Goose directly
- **`-n, --name <NAME>`**: Name for this run session (e.g., 'daily-tasks')
- **`-r, --resume`**: Resume from a previous run
**Usage:**
```bash
goose run --instructions plan.md
```
### configure [options]
Configure Goose settings - providers, extensions, etc.
**Usage:**
```bash
goose configure'
```

44
documentation/docs/guides/handling-llm-rate-limits-with-goose.md Normal file
View File

@@ -0,0 +1,44 @@
---
title: LLM Rate Limits
sidebar_position: 4
---
# Handling LLM Rate Limits
Rate limiting is the process of restricting the number of requests a user or application can send to an LLM API within a specific timeframe. LLM providers enforce this with the purpose of managing resources and preventing abuse.
Since Goose is working very quickly to implement your tasks, you may need to manage rate limits imposed by the provider. If you frequently hit rate limits, consider upgrading your LLM plan to access higher tier limits or using OpenRouter.
## Using OpenRouter
OpenRouter provides a unified interface for LLMs that allows you to select and switch between different providers automatically - all under a single billing plan. With OpenRouter, you can utilize free models or purchase credits for paid models.
1. Go to [openrouter.ai](https://openrouter.ai) and create an account.
2. Once verified, create your [API key](https://openrouter.ai/settings/keys).
<!-- 3. Add your API key and OpenRouter configuration to your environment variables: -->
<Tabs groupId="interface">
<TabItem value="cli" label="Goose CLI" default>
1. Run the Goose configuration command:
```sh
goose configure
```
2. Select `Configure Providers` from the menu.
3. Follow the prompts to choose OpenRouter as your provider and enter your OpenRouter API key when prompted.
</TabItem>
<TabItem value="ui" label="Goose UI">
1. Click on the three dots in the top-right corner.
2. Select `Settings` from the menu.
3. Click on "Browse" in the `Models` section.
4. Click on `Configure`
5. Select `OpenRouter` from the list of available providers.
6. Enter your OpenRouter API key in the dialog that appears.
</TabItem>
</Tabs>
Now Goose will send your requests through OpenRouter which will automatically switch models when necessary to avoid interruptions due to rate limiting.

100
documentation/docs/guides/managing-goose-sessions.md Normal file
View File

@@ -0,0 +1,100 @@
---
sidebar_position: 1
title: Managing Sessions
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Managing Goose Sessions
A session is a single, continuous interaction between you and Goose, providing a space to ask questions and prompt action. In this guide, we'll cover how to start, exit, save, and resume.
## Starting a Session
<Tabs>
<TabItem value="cli" label="Goose CLI" default>
From your terminal, navigate to the directory from which you'd like to start, and run:
```sh
goose session
```
</TabItem>
<TabItem value="ui" label="Goose UI">
After choosing an LLM provider, you’ll see the session interface ready for use.
Type your questions, tasks, or instructions directly into the input field, and Goose will immediately get to work.
</TabItem>
</Tabs>
## Naming a Session
<Tabs>
<TabItem value="cli" label="Goose CLI" default>
By default, Goose will provide a random string as the name of your session. If you'd like to provide a specific name, this is where you'd do so. For example to name your session `react-migration`, you would run:
```
goose session -n react-migration
```
You'll know your session has started when your terminal looks similar to the following:
```
starting session | provider: openai model: gpt-4o
logging to ~/.config/goose/sessions/react-migration.json1
```
</TabItem>
<TabItem value="ui" label="Goose UI">
Session management features, such as **naming** and **resuming** sessions, are **not** currently available in the Goose UI. If you'd like to see these features added, please [open an issue on GitHub](https://github.com/block/goose/issues/new?template=Blank+issue) to let us know.
</TabItem>
</Tabs>
:::info
If this is your first session, Goose will prompt you for an API key to access an LLM (Large Language Model) of your choice. For more information on setting up your API key, see the [Installation Guide](/docs/installation#set-up-a-provider). Here is the list of [supported LLMs](/docs/configuration/providers).
:::
## Exiting a Session
<Tabs>
<TabItem value="cli" label="Goose CLI" default>
To save and exit a session, hold down `Ctrl` + `C`. Alternatively, you can type `exit` to save and exit the session.
Your session will be stored locally in `~/.config/goose/sessions`.
</TabItem>
<TabItem value="ui" label="Goose UI">
To exit a session, simply close the application.
</TabItem>
</Tabs>
## Resuming a Session
<Tabs>
<TabItem value="cli" label="Goose CLI" default>
To resume your latest session, you can run the following command:
```
goose session -r
```
To resume a specific session, you can first check the sessions you currently have by running:
```
goose session --list
```
This command will display a list of all saved sessions, showing a name, date, and time for each session. The output should look similar to the following:
```
2024-11-12 14:12:28 managing-goose
2024-11-12. 13:48:11 blog
2024-11-12 13:27:21 react-migration
2024-11-04 16:14:29 e6d7
```
To resume a specific session, run the following command:
```
goose session -r -n react-migration
```
</TabItem>
<TabItem value="ui" label="Goose UI">
Session management features, such as **naming** and **resuming** sessions, are **not** currently available in the Goose UI. If you'd like to see these features added, please [open an issue on GitHub](https://github.com/block/goose/issues/new?template=Blank+issue) to let us know.
</TabItem>
</Tabs>

50
documentation/docs/guides/tips.md Normal file
View File

@@ -0,0 +1,50 @@
---
title: Quick Tips
---
Here is a collection of tips for working with Goose:
### Goose can and will edit files
Use a git strategy to avoid losing anything - such as staging your personal edits and leaving Goose edits unstaged until reviewed. Consider using individual commits which can be reverted. See more on [File Management](/docs/guides/file-management).
### Goose can and will run commands
Goose will check commands for satefy, however, you can also ask Goose to check with you before running commands if you are concerned.
### You can interrupt Goose with `CTRL+C`
Use this command to stop Goose in the event that you need to correct it or give it more info.
### Goose works best when solving concrete problems
Experiment with how far you need to break a problem down to get Goose to solve it. Be specific! For example, it will likely fail to "create a banking app", but probably does a good job if prompted with "create a Fastapi app with an endpoint for deposit and withdrawal and with account balances stored in mysql keyed by id".
### Goose can troubleshoot
If something goes wrong, Goose can help troubleshoot issues by examining logs, analyzing error messages, and suggesting possible resolutions.
### Leverage Goose to learn
Use Goose to learn new technologies or frameworks by asking it to explain things like code snippets, concepts, or best practices relevant to your project.
### Goose needs context
If Goose doesn't have enough context to start with, it might go in the wrong direction. Tell it to read files that you are referring to or search for objects in code. Even better, ask it to summarize them for you, which will help it set up its own next steps. You can create a [goosehints](/docs/guides/using-goosehints) file to help with this.
### Use easy search terms
Refer to any objects in files with something that is easy for Goose to search for, such as "the MyExample class".
### Teach Goose how you test
Goose *loves* to know how to run tests to get a feedback loop going, just like you do. If you tell it how you test things locally and quickly, it can make use of that when working on your project.
### Goose can do scripting tasks
You can use Goose for tasks that would require scripting. It can even look at your screen and correct designs, or help you fix bugs. Try asking it to help you in a way you would ask a person.
### Goose will make mistakes
Sometimes Goose will go in the wrong direction. Feel free to correct it, or start over again.
### Goose can run tasks continuously if asked
You can tell Goose to run things for you continuously and it will iterate, try, and retry.
### Goose can run anywhere
It doesn't have to be in a repo. Just ask Goose!
### Keep Goose updated
Regularly update Goose to benefit from the latest features, bug fixes, and performance improvements. For the CLI, the best way to keep it updated is by re-running the [Goose installation script][installation]. For Goose UI, check the [GitHub Releases page][ui-release] regularly for updates.
[installation]: https://block.github.io/goose/v1/docs/quickstart/#installation
[ui-release]: https://github.com/block/goose/releases/stable

66
documentation/docs/guides/using-goosehints.md Normal file
View File

@@ -0,0 +1,66 @@
---
title: Using Goosehints
sidebar_position: 3
---
# Providing Hints to Goose
`.goosehints` is a text file used to provide additional context about your project and improve the communication with Goose. The use of `goosehints` ensures that Goose understands your requirements better and can execute tasks more effectively.
:::info Developer extension required
To make use of the hints file, you need to have the `developer` extension [enabled](../configuration/managing-extensions).
:::
This guide will walk you through creating and using your `.goosehints` file to streamline your workflow with custom instructions and context.
## Creating your `.goosehints` file
Create a file named `.goosehints` and save the file in `~/.config/goose/.goosehints`. If saved here, Goose will use this file for every session with you.
:::tip
You can also save `.goosehints` local to any directory. In this case, Goose will utilize the hints when working in that directory.
:::
The `.goosehints` file can include any instructions or contextual details relevant to your projects.
A good time to consider adding a `.goosehints` file is when you find yourself repeating prompts, or providing the same kind of instructions multiple times. It's also a great way to provide a lot of context which might be better suited in a file.
## Setting up hints
The `.goosehints` file supports natural language and also follows [jinja templating rules][jinja-guide], so you can leverage templating to insert file contents or variables.
Here are some ways people have used hints to provide additional context to Goose:
- **Decision-Making**: Specify if Goose should autonomously make changes or confirm actions with you first.
- **Validation Routines**: Provide test cases or validation methods that Goose should perform to ensure changes meet project specifications.
- **Feedback Loop**: Include steps that allow Goose to receive feedback and iteratively improve its suggestions.
- **Point to more detailed documentation**: Indicate important files like `README.md`, `CONTRIBUTING.md`, or others that Goose should consult for detailed explanations.
Like prompts, this is not an extensive list to shape your `.goosehints` file. You can include as much context as you need.
Example `.goosehints` file:
```jinja
This is a simple example JavaScript web application that uses the Express.js framework. View [Express documentation](https://expressjs.com/) for extended guidance.
Go through the README.md for information on how to build and test it as needed.
Make sure to confirm all changes with me before applying.
Use the following custom values when needed:
{%include custom-config.js%}
Run tests with `npm run test` ideally after each change.
```
## Best practices
- **Keep file updated**: Regularly update the `.goosehints` file to reflect any changes in project protocols or priorities.
- **Be concise**: Make sure the content is straightforward and to the point, ensuring Goose can quickly parse and act on the information.
[jinja-guide]: https://jinja.palletsprojects.com/en/stable/