mirror of
https://github.com/aljazceru/goose.git
synced 2026-02-20 14:04:32 +01:00
chore: update readme! (#96)
This commit is contained in:
lily-de
@@ -1,3 +1,3 @@
|
||||
This is a python CLI app that uses UV. Read CONTRIBUTING.md for information on how to build and test it as needed.
|
||||
Some key concepts are that it is run as a command line interface, dependes on the "ai-exchange" package, and has the concept of toolkits which are ways that its behavior can be extended. Look in src/goose and tests.
|
||||
Once the user has UV installed it should be able to be used effectively along with uvx to run tasks as needed
|
||||
Once the user has UV installed it should be able to be used effectively along with uvx to run tasks as needed
|
||||
|
||||
310
README.md
310
README.md
@@ -1,247 +1,187 @@
|
||||
<h1 align="center">
|
||||
goose
|
||||
Goose is your on-machine developer agent, automating engineering tasks seamlessly within your IDE or terminal
|
||||
</h1>
|
||||
|
||||
<p align="center"><strong>goose</strong> <em>is a programming agent that runs on your machine.</em></p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg"></a>
|
||||
<a href="https://square.github.io/goose/"><img src="https://img.shields.io/badge/goose_documentation-blue"></a>
|
||||
<img src="docs/assets/goose.png" width="400" height="400" alt="Goose Drawing"/>
|
||||
</p>
|
||||
<p align="center">
|
||||
Generated by Goose from its <a href="https://github.com/square/goose-plugins/blob/main/src/goose_plugins/toolkits/artify.py">VincentVanCode toolkit</a>.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="#usage">Usage</a> •
|
||||
<a href="#configuration">Configuration</a> •
|
||||
<a href="#tips">Tips</a> •
|
||||
<a href="#faq">FAQ</a> •
|
||||
<a href="#open-source">Open Source</a>
|
||||
<a href="https://square.github.io/goose/"><img src="https://img.shields.io/badge/Documentation-goose_docs-blue"></a>
|
||||
<a href=[goose-ai-pypi]><img src="https://img.shields.io/pypi/v/goose-ai"></a>
|
||||
<a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg">
|
||||
</a>
|
||||
<a href=https://discord.gg/7GaTvbDwga><img src="https://dcbadge.limes.pink/api/server/https://discord.gg/7GaTvbDwga?style=flatlabel=test"></a>
|
||||
</p>
|
||||
|
||||
`goose` assists in solving a wide range of programming and operational tasks. It is a live virtual developer you can interact with, guide, and learn from.
|
||||
|
||||
To solve problems, `goose` breaks down instructions into sequences of tasks and carries them out using tools. Its ability to connect its changes with real outcomes (e.g. errors) and course correct is its most powerful and exciting feature. `goose` is free open source software and is built to be extensible and customizable.
|
||||
|
||||
|
||||
<p align="center">
|
||||
<a href="#unique-features-of-goose-compared-to-other-ai-assistants">Unique features</a> 🤖 •
|
||||
<a href="#what-block-employees-have-to-say-about-goose"> Block Employees on Goose</a> <img src=docs/assets/logo.png height="15", width="15" alt="Block Emoji"/> •
|
||||
<a href="#quick-start-guide">Quick start guide</a> 🚀 •
|
||||
<a href="#getting-involved!">Getting involved!</a> 👋
|
||||
|
||||
> [!TIP]
|
||||
> **Quick install:**
|
||||
> ```
|
||||
> pipx install goose-ai
|
||||
> ```
|
||||
|
||||
**Goose** is a developer agent that supercharges your software development by automating an array of coding tasks directly within your terminal or IDE. Guided by you, it can intelligently assess your project's needs, generate the required code or modifications, and implement these changes on its own. Goose can **interact with a multitude of tools via external APIs** such as Jira, GitHub, Slack, infrastructure and data pipelines, and more -- if your task uses a **shell command or can be carried out by a Python script, Goose can do it for you too!** Like semi-autonomous driving, Goose handles the heavy lifting, allowing you to focus on other priorities. Simply set it on a task and return later to find it completed, boosting your productivity with less manual effort.
|
||||
|
||||
<p align="center">
|
||||
<video src="https://github.com/user-attachments/assets/63ee7910-cb02-45c0-9982-351cbce83925" width="700" height="700" />
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
## Usage
|
||||
## Unique Features of Goose Compared to Other AI Assistants
|
||||
|
||||
- **Autonomy**: A copilot should be able to also fly the plane at times, which in the development world means running code, debugging tests, installing dependencies, not just providing text output and autocomplete or search. Goose moves beyond just generating code snippets by (1) **using the shell** and (2) by seeing what happens with the code it writes and starting a feedback loop to solve harder problems, **refining solutions iteratively like a human developer**. Your code's best wingman.
|
||||
|
||||
- **Extensibility**: Open-source and fully customizable, Goose integrates with your workflow and allows you to extend it for even more control. **Toolkits let you add new capabilities to Goose.** They are anything you can implement as a Python function (e.g. API requests, deployments, search, etc). We have a growing library of toolkits to use, but more importantly you can create your own. This gives Goose the ability to run these commands and decide if and when a tool is needed to complete your request! **Creating your own toolkits give you a way to bring your own private context into Goose's capabilities.** And you can use *any* LLM you want under the hood, as long as it supports tool use.
|
||||
|
||||
## What Block employees have to say about Goose
|
||||
|
||||
> With Goose, I feel like I am Maverick.
|
||||
>
|
||||
> Thanks a ton for creating this. 🙏
|
||||
> I have been having way too much fun with it today.
|
||||
|
||||
-- P, Machine Learning Engineer
|
||||
|
||||
|
||||
> I wanted to construct some fake data for an API with a large request body and business rules I haven't memorized. So I told Goose which object to update and a test to run that calls the vendor. Got it to use the errors descriptions from the vendor response to keep correcting the request until it was successful. So good!
|
||||
|
||||
-- J, Software Engineer
|
||||
|
||||
|
||||
> I asked Goose to write up a few Google Scripts that mimic Clockwise's functionality (particularly, creating blocks on my work calendar based on events in my personal calendar, as well as color-coding calendar entries based on type and importance). Took me under an hour. If you haven't tried Goose yet, I highly encourage you to do so!
|
||||
|
||||
-- M, Software Engineer
|
||||
|
||||
|
||||
> If anyone was looking for another reason to check it out: I just asked Goose to break a string-array into individual string resources across eleven localizations, and it performed amazingly well and saved me a bunch of time doing it manually or figuring out some way to semi-automate it.
|
||||
|
||||
-- A, Android Engineer
|
||||
|
||||
|
||||
> Hi team, thank you for much for making Goose, it's so amazing. Our team is working on migrating Dashboard components to React components. I am working with Goose to help the migration.
|
||||
|
||||
-- K, Software Engineer
|
||||
|
||||
|
||||
> Got Goose to update a dependency, run tests, make a branch and a commit... it was 🤌. Not that complicated but I was impressed it figured out how to run tests from the README.
|
||||
|
||||
-- J, Software Engineer
|
||||
|
||||
|
||||
> Wanted to document what I had Goose do -- took about 30 minutes end to end! I created a custom CLI command in the `gh CLI` library to download in-line comments on PRs about code changes (currently they aren't directly viewable). I don't know Go *that well* and I definitely didn't know where to start looking in the code base or how to even test the new command was working and Goose did it all for me 😁
|
||||
|
||||
-- L, Software Engineer
|
||||
|
||||
|
||||
> Hi Team, just wanted to share my experience of using Goose as a non-engineer! ... I just asked Goose to ensure that my environment is up to date and copied over a guide into my prompt. Goose managed everything flawlessly, keeping me informed at every step... I was truly impressed with how well it works and how easy it was to get started! 😍
|
||||
|
||||
-- M, Product Manager
|
||||
|
||||
**See more of our use-cases in our [docs][use-cases]!**
|
||||
|
||||
## Quick start guide
|
||||
|
||||
### Installation
|
||||
|
||||
To install `goose`, we recommend `pipx`
|
||||
|
||||
First make sure you've [installed pipx][pipx] - for example
|
||||
To install Goose, use `pipx`. First ensure [pipx][pipx] is installed:
|
||||
|
||||
``` sh
|
||||
brew install pipx
|
||||
pipx ensurepath
|
||||
```
|
||||
|
||||
Then you can install `goose` with
|
||||
Then install Goose:
|
||||
|
||||
```sh
|
||||
pipx install goose-ai
|
||||
```
|
||||
#### IDEs
|
||||
There is an early version of a VS Code extension with goose support you can try here: https://github.com/square/goose-vscode - more to come soon.
|
||||
|
||||
### LLM provider access setup
|
||||
`goose` works on top of LLMs (you need to bring your own LLM). By default, `goose` uses `openai` as LLM provider. You need to set OPENAI_API_KEY as an environment variable if you would like to use `openai`.
|
||||
```sh
|
||||
export OPENAI_API_KEY=your_open_api_key
|
||||
```
|
||||
### Running Goose
|
||||
|
||||
Otherwise, please refer <a href="#configuration">Configuration</a> to customise `goose`
|
||||
#### Start a session
|
||||
|
||||
### Start `goose` session
|
||||
From your terminal, navigate to the directory you'd like to start from and run:
|
||||
|
||||
```sh
|
||||
goose session start
|
||||
```
|
||||
|
||||
You will see a prompt `G❯`:
|
||||
You will see the Goose prompt `G❯`:
|
||||
|
||||
```
|
||||
G❯ type your instructions here exactly as you would tell a developer.
|
||||
```
|
||||
Now you are interact with `goose` in conversational sessions - something like a natural language driven code interpreter.
|
||||
The default toolkit lets it take actions through shell commands and file edits.
|
||||
You can interrupt `goose` at any time to help redirect its efforts.
|
||||
|
||||
### Exit `goose` session
|
||||
If you are looking to exit, use `CTRL+D`, although `goose` should help you figure that out if you forget. See below for some examples.
|
||||
Now you are interacting with Goose in conversational sessions - something like a natural language driven code interpreter. The default toolkit allows Goose to take actions through shell commands and file edits. You can interrupt Goose with `CTRL+D` or `ESC+Enter` at any time to help redirect its efforts.
|
||||
|
||||
#### Exit the session
|
||||
|
||||
If you are looking to exit, use `CTRL+D`, although Goose should help you figure that out if you forget.
|
||||
|
||||
#### Resume a session
|
||||
|
||||
### Resume `goose` session
|
||||
When you exit a session, it will save the history in `~/.config/goose/sessions` directory and you can resume it later on:
|
||||
|
||||
``` sh
|
||||
goose session resume
|
||||
```
|
||||
|
||||
## Configuration
|
||||
To see more documentation on the CLI commands currently available to Goose check out the documentation [here][cli]. If you’d like to develop your own CLI commands for Goose, check out the [Contributing document][contributing].
|
||||
|
||||
`goose` can detect what LLM and toolkits it can work with from the configuration file `~/.config/goose/profiles.yaml` automatically.
|
||||
### Next steps
|
||||
|
||||
### Configuration options
|
||||
Example:
|
||||
Learn how to modify your Goose profiles.yaml file to add and remove functionality (toolkits) and providing context to get the most out of Goose in our [Getting Started Guide][getting-started].
|
||||
|
||||
```yaml
|
||||
default:
|
||||
provider: openai
|
||||
processor: gpt-4o
|
||||
accelerator: gpt-4o-mini
|
||||
moderator: truncate
|
||||
toolkits:
|
||||
- name: developer
|
||||
requires: {}
|
||||
- name: screen
|
||||
requires: {}
|
||||
```
|
||||
**Want to move out of the terminal and into an IDE?**
|
||||
|
||||
You can edit this configuration file to use different LLMs and toolkits in `goose`. `goose can also be extended to support any LLM or combination of LLMs
|
||||
We have some experimental IDE integrations for VSCode and JetBrains IDEs:
|
||||
* https://github.com/square/goose-vscode
|
||||
* https://github.com/Kvadratni/goose-intellij
|
||||
|
||||
#### provider
|
||||
Provider of LLM. LLM providers that currently are supported by `goose` (more can be supported by plugins):
|
||||
## Getting involved!
|
||||
|
||||
| Provider | Required environment variable(s) to access provider |
|
||||
| :----- | :------------------------------ |
|
||||
| openai | `OPENAI_API_KEY` |
|
||||
| anthropic | `ANTHROPIC_API_KEY` |
|
||||
| databricks | `DATABRICKS_HOST` and `DATABRICKS_TOKEN` |
|
||||
| ollama * | `OLLAMA_HOST` and ollama running |
|
||||
|
||||
* ollama is for local LLMs, and is limited by the tool calling model you can choose and run on local hardware, considered experimental.
|
||||
|
||||
#### processor
|
||||
Model for complex, multi-step tasks such as writing code and executing commands. Example: `gpt-4o`. You should choose the model based the provider you configured.
|
||||
|
||||
#### accelerator
|
||||
Small model for fast, lightweight tasks. Example: `gpt-4o-mini`. You should choose the model based the provider you configured.
|
||||
|
||||
#### moderator
|
||||
Rules designed to control or manage the output of the model. Moderators that currently are supported by `goose`:
|
||||
|
||||
- `passive`: does not actively intervene in every response
|
||||
- `truncate`: truncates the first contexts when the contexts exceed the max token size
|
||||
|
||||
#### toolkits
|
||||
|
||||
`goose` can be extended with toolkits, and out of the box there are some available:
|
||||
|
||||
* `developer`: for general-purpose development capabilities, including plan management, shell execution, and file operations, with default shell strategies like using ripgrep.
|
||||
* `screen`: for letting goose take a look at your screen to help debug or work on designs (gives goose eyes)
|
||||
* `github`: for awareness and suggestions on how to use github
|
||||
* `repo_context`: for summarizing and understanding a repository you are working in.
|
||||
* `jira`: for working with JIRA (issues, backlogs, tasks, bugs etc)
|
||||
There is a lot to do! If you're interested in contributing, a great place to start is picking a `good-first-issue`-labelled ticket from our [issues list][gh-issues]. More details on how to develop Goose can be found in our [Contributing Guide][contributing]. We are a friendly, collaborative group and look forward to working together![^1]
|
||||
|
||||
|
||||
#### Configuring goose per repo
|
||||
Check out and contribute to more experimental features in [Goose Plugins][goose-plugins]!
|
||||
|
||||
If you are using the `developer` toolkit, `goose` adds the content from `.goosehints`
|
||||
file in working directory to the system prompt of the `developer` toolkit. The hints
|
||||
file is meant to provide additional context about your project. The context can be
|
||||
user-specific or at the project level in which case, you
|
||||
can commit it to git. `.goosehints` file is Jinja templated so you could have something
|
||||
like this:
|
||||
Let us know what you think in our [Discussions][discussions] or the [**`#goose`** channel on Discord][goose-channel].
|
||||
|
||||
```
|
||||
Here is an overview of how to contribute:
|
||||
{% include 'CONTRIBUTING.md' %}
|
||||
|
||||
The following justfile shows our common commands:
|
||||
{% include 'justfile' %}
|
||||
```
|
||||
[^1]: Yes, Goose is open source and always will be. Goose is released under the ASL2.0 license meaning you are free to use it however you like. See [LICENSE.md][license] for more details.
|
||||
|
||||
|
||||
|
||||
### Examples
|
||||
#### provider as `anthropic`
|
||||
|
||||
```yaml
|
||||
default:
|
||||
provider: anthropic
|
||||
processor: claude-3-5-sonnet-20240620
|
||||
accelerator: claude-3-5-sonnet-20240620
|
||||
...
|
||||
```
|
||||
#### provider as `databricks`
|
||||
```yaml
|
||||
default:
|
||||
provider: databricks
|
||||
processor: databricks-meta-llama-3-1-70b-instruct
|
||||
accelerator: databricks-meta-llama-3-1-70b-instruct
|
||||
moderator: passive
|
||||
toolkits:
|
||||
- name: developer
|
||||
requires: {}
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
Here are some collected tips we have for working efficiently 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. Or consider using individual commits which can be reverted.
|
||||
- **`goose` can and will run commands**. You can ask it to check with you first if you are concerned. It will check commands for safety as well.
|
||||
- You can interrupt `goose` with `CTRL+C` to correct it or give it more info.
|
||||
- `goose` works best when solving concrete problems - experiment with how far you need to break that problem
|
||||
down to get `goose` to solve it. Be specific! E.g. 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"`
|
||||
- If `goose` doesn't have enough context to start with, it might go down 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.
|
||||
- Refer to any objects in files with something that is easy to search for, such as `"the MyExample class"
|
||||
- `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
|
||||
- You can use `goose` for tasks that would require scripting at times, even looking at your screen and correcting designs/helping you fix bugs, try asking it to help you in a way you would ask a person.
|
||||
- `goose` will make mistakes, and go in the wrong direction from times, feel free to correct it, or start again.
|
||||
- You can tell `goose` to run things for you continuously (and it will iterate, try, retry) but you can also tell it to check with you before doing things (and then later on tell it to go off on its own and do its best to solve).
|
||||
- `goose` can run anywhere, doesn't have to be in a repo, just ask it!
|
||||
|
||||
|
||||
### Examples
|
||||
|
||||
Here are some examples that have been used:
|
||||
|
||||
```
|
||||
G❯ Looking at the in progress changes in this repo, help me finish off the feature. CONTRIBUTING.md shows how to run the tests.
|
||||
```
|
||||
|
||||
```
|
||||
G❯ In this golang project, I want you to add open telemetry to help me get started with it. Look in the moneymovements module, run the `just test` command to check things work.
|
||||
```
|
||||
|
||||
```
|
||||
G❯ This project uses an old version of jooq. Upgrade to the latest version, and ensure there are no incompatibilities by running all tests. Dependency versions are in gradle/libs.versions.toml and to run gradle, use the binary located in bin/gradle
|
||||
```
|
||||
|
||||
```
|
||||
G❯ This is a fresh checkout of a golang project. I do not have my golang environment set up. Set it up and run tests for this project, and ensure they pass. Use the zookeeper jar included in this repository rather than installing zookeeper via brew.
|
||||
```
|
||||
|
||||
```
|
||||
G❯ In this repo, I want you to look at how to add a new provider for azure.
|
||||
Some hints are in this github issue: https://github.com/square/exchange/issues
|
||||
/4 (you can use gh cli to access it).
|
||||
```
|
||||
|
||||
```
|
||||
G❯ I want you to help me increase the test coverage in src/java... use mvn test to run the unit tests to check it works.
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q:** Why did I get error message of "The model `gpt-4o` does not exist or you do not have access to it.` when I talked goose?
|
||||
|
||||
**A:** You can find out the LLM provider and models in the configuration file `~/.config/goose/profiles.yaml` here to check whether your LLM provider account has access to the models. For example, after you have made a successful payment of $5 or more (usage tier 1), you'll be able to access the GPT-4, GPT-4 Turbo, GPT-4o models via the OpenAI API. [How can I access GPT-4, GPT-4 Turbo, GPT-4o, and GPT-4o mini?](https://help.openai.com/en/articles/7102672-how-can-i-access-gpt-4-gpt-4-turbo-gpt-4o-and-gpt-4o-mini).
|
||||
|
||||
## Open Source
|
||||
|
||||
Yes, `goose` is open source and always will be. `goose` is released under the ASL2.0 license meaning you can use it however you like.
|
||||
See LICENSE.md for more details.
|
||||
|
||||
To run `goose` from source, please see `CONTRIBUTING.md` for instructions on how to set up your environment and you can then run `uv run `goose` session start`.
|
||||
|
||||
[goose-plugins]: https://github.com/block-open-source/goose-plugins
|
||||
|
||||
[pipx]: https://github.com/pypa/pipx?tab=readme-ov-file#install-pipx
|
||||
[contributing]: CONTRIBUTING.md
|
||||
[license]: LICENSE.md
|
||||
|
||||
[goose-docs]: https://block-open-source.github.io/goose/
|
||||
[toolkits]: https://block-open-source.github.io/goose/plugins/available-toolkits.html
|
||||
[configuration]: https://block-open-source.github.io/goose/configuration.html
|
||||
[cli]: https://block-open-source.github.io/goose/plugins/cli.html
|
||||
[providers]: https://block-open-source.github.io/goose/providers.html
|
||||
[use-cases]: https://block-open-source.github.io/goose/guidance/applications.html
|
||||
[getting-started]: https://block-open-source.github.io/goose/guidance/getting-started.html
|
||||
|
||||
[discord-invite]: https://discord.gg/7GaTvbDwga
|
||||
[gh-issues]: https://github.com/block-open-source/goose/issues
|
||||
[van-code]: https://github.com/block-open-source/goose-plugins/blob/de98cd6c29f8e7cd3b6ace26535f24ac57c9effa/src/goose_plugins/toolkits/artify.py
|
||||
[discussions]: https://github.com/block-open-source/goose/discussions
|
||||
[goose-channel]: https://discord.com/channels/1287729918100246654/1287729920319033345
|
||||
[goose-ai-pypi]: https://pypi.org/project/goose-ai/
|
||||
|
||||
|
||||
|
||||
BIN
docs/assets/goose-in-action.gif
Normal file
BIN
docs/assets/goose-in-action.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 9.2 MiB |
BIN
docs/assets/goose-in-action.mp4
Normal file
BIN
docs/assets/goose-in-action.mp4
Normal file
Binary file not shown.
BIN
docs/assets/goose.png
Normal file
BIN
docs/assets/goose.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.0 MiB |
Reference in New Issue
Block a user