Skip to content

Commit 5aa12ec

Browse files
lifeizhou-aplifeizhou-ap
authored
Modified the readme to be more friendly to new users (#16)
* modified README to be friendly to new users
1 parent 6ab1df0 commit 5aa12ec

File tree

1 file changed

+116
-98
lines changed

1 file changed

+116
-98
lines changed

‎README.md

+116-98
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,46 @@ goose
1010

1111
<p align="center">
1212
<a href="#usage">Usage</a> •
13-
<a href="#installation">Installation</a> •
14-
<a href="#tips">Tips</a>
13+
<a href="#configuration">Configuration</a> •
14+
<a href="#tips">Tips</a> •
15+
<a href="#faq">FAQ</a> •
16+
<a href="#open-source">Open Source</a>
1517
</p>
1618

1719
`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.
1820

19-
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.
21+
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.
22+
23+
![goose_demo](https://github.com/user-attachments/assets/0794eaba-97ab-40ef-af64-6fc7f68eb8e2)
24+
25+
2026

2127
## Usage
28+
### Installation
2229

23-
You interact with goose in conversational sessions - something like a natural language driven code interpreter.
24-
The default toolkit lets it take actions through shell commands and file edits.
25-
You can interrupt Goose at any time to help redirect its efforts.
30+
To install `goose`, we recommend `pipx`
31+
32+
First make sure you've [installed pipx][pipx] - for example
33+
34+
``` sh
35+
brew install pipx
36+
pipx ensurepath
37+
```
38+
39+
Then you can install `goose` with
40+
41+
```sh
42+
pipx install goose-ai
43+
```
44+
### LLM provider access setup
45+
`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`.
46+
```sh
47+
export OPENAI_API_KEY=your_open_api_key
48+
```
2649

50+
Otherwise, please refer <a href="#configuration">Configuration</a> to customise `goose`
51+
52+
### Start `goose` session
2753
From your terminal, navigate to the directory you'd like to start from and run:
2854
```sh
2955
goose session start
@@ -34,83 +60,118 @@ You will see a prompt `G❯`:
3460
```
3561
G❯ type your instructions here exactly as you would tell a developer.
3662
```
63+
Now you are interact with `goose` in conversational sessions - something like a natural language driven code interpreter.
64+
The default toolkit lets it take actions through shell commands and file edits.
65+
You can interrupt `goose` at any time to help redirect its efforts.
3766

38-
> [!NOTE]
39-
> From here you can talk directly with goose - send along your instructions. If you are looking to exit, use `CTRL+D`,
40-
> although goose should help you figure that out if you forget. See below for some examples.
67+
### Exit `goose` session
68+
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.
4169

4270

43-
When you exit a session, it will save the history and you can resume it later on:
71+
### Resume `goose` session
72+
When you exit a session, it will save the history in `~/.config/goose/sessions` directory and you can resume it later on:
4473

4574
``` sh
4675
goose session resume
4776
```
4877

49-
## Tips
78+
## Configuration
5079

51-
Here are some collected tips we have for working efficiently with Goose
80+
`goose` can detect what LLM and toolkits it can work with from the configuration file `~/.config/goose/profiles.yaml` automatically.
5281

53-
- **goose can and will edit files**. Use a git strategy to avoid losing anything - such as staging your
54-
personal edits and leaving goose edits unstaged until reviewed. Or consider using indivdual commits which can be reverted.
55-
- **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.
56-
- You can interrupt goose with `CTRL+C` to correct it or give it more info.
57-
- goose works best when solving concrete problems - experiment with how far you need to break that problem
58-
down to get goose to solve it. Be specific! E.g. it will likely fail to `"create a banking app"`,
59-
but probably does a good job if prompted with `"create a Fastapi app with an endpoint for deposit and withdrawal
60-
and with account balances stored in mysql keyed by id"`
61-
- If goose doesn't have enough context to start with, it might go down the wrong direction. Tell it
62-
to read files that you are refering to or search for objects in code. Even better, ask it to summarize
63-
them for you, which will help it set up its own next steps.
64-
- Refer to any objects in files with something that is easy to search for, such as `"the MyExample class"
65-
- 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
66-
- 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.
67-
- goose will make mistakes, and go in the wrong direction from times, feel free to correct it, or start again.
68-
- 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).
69-
- Goose can run anywhere, doesn't have to be in a repo, just ask it!
82+
### Configuration options
83+
Example:
7084

71-
## Installation
85+
```yaml
86+
default:
87+
provider: openai
88+
processor: gpt-4o
89+
accelerator: gpt-4o-mini
90+
moderator: truncate
91+
toolkits:
92+
- name: developer
93+
requires: {}
94+
- name: screen
95+
requires: {}
96+
```
7297
73-
To install goose, we recommend `pipx`
98+
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
7499

75-
First make sure you've [installed pipx][pipx] - for example
100+
#### provider
101+
Provider of LLM. LLM providers that currently are supported by `goose`:
76102

77-
``` sh
78-
brew install pipx
79-
pipx ensurepath
80-
```
103+
| Provider | Required environment variable(s) to access provider |
104+
| :----- | :------------------------------ |
105+
| openai | `OPENAI_API_KEY` |
106+
| anthropic | `ANTHROPIC_API_KEY` |
107+
| databricks | `DATABRICKS_HOST` and `DATABRICKS_TOKEN` |
81108

82-
Then you can install goose with
83109

84-
``` sh
85-
pipx install goose-ai
86-
```
110+
#### processor
111+
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.
112+
113+
#### accelerator
114+
Small model for fast, lightweight tasks. Example: `gpt-4o-mini`. You should choose the model based the provider you configured.
87115

88-
### Config
116+
#### moderator
117+
Rules designed to control or manage the output of the model. Moderators that currently are supported by `goose`:
89118

90-
Goose will try to detect what LLM it can work with and place a config in `~/.config/goose/profiles.yaml` automatically.
119+
- `passive`: does not actively intervene in every response
120+
- `truncate`: truncates the first contexts when the contexts exceed the max token size
91121

92-
#### Toolkits
122+
#### toolkits
93123

94-
Goose can be extended with toolkits, and out of the box there are some available:
124+
`goose` can be extended with toolkits, and out of the box there are some available:
95125

96126
* `screen`: for letting goose take a look at your screen to help debug or work on designs (gives goose eyes)
97127
* `github`: for awareness and suggestions on how to use github
98128
* `repo_context`: for summarizing and understanding a repository you are working in.
99129

100-
To configure for example the screen toolkit, edit `~/.config/goose/profiles.yaml`:
130+
### Examples
131+
#### provider as `anthropic`
101132

102133
```yaml
103-
provider: openai
104-
processor: gpt-4o
105-
accelerator: gpt-4o-mini
134+
default:
135+
provider: anthropic
136+
processor: claude-3-5-sonnet-20240620
137+
accelerator: claude-3-5-sonnet-20240620
138+
...
139+
```
140+
#### provider as `databricks`
141+
```yaml
142+
default:
143+
provider: databricks
144+
processor: databricks-meta-llama-3-1-70b-instruct
145+
accelerator: databricks-meta-llama-3-1-70b-instruct
106146
moderator: passive
107147
toolkits:
108148
- name: developer
109149
requires: {}
110-
- name: screen
111-
requires: {}
112150
```
113151

152+
## Tips
153+
154+
Here are some collected tips we have for working efficiently with `goose`
155+
156+
- **`goose` can and will edit files**. Use a git strategy to avoid losing anything - such as staging your
157+
personal edits and leaving `goose` edits unstaged until reviewed. Or consider using individual commits which can be reverted.
158+
- **`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.
159+
- You can interrupt `goose` with `CTRL+C` to correct it or give it more info.
160+
- `goose` works best when solving concrete problems - experiment with how far you need to break that problem
161+
down to get `goose` to solve it. Be specific! E.g. it will likely fail to `"create a banking app"`,
162+
but probably does a good job if prompted with `"create a Fastapi app with an endpoint for deposit and withdrawal
163+
and with account balances stored in mysql keyed by id"`
164+
- If `goose` doesn't have enough context to start with, it might go down the wrong direction. Tell it
165+
to read files that you are referring to or search for objects in code. Even better, ask it to summarize
166+
them for you, which will help it set up its own next steps.
167+
- Refer to any objects in files with something that is easy to search for, such as `"the MyExample class"
168+
- `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
169+
- 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.
170+
- `goose` will make mistakes, and go in the wrong direction from times, feel free to correct it, or start again.
171+
- 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).
172+
- `goose` can run anywhere, doesn't have to be in a repo, just ask it!
173+
174+
114175
### Examples
115176

116177
Here are some examples that have been used:
@@ -141,61 +202,18 @@ Some hints are in this github issue: https://github.com/square/exchange/issues
141202
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.
142203
```
143204
205+
## FAQ
144206
145-
#### Advanced LLM config
146-
147-
goose works on top of LLMs (you bring your own LLM). If you need to customize goose, one way is via editing: `~/.config/goose/profiles.yaml`.
148-
149-
It will look by default something like:
150-
151-
```yaml
152-
default:
153-
provider: openai
154-
processor: gpt-4o
155-
accelerator: gpt-4o-mini
156-
moderator: truncate
157-
toolkits:
158-
- name: developer
159-
requires: {}
160-
```
161-
162-
*Note: This requires the environment variable `OPENAI_API_KEY` to be set to your OpenAI API key. goose uses at least 2 LLMs: one for acceleration for fast operating, and processing for writing code and executing commands.*
163-
164-
You can tell it to use another provider for example for Anthropic:
165-
166-
```yaml
167-
default:
168-
provider: anthropic
169-
processor: claude-3-5-sonnet-20240620
170-
accelerator: claude-3-5-sonnet-20240620
171-
...
172-
```
173-
174-
*Note: This will then use the claude-sonnet model, you will need to set the `ANTHROPIC_API_KEY` environment variable to your anthropic API key.*
175-
176-
For Databricks hosted models:
177-
178-
```yaml
179-
default:
180-
provider: databricks
181-
processor: databricks-meta-llama-3-1-70b-instruct
182-
accelerator: databricks-meta-llama-3-1-70b-instruct
183-
moderator: passive
184-
toolkits:
185-
- name: developer
186-
requires: {}
187-
```
188-
189-
This requires `DATABRICKS_HOST` and `DATABRICKS_TOKEN` to be set accordingly
207+
**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?
190208
191-
(goose can be extended to support any LLM or combination of LLMs).
209+
**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).
192210
193211
## Open Source
194212
195-
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.
213+
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.
196214
See LICENSE.md for more details.
197215
198-
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`.
216+
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`.
199217
200218
201219
[pipx]: https://github.com/pypa/pipx?tab=readme-ov-file#install-pipx

0 commit comments

Comments
 (0)