feat: V1.0 (#734)
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
Binary file not shown.
|
After Width: | Height: | Size: 705 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 620 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 684 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 490 KiB |
@@ -0,0 +1,213 @@
|
||||
/*@media only screen and (min-width: 76.25em) {*/
|
||||
/* .md-main__inner {*/
|
||||
/* max-width: none;*/
|
||||
/* }*/
|
||||
/* .md-sidebar--primary {*/
|
||||
/* left: 0;*/
|
||||
/* }*/
|
||||
/* .md-sidebar--secondary {*/
|
||||
/* right: 0;*/
|
||||
/* margin-left: 0;*/
|
||||
/* -webkit-transform: none;*/
|
||||
/* transform: none;*/
|
||||
/* }*/
|
||||
/*}*/
|
||||
|
||||
body {
|
||||
--md-code-fg-color: white !important;
|
||||
--md-code-bg-color: rgba(0, 0, 0, .5) !important;
|
||||
--shadow-color: #FF9E9E;
|
||||
--shadow-color-light: white;
|
||||
}
|
||||
|
||||
#__mermaid_0 {
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
.md-typeset code {
|
||||
border-radius: 5px;
|
||||
}
|
||||
|
||||
/* Reduce the space between the term and definition in a definition list
|
||||
Reads better for flags and their documention in CLI options lists */
|
||||
.md-typeset dd {
|
||||
margin-top: 0.125em;
|
||||
}
|
||||
|
||||
/* We want syntax highlighting in fenced codeblocks describing shell commands
|
||||
because it's nice to see comments dimmed and quoted strings highlighted. */
|
||||
.md-typeset .language-bash {
|
||||
/* We don't need to syntax-highlight numbers in bash blocks */
|
||||
--md-code-hl-number-color: var(--md-code-fg-color);
|
||||
/* We don't need to syntax-highlight shell-native functions (like `cd`) in bash blocks */
|
||||
--md-code-hl-constant-color: var(--md-code-fg-color);
|
||||
}
|
||||
|
||||
.highlight .kc, .highlight .n {
|
||||
color: rgba(255, 255, 255, 0.8);
|
||||
}
|
||||
|
||||
body .md-sidebar--primary .md-sidebar__scrollwrap {
|
||||
border-right: 1px solid #454755;
|
||||
}
|
||||
|
||||
.md-container {
|
||||
opacity: 1 !important;
|
||||
}
|
||||
|
||||
@media screen and (min-width: 76.25em) {
|
||||
.md-main::before {
|
||||
content: "";
|
||||
|
||||
background-size: cover !important;
|
||||
background-repeat: no-repeat !important;
|
||||
background-attachment: fixed !important;
|
||||
background-position: center !important;
|
||||
|
||||
position: absolute;
|
||||
z-index: -99999;
|
||||
top: 0;
|
||||
right: 0;
|
||||
bottom: 0;
|
||||
left: 0;
|
||||
opacity: .06;
|
||||
|
||||
animation: changeBg 15s infinite ease-in-out;
|
||||
|
||||
-webkit-transition: background 15s linear;
|
||||
-moz-transition: background 15s linear;
|
||||
-o-transition: background 15s linear;
|
||||
-ms-transition: background 15s linear;
|
||||
transition: background 15s linear;
|
||||
|
||||
animation-duration: 15s;
|
||||
animation-iteration-count: infinite;
|
||||
animation-direction: alternate;
|
||||
}
|
||||
}
|
||||
|
||||
@keyframes changeBg {
|
||||
0% {
|
||||
background-image: var(--bg1);
|
||||
}
|
||||
25% {
|
||||
background-image: var(--bg2);
|
||||
}
|
||||
50% {
|
||||
background-image: var(--bg3);
|
||||
}
|
||||
75% {
|
||||
background-image: var(--bg4);
|
||||
}
|
||||
100% {
|
||||
background-image: var(--bg1);
|
||||
}
|
||||
}
|
||||
|
||||
.md-header {
|
||||
background-color: rgba(14, 20, 24, 0.9) !important;
|
||||
}
|
||||
|
||||
.md-tabs {
|
||||
background-color: rgba(14, 20, 24, 0.6) !important;
|
||||
}
|
||||
|
||||
@media screen and (min-width: 76.25em) {
|
||||
.md-nav--lifted > .md-nav__list > .md-nav__item--active > .md-nav__link {
|
||||
background: none;
|
||||
box-shadow: none;
|
||||
}
|
||||
}
|
||||
|
||||
.md-nav__toggle.md-toggle--indeterminate~.md-nav, .md-nav__toggle:checked~.md-nav, .md-nav__toggle~.md-nav {
|
||||
-webkit-transition-property: none;
|
||||
-moz-transition-property: none;
|
||||
-o-transition-property: none;
|
||||
transition-property: none;
|
||||
}
|
||||
|
||||
@media screen and (min-width: 60em) {
|
||||
.md-nav--secondary .md-nav__title {
|
||||
background: none;
|
||||
box-shadow: none;
|
||||
}
|
||||
}
|
||||
|
||||
/*add a subtle breathing effect to admonitions border*/
|
||||
.admonition {
|
||||
animation: pulsate 10s infinite;
|
||||
border-radius: 7px;
|
||||
}
|
||||
|
||||
@keyframes pulsate {
|
||||
0% {
|
||||
-webkit-box-shadow: inset 0 0 .075rem rgb(138, 163, 255);
|
||||
-moz-box-shadow: inset 0 0 .075rem rgb(138, 163, 255);
|
||||
box-shadow: inset 0 0 .075rem rgb(138, 163, 255);
|
||||
}
|
||||
50% {
|
||||
border-color: rgba(255, 255, 255, .5);
|
||||
-webkit-box-shadow: inset 0 0 .075rem rgba(255, 255, 255, .5);
|
||||
-moz-box-shadow: inset 0 0 .075rem rgba(255, 255, 255, .5);
|
||||
box-shadow: inset 0 0 .075rem rgba(255, 255, 255, .5);
|
||||
}
|
||||
100% {
|
||||
-webkit-box-shadow: inset 0 0 .075rem rgb(138, 163, 255);
|
||||
-moz-box-shadow: inset 0 0 .075rem rgb(138, 163, 255);
|
||||
box-shadow: inset 0 0 .075rem rgb(138, 163, 255);
|
||||
}
|
||||
}
|
||||
|
||||
/*pop code elements a tad*/
|
||||
code {
|
||||
border: .075rem solid rgba(0, 0, 0, .3);
|
||||
}
|
||||
|
||||
img {
|
||||
border-radius: 10px;
|
||||
}
|
||||
|
||||
.neon {
|
||||
color: white;
|
||||
animation: neon 3s infinite;
|
||||
margin: calc(50vh - 40px) auto 0 auto;
|
||||
font-size: 25px;
|
||||
text-transform: uppercase;
|
||||
font-family: "Archivo Black", "Archivo", sans-serif;
|
||||
font-weight: normal;
|
||||
display: block;
|
||||
height: auto;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
@keyframes neon {
|
||||
0% {
|
||||
text-shadow: -1px -1px 1px var(--shadow-color-light), -1px 1px 1px var(--shadow-color-light), 1px -1px 1px var(--shadow-color-light), 1px 1px 1px var(--shadow-color-light),
|
||||
0 0 3px var(--shadow-color-light), 0 0 10px var(--shadow-color-light), 0 0 20px var(--shadow-color-light),
|
||||
0 0 30px var(--shadow-color), 0 0 20px var(--shadow-color), 0 0 25px var(--shadow-color), 0 0 35px var(--shadow-color), 0 0 25px var(--shadow-color), 0 0 25px var(--shadow-color);
|
||||
}
|
||||
50% {
|
||||
text-shadow: -1px -1px 1px var(--shadow-color-light), -1px 1px 1px var(--shadow-color-light), 1px -1px 1px var(--shadow-color-light), 1px 1px 1px var(--shadow-color-light),
|
||||
0 0 5px var(--shadow-color-light), 0 0 15px var(--shadow-color-light), 0 0 25px var(--shadow-color-light),
|
||||
0 0 40px var(--shadow-color), 0 0 25px var(--shadow-color), 0 0 30px var(--shadow-color), 0 0 40px var(--shadow-color), 0 0 30px var(--shadow-color), 0 0 30px var(--shadow-color);
|
||||
}
|
||||
100% {
|
||||
text-shadow: -1px -1px 1px var(--shadow-color-light), -1px 1px 1px var(--shadow-color-light), 1px -1px 1px var(--shadow-color-light), 1px 1px 1px var(--shadow-color-light),
|
||||
0 0 3px var(--shadow-color-light), 0 0 10px var(--shadow-color-light), 0 0 20px var(--shadow-color-light),
|
||||
0 0 30px var(--shadow-color), 0 0 20px var(--shadow-color), 0 0 25px var(--shadow-color), 0 0 35px var(--shadow-color), 0 0 25px var(--shadow-color), 0 0 25px var(--shadow-color);
|
||||
}
|
||||
}
|
||||
|
||||
.md-nav__item--section>.md-nav__link[for] {
|
||||
color: white;
|
||||
}
|
||||
|
||||
/* this is the top nav item side left */
|
||||
.md-nav--lifted>.md-nav__list>.md-nav__item>[for] {
|
||||
color: white;
|
||||
position: absolute; /* otherwise scroll overflow does not look great */
|
||||
}
|
||||
|
||||
.md-nav__link--active {
|
||||
color: white !important;
|
||||
}
|
||||
@@ -0,0 +1,261 @@
|
||||
const backgrounds = [
|
||||
"/assets/bg.png",
|
||||
"/assets/bg2.png",
|
||||
"/assets/bg3.png",
|
||||
"/assets/bg4.png",
|
||||
];
|
||||
|
||||
// this is to preload the images so the transition is smooth.
|
||||
// otherwise, on transition image will flicker without smooth transition.
|
||||
|
||||
var hiddenContainer = document.createElement('div');
|
||||
hiddenContainer.style.display = 'none';
|
||||
document.body.appendChild(hiddenContainer);
|
||||
|
||||
let index = 1;
|
||||
for (let bg of backgrounds) {
|
||||
let img = [];
|
||||
img[index] = new Image();
|
||||
img[index].src = bg;
|
||||
|
||||
hiddenContainer.appendChild(img[index]);
|
||||
index++;
|
||||
}
|
||||
|
||||
function shuffleBackgrounds() {
|
||||
let images = []; // preload
|
||||
let index = 1;
|
||||
for (let bg of shuffle(backgrounds)) {
|
||||
document.body.style.setProperty("--bg" + index, "url(" + bg + ")");
|
||||
index++;
|
||||
}
|
||||
}
|
||||
|
||||
function shuffle(array) {
|
||||
let currentIndex = array.length, randomIndex;
|
||||
|
||||
// While there remain elements to shuffle.
|
||||
while (currentIndex !== 0) {
|
||||
|
||||
// Pick a remaining element.
|
||||
randomIndex = Math.floor(Math.random() * currentIndex);
|
||||
currentIndex--;
|
||||
|
||||
// And swap it with the current element.
|
||||
[array[currentIndex], array[randomIndex]] = [
|
||||
array[randomIndex], array[currentIndex]];
|
||||
}
|
||||
|
||||
return array;
|
||||
}
|
||||
|
||||
shuffleBackgrounds();
|
||||
|
||||
window.onload = function () {
|
||||
onLoad();
|
||||
};
|
||||
|
||||
let origOpen = XMLHttpRequest.prototype.open;
|
||||
XMLHttpRequest.prototype.open = function () {
|
||||
let url = arguments[1]; // The second argument is the URL
|
||||
|
||||
this.addEventListener('loadend', function (e) {
|
||||
if (url.includes("https://codeserver.sq.dev/api/v1/health")) {
|
||||
return;
|
||||
}
|
||||
|
||||
console.log(url);
|
||||
|
||||
// make sure we have a full render before calling onLoad
|
||||
setTimeout(() => {
|
||||
onLoad();
|
||||
}, 100);
|
||||
});
|
||||
origOpen.apply(this, arguments);
|
||||
};
|
||||
|
||||
let healthCheckTimer = null;
|
||||
|
||||
function onLoad() {
|
||||
|
||||
console.log("onLoad");
|
||||
let interactiveCodePage = false;
|
||||
document.querySelectorAll("a").forEach((e) => {
|
||||
if (e.innerText === "Run Code") {
|
||||
interactiveCodePage = true;
|
||||
}
|
||||
});
|
||||
|
||||
if (interactiveCodePage) {
|
||||
document.querySelectorAll("code").forEach((e) => {
|
||||
e.style.maxHeight = "40vh";
|
||||
});
|
||||
}
|
||||
|
||||
if (healthCheckTimer) {
|
||||
console.log("clearing health check timer");
|
||||
clearInterval(healthCheckTimer);
|
||||
}
|
||||
|
||||
healthCheckTimer = setInterval(() => {
|
||||
// if the tab is not visible, don't check
|
||||
if (document.hidden) {
|
||||
return;
|
||||
}
|
||||
|
||||
// check if https://codeserver.sq.dev/api/v1/health is up
|
||||
const xhr = new XMLHttpRequest();
|
||||
xhr.open("GET", "https://codeserver.sq.dev/api/v1/health", true);
|
||||
xhr.send();
|
||||
xhr.timeout = 1000;
|
||||
xhr.onreadystatechange = function () {
|
||||
if (xhr.readyState === 4) {
|
||||
if (xhr.status === 200) {
|
||||
document.querySelectorAll("a").forEach((e) => {
|
||||
if (e.innerText === "Code Server is down") {
|
||||
e.innerText = "Run Code";
|
||||
e.onclick = function () {
|
||||
};
|
||||
}
|
||||
});
|
||||
} else {
|
||||
document.querySelectorAll("a").forEach((e) => {
|
||||
if (e.innerText === "Run Code") {
|
||||
e.innerText = "Code Server is down";
|
||||
e.onclick = function () {
|
||||
alert("Code Server is down.\n\nRun\n\nsq dev up codeserver\n\nto start the code server in your local development environment.");
|
||||
return false;
|
||||
};
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
};
|
||||
}, 1000);
|
||||
}
|
||||
|
||||
let codeServerRequestLoading = false;
|
||||
|
||||
// register button listener
|
||||
// this is for code running examples
|
||||
document.addEventListener("click", function (e) {
|
||||
if (e.target.innerText !== "Run Code") {
|
||||
return;
|
||||
}
|
||||
|
||||
if (codeServerRequestLoading) {
|
||||
alert("Please wait for the previous request to finish.");
|
||||
return;
|
||||
}
|
||||
|
||||
// console.log("e", e.target);
|
||||
// console.log("parent", e.target.parentElement);
|
||||
// console.log("parent pu", getPreviousUntil(e.target.parentElement, '.tabbed-block'));
|
||||
// console.log("parent > 1", e.target.parentElement.previousElementSibling);
|
||||
// console.log("parent > 2", e.target.parentElement.previousElementSibling.previousElementSibling);
|
||||
// console.log("parent > tabbed-block", e.target.parentElement.previousElementSibling.previousElementSibling);
|
||||
// console.log("parent > tabbed-block", e.target.parentElement.previousElementSibling.previousElementSibling.querySelectorAll('.tabbed-block'));
|
||||
|
||||
// const codeClass = e.target.parentElement.previousElementSibling.previousElementSibling.querySelectorAll('.tabbed-block');
|
||||
const codeClass = getPreviousUntil(e.target.parentElement, '.tabbed-content')[0].querySelectorAll('.tabbed-block');
|
||||
|
||||
// console.log("ele", codeClass);
|
||||
|
||||
let language = "";
|
||||
codeClass.forEach((e) => {
|
||||
console.log(window.getComputedStyle(e).display);
|
||||
// this is the visible code block
|
||||
if (window.getComputedStyle(e).display === "block") {
|
||||
console.log(e);
|
||||
const codeBlock = e.querySelector('code');
|
||||
if (codeBlock) {
|
||||
language = codeBlock.closest('div').className.split(" ")[0].split("-")[1];
|
||||
|
||||
console.log("code block", codeBlock);
|
||||
console.log(codeBlock.closest('div'));
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// console.log("Language", language);
|
||||
|
||||
document.getElementById("loader")?.remove();
|
||||
document.getElementById("output")?.remove();
|
||||
document.getElementById("output-error")?.remove();
|
||||
|
||||
const output = document.createElement("pre");
|
||||
output.id = "loader";
|
||||
output.innerHTML = "<code style='border: .075rem solid white'>Loading...</code>";
|
||||
e.target.parentElement.appendChild(output);
|
||||
|
||||
const code = e.target.parentElement.previousSibling.previousSibling.querySelector('.language-' + CSS.escape(language));
|
||||
if (code) {
|
||||
const xhr = new XMLHttpRequest();
|
||||
xhr.open("POST", "https://codeserver.sq.dev/api/v1/code/" + language + "/run", true);
|
||||
xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
|
||||
xhr.send(code.innerText);
|
||||
|
||||
codeServerRequestLoading = true;
|
||||
xhr.onreadystatechange = function () {
|
||||
document.getElementById("loader")?.remove();
|
||||
|
||||
if (xhr.readyState === 4) {
|
||||
|
||||
if (xhr.status === 200) {
|
||||
|
||||
// code result
|
||||
const output = document.createElement("div");
|
||||
output.id = "output";
|
||||
output.innerHTML = "<h4>" + toTitleCase(language) + " Execution</h4><pre><code style='border: .075rem solid green'>" + xhr.responseText + "</code></pre>";
|
||||
e.target.parentElement.appendChild(output);
|
||||
output.scrollIntoView({behavior: "smooth", block: "center", inline: "nearest"});
|
||||
} else {
|
||||
console.log("Error", xhr.statusText);
|
||||
const output = document.createElement("pre");
|
||||
output.id = "output-error";
|
||||
output.innerHTML = "<code style='border: solid 1px red'>" + xhr.responseText + "</code>";
|
||||
e.target.parentElement.appendChild(output);
|
||||
output.scrollIntoView({behavior: "smooth", block: "center", inline: "nearest"});
|
||||
}
|
||||
}
|
||||
|
||||
codeServerRequestLoading = false;
|
||||
|
||||
};
|
||||
}
|
||||
|
||||
// do something
|
||||
});
|
||||
|
||||
function toTitleCase(str) {
|
||||
return str.replace(
|
||||
/\w\S*/g,
|
||||
function (txt) {
|
||||
return txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase();
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
const getPreviousUntil = function (elem, selector) {
|
||||
|
||||
// Setup siblings array and get previous sibling
|
||||
const siblings = [];
|
||||
let prev = elem.previousElementSibling;
|
||||
|
||||
// Loop through all siblings
|
||||
while (prev) {
|
||||
|
||||
// If the matching item is found, quit
|
||||
if (selector && prev.matches(selector)) break;
|
||||
|
||||
// Otherwise, push to array
|
||||
siblings.push(prev);
|
||||
|
||||
// Get the previous sibling
|
||||
prev = prev.previousElementSibling;
|
||||
|
||||
}
|
||||
|
||||
return siblings;
|
||||
|
||||
};
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 9.2 MiB |
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 2.0 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 74 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 82 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 299 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 2.2 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 84 KiB |
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Configuration",
|
||||
"position": 5,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Extend goose functionalities with extensions and custom configurations"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,172 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Managing Goose Extensions
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
Extensions are add-ons that provide a way to extend the functionality of Goose. They also provide a way to connect Goose with applications and tools you already use in your workflow. These extensions can be used to add new features, automate tasks, or integrate with other systems.
|
||||
|
||||
Extensions are based on the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol), so you can connect
|
||||
Goose to a wide ecosystem of capabilities.
|
||||
|
||||
|
||||
## Adding Extensions
|
||||
|
||||
You can add extensions to Goose through the CLI or the UI.
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
|
||||
1. After the initial Goose setup, You can add extensions through the configuration system.
|
||||
|
||||
```
|
||||
goose configure
|
||||
```
|
||||
|
||||
2. Choose `Add Extension` to see the options.
|
||||
|
||||
You can also edit the config file directly, which is stored in `~/.config/goose/config.yaml`.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
1. Locate the menu (...) in the top right corner of the Goose UI.
|
||||
2. Select `Settings` from the menu.
|
||||
3. Under `Extensions`, you can add (+) a new extension manually,
|
||||
4. Or [`Browse Extensions`][extensions] to find curated extensions.
|
||||
5. Click 'Install' on extension you'd like to add and it installs right in the Goose app.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Removing Extensions
|
||||
|
||||
You can remove extensions installed on Goose
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
At the moment, you can remove extensions by editing the config file directly, which is stored in `~/.config/goose/config.yaml`.
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
|
||||
1. Locate the menu (...) in the top right corner of the Goose UI.
|
||||
2. Select `Settings` from the menu.
|
||||
3. Under `Extensions`, find the extension you'd like to remove and click on the settings icon beside it.
|
||||
4. In the dialog that appears, click `Remove Extension`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Built-in Extensions
|
||||
Out of the box, Goose is installed with a few extensions out of the box but with only the `Developer` extension enabled by default.
|
||||
|
||||
Here are the default extensions:
|
||||
|
||||
1. **Developer**: The `Developer` extension provides a set of general development tools that are useful for software development.
|
||||
2. **Non-Developer**: The `Non-Developer` extension provides general computer control tools that don't require you to be a developer or engineer.
|
||||
3. **Memory**: The `Memory` extension teaches goose to remember your preferences as you use it
|
||||
4. **JetBrains**: The `JetBrains` extension provides an integration for working with JetBrains IDEs.
|
||||
5. **Google Drive**: The `Google Drive` extension provides an integration for working with Google Drive for file management and access.
|
||||
|
||||
|
||||
#### Toggling Built-in Extensions
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
1. Run Goose configuration:
|
||||
|
||||
```bash
|
||||
goose configure
|
||||
```
|
||||
2. Choose `Add Extension`
|
||||
3. Choose `Built-in Extension`
|
||||
|
||||
Alternatively, you can enable a built-in extension by specifying its name in this command:
|
||||
|
||||
```
|
||||
goose mcp {name}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
1. Locate the menu (...) in the top right corner of the Goose UI.
|
||||
2. Select `Settings` from the menu.
|
||||
3. Under `Extensions`, you can toggle the built-in extensions on or off.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
:::tip
|
||||
All of Goose's built-in extensions are MCP servers in their own right. If you'd like
|
||||
to use the MCP servers included with Goose with any other agent, you are free to do so.
|
||||
:::
|
||||
|
||||
## MCP Servers
|
||||
|
||||
You can run any MCP server as a Goose extension.
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
|
||||
1. Run `goose configure`
|
||||
2. Choose `Add Extension`
|
||||
3. Choose `Command-line Extension`
|
||||
|
||||
You'll then be prompted to enter a command and any environment variables needed. For example, to connect to the [Fetch Server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch), enter `uvx mcp-server-fetch` as the command.
|
||||
|
||||
You can also edit the resulting config entry directly, which would look like this:
|
||||
|
||||
```yaml
|
||||
extensions:
|
||||
fetch:
|
||||
name: fetch
|
||||
cmd: uvx
|
||||
args: [mcp-server-fetch]
|
||||
enabled: true
|
||||
envs: {}
|
||||
type: stdio
|
||||
```
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
|
||||
1. Locate the menu (...) in the top right corner of the Goose UI.
|
||||
2. Select `Settings` from the menu.
|
||||
3. Under `Extensions`, you can add a MCP server as an extension manually by clicking on the (+) button to the right.
|
||||
4. In the dialog that appears, enter the details of the MCP server including any environment variables needed.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
## Discovering Extensions
|
||||
|
||||
Goose comes with a [central directory][extensions] of extensions that you can install and use. You can install extensions from the Goose CLI or from the Goose GUI. The page will give you a test command to try out extensions, and if you want to keep them, you can add through `goose configure`.
|
||||
|
||||
You can test out an extension for a single session with
|
||||
|
||||
```sh
|
||||
goose session --with-extension "command to run"
|
||||
```
|
||||
|
||||
|
||||
## Starting a Session with Extensions
|
||||
|
||||
You can start a tailored goose session with specific extensions directly from the CLI. To do this, run the following command:
|
||||
|
||||
```bash
|
||||
goose session --with-extension "{extension command}"
|
||||
```
|
||||
|
||||
:::note
|
||||
You may need to set necessary environment variables for the extension to work correctly.
|
||||
```bash
|
||||
goose session --with-extension "VAR=value command arg1 arg2"
|
||||
```
|
||||
:::
|
||||
|
||||
## Developing Extensions
|
||||
Goose extensions are implemented with MCP - a system that allows AI models and agents to securely connect with local or remote resources using standard protocols. Learn how to build your own [extension as an MCP server](https://modelcontextprotocol.io/quickstart/server).
|
||||
|
||||
|
||||
[extensions]: https://block.github.io/goose/v1/extensions
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Supported LLM Providers
|
||||
|
||||
You can use Goose with your preferred LLM. Goose supports a variety of LLM providers. To configure your chosen provider or see available options, run `goose configure` in the CLI or visit the `Provider Settings` page in the Goose UI.
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
1. Run the following command:
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Select `Configure Providers` from the menu.
|
||||
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
**To update your LLM provider and API key:**
|
||||
|
||||
1. Click on the three dots in the top-right corner.
|
||||
2. Select `Provider Settings` from the menu.
|
||||
3. Click Edit, enter your API key, and click `Set as Active`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Available Providers
|
||||
|
||||
- OpenAI
|
||||
- Databricks
|
||||
- Ollama
|
||||
- Anthropic
|
||||
- Google Gemini
|
||||
- Groq
|
||||
- OpenRouter
|
||||
|
||||
|
||||
### OpenAI
|
||||
|
||||
OpenAI offers powerful language models that include GPT-4, GPT-3.5-turbo, and more.
|
||||
|
||||
1. Run the following command and choose "Configure Providers":
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Select `OpenAI` from the list of available providers.
|
||||
3. Enter your `OPENAI_API_KEY` when prompted, which you can obtain by registering at [OpenAI's platform](https://platform.openai.com/api-keys).
|
||||
|
||||
### Databricks
|
||||
|
||||
Databricks is a data analytics and AI platform that provides access to various AI models and tools. They offer integration with popular models and custom model deployment.
|
||||
|
||||
1. Run the following command and choose "Configure Providers":
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Select `Databricks` as your provider.
|
||||
3. Enter your `DATABRICKS_HOST` and `DATABRICKS_TOKEN`, which can be generated in your [Databricks Account Settings](https://www.databricks.com/).
|
||||
|
||||
### Ollama
|
||||
|
||||
Ollama is an open-source project that allows running large language models locally. It supports various open-source models and provides an API for integration.
|
||||
|
||||
1. Run the following command and choose "Configure Providers":
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Select `Ollama` and follow the steps to download and set up your models as detailed on [Ollama's site](https://ollama.com/). Requires `OLLAMA_HOST`.
|
||||
|
||||
### Anthropic
|
||||
|
||||
Anthropic is an AI research company that offers advanced language models through its API. Their primary model is Claude, which comes in various versions.
|
||||
|
||||
1. Run the following command and choose "Configure Providers":
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Choose `Anthropic` and provide the `ANTHROPIC_API_KEY`, obtainable via [Anthropic's platform](https://www.anthropic.com/).
|
||||
|
||||
### Google Gemini
|
||||
|
||||
Google Gemini is a suite of large language models developed by Google. It offers multimodal capabilities and can be accessed through the [Google AI Studio](https://ai.google.dev/gemini-api/docs).
|
||||
|
||||
1. Run the following command and choose "Configure Providers":
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Pick `Google Gemini` from the list of providers and input your `GOOGLE_API_KEY`. .
|
||||
|
||||
### Groq
|
||||
|
||||
Groq is an AI company that offers high-performance inference for large language models. They provide access to various models through their API.
|
||||
|
||||
1. Run the following command and choose "Configure Providers":
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Select `Groq` from the list of providers and input your `GROQ_API_KEY`, set up via the [Groq Console](https://groq.com/).
|
||||
|
||||
### OpenRouter
|
||||
|
||||
OpenRouter is a platform that provides access to multiple AI models from various providers through a single API. It simplifies the process of using different AI models in applications.
|
||||
|
||||
1. Run the following command and choose "Configure Providers":
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
|
||||
2. Select `OpenRouter` from the list of providers and input your `OPENROUTER_API_KEY`, set up via the [OpenRouter Console](https://openrouter.ai/).
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Getting Started",
|
||||
"position": 3,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Get up to speed quickly with Goose"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Using Extensions
|
||||
---
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Using Extensions
|
||||
|
||||
:::info Supported Environments
|
||||
Goose currently works only on **OSX** and **Linux** systems, and supports both **ARM** and **x86** architectures. If you'd like to request support for additional operating systems, please [open an issue on GitHub](https://github.com/block/goose/issues/new?template=Blank+issue) to let us know.
|
||||
:::
|
||||
|
||||
Goose Extensions are add-ons that provide a way to extend the functionality of Goose by connecting with applications and tools you already use in your workflow. These extensions can be used to add new features, access data and resources, or integrate with other systems.
|
||||
|
||||
### Adding An Extension
|
||||
When you install Goose, a few built-in extensions are included. In addition, you can add external extensions that were developed on the [Model Context Protocol (MCP)][mcp].
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
|
||||
**To add an extension:**
|
||||
|
||||
1. Run the following command:
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Select `Add Extension` from the menu.
|
||||
3. Choose the type of extension you’d like to add:
|
||||
- `Built-In Extension`: Use an extension that comes pre-installed with Goose.
|
||||
- `Command-Line Extension`: Add a local command or script to run as an extension.
|
||||
- `Remote Extension`: Connect to a remote system via SSE (Server-Sent Events).
|
||||
4. Follow the prompts based on the type of extension you selected.
|
||||
|
||||
**Example: Adding Built-in Extension**
|
||||
|
||||
To select an option during configuration, hover over it and press Enter.
|
||||
|
||||
```sh
|
||||
What would you like to configure?
|
||||
Configure Providers
|
||||
Toggle Extensions
|
||||
> Add Extension
|
||||
|
||||
|
||||
What type of extension would you like to add?
|
||||
> Built-in Extension
|
||||
Command-line Extension
|
||||
Remote Extension
|
||||
|
||||
Which Built-in extension would you like to enable?
|
||||
Developer Tools
|
||||
Non Developer
|
||||
> Jetbrains
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
**Extensions can be installed directly from the [directory page][extensions-directory] to the Goose UI as shown below.**
|
||||
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Toggle Extensions
|
||||
|
||||
You can manage extensions by enabling or disabling them based on your workflow needs. Both, the CLI and UI, allow you to toggle extensions on or off as necessary.
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
**To enable or disable extensions that are already installed:**
|
||||
|
||||
1. Run the following command to open up Goose's configurations:
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Select `Toggle Extensions` from the menu.
|
||||
3. A list of already installed extensions will populate.
|
||||
4. Press the `space bar` to toggle the extension `enabled` or `disabled`.
|
||||
|
||||
**Example:**
|
||||
|
||||
To select an option during configuration, hover over it and press Enter.
|
||||
```sh
|
||||
What would you like to configure?
|
||||
Configure Providers
|
||||
> Toggle Extensions
|
||||
Add Extension
|
||||
|
||||
Enable systems: (use "space" to toggle and "enter" to submit)
|
||||
[ ] Developer Tools
|
||||
[X] JetBrains
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
**To enable or disable extensions that are already installed:**
|
||||
|
||||
1. Click the three dots in the top-right corner of the application.
|
||||
2. Select `Settings` from the menu, then click on the `Extensions` section.
|
||||
2. Use the toggle switch next to each extension to enable or disable it.
|
||||
|
||||
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Additional Resources
|
||||
|
||||
Visit the [Installation Guide][installation-guide] for detailed instructions on how to update your LLM provider.
|
||||
|
||||
[providers]: /docs/configuration/providers
|
||||
[handling-rate-limits]: /docs/guides/handling-llm-rate-limits-with-goose
|
||||
[mcp]: https://www.anthropic.com/news/model-context-protocol
|
||||
[installation-guide]: /docs/installation/#update-a-provider
|
||||
[extensions-directory]: https://silver-disco-nvm6v4e.pages.github.io/
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Using Goose for Free
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Using Goose for Free
|
||||
|
||||
:::info Supported Environments
|
||||
Goose currently works only on **OSX** and **Linux** systems, and supports both **ARM** and **x86** architectures. If you'd like to request support for additional operating systems, please [open an issue on GitHub](https://github.com/block/goose/issues/new?template=Blank+issue) to let us know.
|
||||
:::
|
||||
|
||||
Goose is a free and open source developer AI agent that you can start using right away, but not all supported [LLM Providers][providers] provide a free tier.
|
||||
|
||||
Below, we outline a couple of free options and how to get started with them.
|
||||
|
||||
|
||||
## Google Gemini
|
||||
Google Gemini provides free access to its AI capabilities with some limitations. To start using the Gemini API with Goose, you need an API Key from [Google AI studio](https://aistudio.google.com/app/apikey).
|
||||
|
||||
To set up Google Gemini with Goose, follow these steps:
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
1. Run:
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Select `Configure Providers` from the menu.
|
||||
3. Follow the prompts to choose `Google Gemini` as the provider and enter your API key.
|
||||
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
**To update your LLM provider and API key:**
|
||||
|
||||
1. Click on the three dots in the top-right corner.
|
||||
2. Select `Provider Settings` from the menu.
|
||||
2. Choose `Google Gemini` as provider from the list.
|
||||
3. Click Edit, enter your API key, and click `Set as Active`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Limitations
|
||||
|
||||
These free options are a great way to get started with Goose and explore its capabilities. However, if you need more advanced features or higher usage limits, you can upgrade to a paid plan with your LLM provider.
|
||||
|
||||
---
|
||||
|
||||
If you have any questions or need help with a specific provider, feel free to reach out to us on [Discord](https://discord.gg/block-opensource) or on the [Goose repo](https://github.com/block/goose).
|
||||
|
||||
|
||||
[providers]: /docs/configuration/providers
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Architecture Overview",
|
||||
"position": 5,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Extend Goose functionalities with extensions and custom configurations"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Error Handling
|
||||
---
|
||||
# Error Handling in Goose
|
||||
|
||||
Error handling is a key performance-driving part of Goose. There are many ways that the non-determinism
|
||||
in the LLM can introduce an error that it can in turn recover from. In a typical Goose session, it's expected for there
|
||||
to be several agent errors that the model can see directly and correct, perhaps entirely behind the scenes.
|
||||
|
||||
## Traditional Errors
|
||||
|
||||
While the agent is operating, there can be intermittent issues in the network, availability of the
|
||||
foundational model, etc. These are raised as errors in the agent API to the caller, who can decide
|
||||
how to handle that. We generally handle these with [anyhow::Error][anyhow-error].
|
||||
|
||||
## Agent Errors
|
||||
|
||||
There are several types of errors where everything is working correctly, but the model generations
|
||||
themselves are somehow causing errors. Things like generating an unknown tool name, incorrect parameters,
|
||||
or a well formed tool call that results in an error in the tool itself. All of these can be surfaced to
|
||||
the LLM to have it attempt to recover.
|
||||
|
||||
The error messages are in some ways prompting - they give instructions to the LLM on how it might go
|
||||
about recovering. We handle these with [thiserror::Error][this-error] and carefully maintain a collection.
|
||||
|
||||
To cover all these cases, both `ToolUse` and `ToolResult` are typically passed through the API as part of a
|
||||
`Result<T, AgentError>`. An error in a `ToolUse` will immediately become an error in a `ToolResult` and
|
||||
passed back to the LLM. A valid `ToolUse` might still end up in an error `ToolResult`, which is also passed
|
||||
back to the LLM.
|
||||
|
||||
The providers then handle translating the agent errors into the various API specs as valid messages.
|
||||
|
||||
|
||||
[anyhow-error]: https://docs.rs/anyhow/latest/anyhow/
|
||||
[this-error]: https://docs.rs/thiserror/latest/thiserror/
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
# Extensions Design
|
||||
|
||||
This document describes the design and implementation of the Extensions framework in Goose, which enables AI agents to interact with different extensions through a unified tool-based interface.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Extension
|
||||
An Extension represents any component that can be operated by an AI agent. Extensions expose their capabilities through Tools and maintain their own state. The core interface is defined by the `Extension` trait:
|
||||
|
||||
```rust
|
||||
#[async_trait]
|
||||
pub trait Extension: Send + Sync {
|
||||
fn name(&self) -> &str;
|
||||
fn description(&self) -> &str;
|
||||
fn instructions(&self) -> &str;
|
||||
fn tools(&self) -> &[Tool];
|
||||
async fn status(&self) -> AnyhowResult<HashMap<String, Value>>;
|
||||
async fn call_tool(&self, tool_name: &str, parameters: HashMap<String, Value>) -> ToolResult<Value>;
|
||||
}
|
||||
```
|
||||
|
||||
### Tools
|
||||
Tools are the primary way Extensions expose functionality to agents. Each tool has:
|
||||
- A name
|
||||
- A description
|
||||
- A set of parameters
|
||||
- An implementation that executes the tool's functionality
|
||||
|
||||
A tool must take a Value and return an `AgentResult<Value>` (it must also be async). This
|
||||
is what makes it compatible with the tool calling framework from the agent.
|
||||
|
||||
```rust
|
||||
async fn echo(&self, params: Value) -> AgentResult<Value>
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Component Overview
|
||||
|
||||
1. **Extension Trait**: The core interface that all extensions must implement
|
||||
2. **Error Handling**: Specialized error types for tool execution
|
||||
3. **Proc Macros**: Simplify tool definition and registration [*not yet implemented*]
|
||||
|
||||
### Error Handling
|
||||
|
||||
The system uses two main error types:
|
||||
- `ToolError`: Specific errors related to tool execution
|
||||
- `anyhow::Error`: General purpose errors for extension status and other operations
|
||||
|
||||
This split allows precise error handling for tool execution while maintaining flexibility for general extension operations.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Tool Design
|
||||
|
||||
1. **Clear Names**: Use clear, action-oriented names for tools (e.g., "create_user" not "user")
|
||||
2. **Descriptive Parameters**: Each parameter should have a clear description
|
||||
3. **Error Handling**: Return specific errors when possible, the errors become "prompts"
|
||||
4. **State Management**: Be explicit about state modifications
|
||||
|
||||
### Extension Implementation
|
||||
|
||||
1. **State Encapsulation**: Keep extension state private and controlled
|
||||
2. **Error Propagation**: Use `?` operator with `ToolError` for tool execution
|
||||
3. **Status Clarity**: Provide clear, structured status information
|
||||
4. **Documentation**: Document all tools and their effects
|
||||
|
||||
### Example Implementation
|
||||
|
||||
Here's a complete example of a simple extension:
|
||||
|
||||
```rust
|
||||
use goose_macros::tool;
|
||||
|
||||
struct FileSystem {
|
||||
registry: ToolRegistry,
|
||||
root_path: PathBuf,
|
||||
}
|
||||
|
||||
impl FileSystem {
|
||||
#[tool(
|
||||
name = "read_file",
|
||||
description = "Read contents of a file"
|
||||
)]
|
||||
async fn read_file(&self, path: String) -> ToolResult<Value> {
|
||||
let full_path = self.root_path.join(path);
|
||||
let content = tokio::fs::read_to_string(full_path)
|
||||
.await
|
||||
.map_err(|e| ToolError::ExecutionError(e.to_string()))?;
|
||||
|
||||
Ok(json!({ "content": content }))
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for FileSystem {
|
||||
// ... implement trait methods ...
|
||||
}
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Extensions should be tested at multiple levels:
|
||||
1. Unit tests for individual tools
|
||||
2. Integration tests for extension behavior
|
||||
3. Property tests for tool invariants
|
||||
|
||||
Example test:
|
||||
```rust
|
||||
#[tokio::test]
|
||||
async fn test_echo_tool() {
|
||||
let extension = TestExtension::new();
|
||||
let result = extension.call_tool(
|
||||
"echo",
|
||||
hashmap!{ "message" => json!("hello") }
|
||||
).await;
|
||||
|
||||
assert_eq!(result.unwrap(), json!({ "response": "hello" }));
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Guides",
|
||||
"position": 4,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Learn essential tips and recommendations for using Goose"
|
||||
}
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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'
|
||||
```
|
||||
@@ -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.
|
||||
|
||||
@@ -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>
|
||||
@@ -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
|
||||
@@ -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/
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Installation
|
||||
|
||||
:::info Supported Environments
|
||||
Goose currently works only on **OSX** and **Linux** systems, and supports both **ARM** and **x86** architectures. If you'd like to request support for additional operating systems, please [open an issue on GitHub](https://github.com/block/goose/issues/new?template=Blank+issue) to let us know.
|
||||
:::
|
||||
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
#### Installing the Goose CLI
|
||||
To install Goose, run the following script on macOS or Linux.
|
||||
|
||||
```sh
|
||||
curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | sh
|
||||
```
|
||||
This script will fetch the latest version of Goose and set it up on your system.
|
||||
|
||||
:::tip Best Practice
|
||||
It’s best to keep Goose updated. You can update it by re-running the installation script.
|
||||
:::
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
#### Installing the Goose Desktop Application
|
||||
To install Goose, click the **button** below:
|
||||
<Button
|
||||
label=":arrow_down: Download Goose Desktop"
|
||||
link="https://github.com/block/goose/releases/download/stable/Goose.zip"
|
||||
variant="secondary"
|
||||
size="lg"
|
||||
outline
|
||||
/>
|
||||
<div style={{ marginTop: '1rem' }}>
|
||||
1. Unzip the downloaded `Goose.zip` file.
|
||||
2. Run the executable file to launch the Goose desktop application.
|
||||
:::tip Best Practice
|
||||
It’s best to keep Goose updated. You can do this by checking the [Goose GitHub Release page](https://github.com/block/goose/releases/stable) and downloading updates when available.
|
||||
:::
|
||||
</div>
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Set Up a Provider
|
||||
Goose works with a set of [supported LLM providers][providers], and you’ll need an API key to get started. When you use Goose for the first time, you’ll be prompted to select a provider and enter your API key.
|
||||
|
||||
The process will look similar to the example below:
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Update a Provider
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
**To update your LLM provider and API key:**
|
||||
1. Run the following command:
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
2. Select `Configure Providers` from the menu.
|
||||
3. Follow the prompts to choose your LLM provider and enter or update your API key.
|
||||
|
||||
**Example:**
|
||||
|
||||
To select an option during configuration, hover over it and press Enter.
|
||||
|
||||
```sh
|
||||
What would you like to configure?
|
||||
> Configure Providers
|
||||
Toggle Extensions
|
||||
Add Extension
|
||||
|
||||
Which Model provider should we use?
|
||||
> OpenAI
|
||||
Databricks
|
||||
Ollama
|
||||
.....
|
||||
|
||||
Enter Api Key:
|
||||
> sk-1234abcd5678efgh
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
**To update your LLM provider and API key:**
|
||||
|
||||
1. Click on the three dots in the top-right corner.
|
||||
2. Select `Provider Settings` from the menu.
|
||||
2. Choose a provider from the list.
|
||||
3. Click Edit, enter your API key, and click `Set as Active`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::info Billing
|
||||
You will need to have credits in your LLM Provider account (when necessary) to be able to successfully make requests. Some providers also have rate limits on API usage, which can affect your experience. Check out the [Handling Rate Limits][handling-rate-limits] guide to learn how to efficiently manage these limits while using Goose.
|
||||
:::
|
||||
|
||||
## Running Goose
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
From your terminal, navigate to the directory you'd like to start from and run:
|
||||
```sh
|
||||
goose session
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
Starting a session in the Goose UI is straightforward. After choosing your provider, you’ll see the session interface ready for use.
|
||||
|
||||
Type your questions, tasks, or instructions directly into the input field, and Goose will get to work immediately.
|
||||
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Additional Resources
|
||||
|
||||
You can also configure Extensions to extend Goose's functionality, including adding new ones or toggling them on and off. For detailed instructions, visit the [Using Extensions Guide][using-extensions].
|
||||
|
||||
[using-extensions]: /docs/configuration/managing-extensions
|
||||
[providers]: /docs/configuration/providers
|
||||
[handling-rate-limits]: /docs/guides/handling-llm-rate-limits-with-goose
|
||||
[mcp]: https://www.anthropic.com/news/model-context-protocol
|
||||
@@ -0,0 +1,159 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Quickstart
|
||||
---
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
|
||||
# Goose in 5 minutes
|
||||
|
||||
:::info Supported Environments
|
||||
Goose currently works only on **OSX** and **Linux** systems, and supports both **ARM** and **x86** architectures. If you'd like to request support for additional operating systems, please [open an issue on GitHub](https://github.com/block/goose/issues/new?template=Blank+issue) to let us know.
|
||||
:::
|
||||
|
||||
## Quickstart
|
||||
|
||||
Goose is a developer AI agent that supercharges your software development by automating coding tasks. This Quickstart will guide you through getting started with Goose and covers using both the CLI and Desktop UI.
|
||||
|
||||
|
||||
### Installation
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
#### Installing the Goose CLI
|
||||
To install Goose, run the following script on macOS or Linux.
|
||||
|
||||
```sh
|
||||
curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | sh
|
||||
```
|
||||
This script will fetch the latest version of Goose and set it up on your system.
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
#### Installing the Goose Desktop Application
|
||||
To install Goose, click the **button** below:
|
||||
<Button
|
||||
label=":arrow_down: Download Goose Desktop"
|
||||
link="https://github.com/block/goose/releases/download/stable/Goose.zip"
|
||||
variant="secondary"
|
||||
size="lg"
|
||||
outline
|
||||
/>
|
||||
<div style={{ marginTop: '1rem' }}>
|
||||
1. Unzip the downloaded `Goose.zip` file.
|
||||
2. Run the executable file to launch the Goose desktop application.
|
||||
</div>
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Running Goose
|
||||
|
||||
#### Set up a provider
|
||||
Goose works with [supported LLM providers][providers]. When you first run Goose, you'll be prompted to supply an API key from your preferred LLM provider.
|
||||
|
||||
The process will look similar to the example below:
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="cli" label="Goose CLI" default>
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="ui" label="Goose UI">
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::info Billing
|
||||
You will need to have credits in your LLM Provider account (when necessary) to be able to successfully make requests. Some providers also have rate limits on API usage, which can affect your experience. Check out our [Handling Rate Limits][handling-rate-limits] guide to learn how to efficiently manage these limits while using Goose.
|
||||
:::
|
||||
|
||||
#### Start a session
|
||||
<Tabs groupId="interface">
|
||||
<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>
|
||||
|
||||
#### Make Goose do the work for you
|
||||
|
||||
You will see the Goose prompt `( O)>`. From here, you can interact with Goose in conversational sessions. Think of it as you're giving directions to a junior developer.
|
||||
|
||||
```
|
||||
( O)> type your instructions here exactly as you would speak to a developer.
|
||||
```
|
||||
|
||||
Here's an example:
|
||||
|
||||
```
|
||||
( O)> Create a JavaScript project that fetches and displays weather for a user specified city using a public API
|
||||
```
|
||||
|
||||
You can interrupt Goose with `CTRL+C` while it is running to help redirect its efforts.
|
||||
|
||||
#### Exit the session
|
||||
|
||||
To end a session, use `CTRL+D` or enter `/exit`.
|
||||
|
||||
#### Resume a session
|
||||
|
||||
When you exit a session, it will save the history in the `~/.config/goose/sessions` directory. You can later resume your last saved session by using:
|
||||
|
||||
``` sh
|
||||
goose session --resume
|
||||
```
|
||||
|
||||
Check out [Managing Goose sessions][managing-sessions] to learn more about working with sessions in Goose.
|
||||
|
||||
|
||||
Be sure to check out the available [CLI commands][cli]. If you’d like to develop your own CLI commands for Goose, check out the [Contributing guide][contributing].
|
||||
|
||||
|
||||
### Running a Goose task
|
||||
|
||||
As an alternative to the chat interface, you can also provide instructions to Goose via files. In this example, Goose will execute the commands that are specified in `instructions.md`:
|
||||
|
||||
```sh
|
||||
goose run -t "Create a new Python file that prints hello world" instructions.md
|
||||
```
|
||||
|
||||
You can also pass in a file full of instructions, or use process substitution to chain more complex commands:
|
||||
|
||||
```sh
|
||||
goose run -t instructions.md
|
||||
goose run -t <(echo "Create a new Python file that prints hello world")
|
||||
```
|
||||
|
||||
This will run until completion as best it can. If you'd like to take the run and turn it into an interactive session,
|
||||
you can use `goose session --resume` to pick up where it left off.
|
||||
|
||||
### Extending Goose Functionality
|
||||
|
||||
[Goose Extensions][extensions-guide] are add-ons built on the [Model Context Protocol(MCP)][MCP]. They enhance Goose's functionality by integrating with the applications and tools you already use in your workflow. Extensions can be used to add new features, access data, and integrate with other systems.
|
||||
|
||||
For more information on how to add or remove extensions, see [Managing Extensions][extensions-guide].
|
||||
|
||||
## Additional tips
|
||||
|
||||
You can provide Goose with a set of hints that it will automatically use in every session with you. To do so, create a file named `.goosehints` and save it in `~/.config/goose/.goosehints`. For additional tips to enhance your experience, check out [Quick Tips][quick-tips].
|
||||
|
||||
|
||||
|
||||
[handling-rate-limits]: /docs/guides/handling-llm-rate-limits-with-goose
|
||||
[openai-key]: https://platform.openai.com/api-keys
|
||||
[getting-started]: /docs/category/getting-started
|
||||
[providers]: /docs/configuration/providers
|
||||
[managing-sessions]: /docs/guides/managing-goose-sessions
|
||||
[contributing]: https://github.com/block/goose/blob/main/CONTRIBUTING.md
|
||||
[quick-tips]: /docs/guides/tips
|
||||
[extensions-guide]: /docs/configuration/managing-extensions
|
||||
[cli]: /docs/guides/goose-cli-commands
|
||||
[MCP]: https://www.anthropic.com/news/model-context-protocol
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
Goose, like any system, may run into occasional issues. This guide provides solutions for common problems.
|
||||
|
||||
### Goose Edits Files
|
||||
Goose can and will edit files as part of its workflow. To avoid losing personal changes, use version control to stage your personal edits. Leave Goose edits unstaged until reviewed. Consider separate commits for Goose's edits so you can easily revert them if needed.
|
||||
|
||||
---
|
||||
|
||||
### Interrupting Goose
|
||||
If Goose is heading in the wrong direction or gets stuck, you can interrupt it by pressing `CTRL+C`. This will stop Goose and give you the opportunity to correct its actions or provide additional information.
|
||||
|
||||
---
|
||||
|
||||
### Stuck in a Loop or Unresponsive
|
||||
In rare cases, Goose may enter a "death loop" or become unresponsive during a long session. This is often resolved by ending the current session, and starting a new session.
|
||||
|
||||
1. Hold down `Ctrl + C` to cancel
|
||||
2. Start a new session:
|
||||
```sh
|
||||
goose session
|
||||
```
|
||||
:::tip
|
||||
For particularly large or complex tasks, consider breaking them into smaller sessions.
|
||||
:::
|
||||
|
||||
---
|
||||
### Context Length Exceeded Error
|
||||
|
||||
This error occurs when the input provided to Goose exceeds the maximum token limit of the LLM being used. To resolve this try breaking down your input into smaller parts. You can also use `.goosehints` as a way to provide goose with detailed context. Refer to the [Using Goosehints Guide][goosehints] for more information.
|
||||
|
||||
---
|
||||
|
||||
### Handling Rate Limit Errors
|
||||
Goose may encounter a `429 error` (rate limit exceeded) when interacting with LLM providers. The recommended solution is to use OpenRouter. See [Handling LLM Rate Limits][handling-rate-limits] for more info.
|
||||
|
||||
---
|
||||
|
||||
### API Errors
|
||||
|
||||
Users may run into an error like the one below when there are issues with their LLM API tokens, such as running out of credits or incorrect configuration:
|
||||
|
||||
```sh
|
||||
Traceback (most recent call last):
|
||||
File "/Users/admin/.local/pipx/venvs/goose-ai/lib/python3.13/site-packages/exchange/providers/utils.py",
|
||||
line 30, in raise_for_status
|
||||
response.raise_for_status()
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~^^
|
||||
File "/Users/admin/.local/pipx/venvs/goose-ai/lib/python3.13/site-packages/httpx/_models.py",
|
||||
line 829, in raise_for_status
|
||||
raise HTTPStatusError(message, request=request, response=self)
|
||||
httpx.HTTPStatusError: Client error '404 Not Found' for url
|
||||
'https://api.openai.com/v1/chat/completions'
|
||||
|
||||
...
|
||||
```
|
||||
This error typically occurs when LLM API credits are exhausted or your API key is invalid. To resolve this issue:
|
||||
|
||||
1. Check Your API Credits:
|
||||
- Log into your LLM provider's dashboard
|
||||
- Verify that you have enough credits. If not, refill them
|
||||
2. Verify API Key:
|
||||
- Run the following command to reconfigure your API key:
|
||||
```sh
|
||||
goose configure
|
||||
```
|
||||
For detailed steps on updating your LLM provider, refer to the [Installation][installation] Guide.
|
||||
|
||||
---
|
||||
|
||||
### Need Further Help?
|
||||
If you have questions, run into issues, or just need to brainstorm ideas join the [Discord Community][discord]!
|
||||
|
||||
|
||||
|
||||
[handling-rate-limits]: /docs/guides/handling-llm-rate-limits-with-goose
|
||||
[installation]: /docs/installation
|
||||
[discord]: https://discord.gg/block-opensource
|
||||
[goosehints]: /docs/guides/using-goosehints
|
||||
Reference in New Issue
Block a user