goose

https://goose-docs.ai/docs/
Admin
goose is an open-source AI agent that runs on your machine as a desktop app, CLI, or API, extensible...
Tokens:417,945
Snippets:3,349
Trust Score:5.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install and run the example hello-hooks plugin

Source: https://goose-docs.ai/docs/guides/context-engineering/hooks

Commands to copy the example plugin into the user plugins directory, make its announce script executable, and start a goose session. The plugin prints hook events to stderr and appends payloads to ~/.agents/plugins/hello-hooks/last-event.log.

```bash
mkdir -p ~/.agents/plugins
cp -R examples/plugins/hello-hooks ~/.agents/plugins/hello-hooks
chmod +x ~/.agents/plugins/hello-hooks/scripts/announce.sh

goose session
```

--------------------------------

### Start session with Fetch extension using uvx

Source: https://goose-docs.ai/docs/getting-started/using-extensions

Example of starting a session with the Fetch extension by running the uvx command.

```bash
goose session --with-extension "uvx mcp-server-fetch"
```

--------------------------------

### Example goose prompt for starting a tutorial

Source: https://goose-docs.ai/docs/mcp/tutorial-mcp

Prompt used to start learning about building extensions.

```text
I'd like to learn how to build an extension for goose
```

--------------------------------

### Example output of plugin installation

Source: https://goose-docs.ai/docs/guides/context-engineering/plugins

Shows the expected output after installing a plugin, including the plugin name, version, source, location, and imported skills.

```text
✓ Installed open-plugins plugin 'my-plugin' (1.0.0)
  Source: https://github.com/example/my-goose-plugin.git
  Location: /Users/you/.agents/plugins/my-plugin
  Imported skills:
    - my-plugin:review
    - my-plugin:test-plan
```

--------------------------------

### Install and start ClawMetry

Source: https://goose-docs.ai/docs/tutorials/clawmetry

Install ClawMetry via pip and start the dashboard. After running these commands, open http://localhost:8900. No goose-side configuration is needed.

```bash
pip install clawmetry
clawmetry
```

--------------------------------

### Start session with GitHub extension using environment variable

Source: https://goose-docs.ai/docs/getting-started/using-extensions

Example of starting a session with the GitHub extension, passing a personal access token as an environment variable. Requires Node.js installed.

```bash
goose session --with-extension "GITHUB_PERSONAL_ACCESS_TOKEN=<YOUR_TOKEN> npx -y @modelcontextprotocol/server-github"
```

--------------------------------

### Install MLflow and start the tracking server

Source: https://goose-docs.ai/docs/tutorials/mlflow

Installs MLflow and starts the tracking server on port 5000. The MLflow UI will be available at http://localhost:5000. For production, configure a SQL backend store instead of the default SQLite.

```bash
pip install mlflow
mlflow server --port 5000
```

--------------------------------

### Example command with a specific path

Source: https://goose-docs.ai/docs/tutorials/custom-extensions

An example of the command with a specific user path, as shown in the guide.

```plaintext
uv run /Users/smohammed/Development/mcp/mcp-wiki/.venv/bin/mcp-wiki
```

--------------------------------

### Example goose output for tutorial session

Source: https://goose-docs.ai/docs/mcp/tutorial-mcp

Output from goose when starting the build-mcp-extension tutorial, showing the load_tutorial tool call and the initial guidance message.

```text
I'll help you learn about building extensions! The "build-mcp-extension" tutorial would be perfect for this. Let me load it and guide you through it.

─── load_tutorial | tutorial ──────────────────────────
name: build-mcp-extension

Before we dive into building your extension, I need to understand a few things to better guide you:

1. Which SDK would you prefer to use? We have three options:
   - Python (beginner-friendly, great for prototyping)
   - TypeScript (great for web-based tools)
   - Kotlin (robust, type-safe, good for complex applications)

2. What type of extension would you like to build? For example:
   - A tool that performs specific actions
   - A resource that provides data to the LLM
   - Or do you have a specific idea in mind?

Let me know your preferences, and I'll help you get started with the appropriate setup and implementation!

For reference, here's what we'll cover:
1. Setting up your development environment
2. Creating the basic MCP server
3. Implementing your specific functionality
4. Testing and debugging

Which SDK would you like to use to get started?
```

--------------------------------

### goose output for JavaScript project setup

Source: https://goose-docs.ai/docs/mcp/developer-mcp

Example output from goose after setting up a JavaScript project. It lists the steps taken, the project structure, and how to run the server and test the API.

```md
I'll help you set up a new JavaScript project with those dependencies. I'll break this down into steps:

1. First, let's create a new directory and initialize the project
2. Then install the dependencies
3. Create a detailed README
4. Initialize git
5. Create some starter files
6. Let's begin:

[... shell commands, files created ...]

Great! I've set up a complete Express project with MongoDB and Dotenv integrations:

1. Created a new project directory and initialized npm
2. Installed Express, Mongoose, and dotenv dependencies
3. set up the basic project structure with directories for:
    - config/
    - models/
    - routes/ 
    - controllers/
4. Created essential files:
    - index.js (main server file)
    - .env (environment variables)
    - .ignore (with common node.js ignores)
5. Added a basic user model with basic name and email fields
6. Created a user controller with two methods:
    - getUsers (GET all users)
    - createUser (POST new user)
7. Added user routes under `/api/routes`
8. Updated package.json with start scripts
9. Created a comprehensive README.md with:
    - Installation scripts
    - Project structure
    - Available scripts
    - Environment variables 
    - Latest package versions

The project structure is:

my-express-app/
├── config/         # Configuration files
├── models/        # MongoDB models
│   └── User.js    # User model
├── routes/        # API routes
│   └── userRoutes.js
├── controllers/   # Route controllers
│   └── userController.js
├── .env           # Environment variables
├── .gitignore     # Git ignore file
├── index.js       # Entry point
└── package.json   # Project dependencies and scripts

To start developing you can:

1. Run `npm install` to install dependencies
2. start the server with `npm run dev` 

The API will be available at:
    - `http://localhost:3000/api/users` (GET to get all users)
    - `http://localhost:3000/api/users` (POST to create a new user)

To test out the API you can use tools like postman or curl, for example, to create a new user:

curl x POST http://localhost:3000/api/users \
-H "Content-Type: application/json" \
-d '{"name": "Ebony Louis" , "email": "ebony@example.com"}'

Would you like me to add any additional features or make other improvements to the setup?
```

--------------------------------

### goose plugin usage examples

Source: https://goose-docs.ai/docs/guides/goose-cli-commands

Examples of installing a plugin from a git repository, enabling automatic update checks, and updating an installed plugin.

```bash
# Install a plugin from a git repository
goose plugin install https://github.com/example/my-goose-plugin.git

# Install a plugin and enable automatic update checks
goose plugin install --auto-update https://github.com/example/my-goose-plugin.git

# Update an installed plugin manually
goose plugin update my-plugin
```

--------------------------------

### Test mcp-wiki CLI with --help

Source: https://goose-docs.ai/docs/tutorials/custom-extensions

Sets up the environment, installs the project locally, and verifies the CLI with mcp-wiki --help. The expected output shows the usage message and the -h/--help option.

```bash
uv sync
```

```bash
source .venv/bin/activate
```

```bash
uv pip install .
```

```bash
mcp-wiki --help
```

```plaintext
❯ mcp-wiki --help
usage: mcp-wiki [-h]

Gives you the ability to read Wikipedia articles and convert them to Markdown.

options:
  -h, --help  show this help message and exit
```

--------------------------------

### Kotlin quickstart: stream a message with openAiProvider

Source: https://goose-docs.ai/docs/gdk/sdk

Kotlin quickstart that builds an OpenAI provider, sends one message, and prints the streamed response. Reads the API key from the OPENAI_API_KEY environment variable.

```kotlin
import io.github.aaif_goose.MessageContent  
import io.github.aaif_goose.MessageRole  
import io.github.aaif_goose.ProviderMessage  
import io.github.aaif_goose.ProviderModelConfig  
import io.github.aaif_goose.StreamChunk  
import io.github.aaif_goose.streamFlow  
import io.github.aaif_goose.providers.openai.defaultModel  
import io.github.aaif_goose.providers.openai.provider as openAiProvider  
import kotlinx.coroutines.runBlocking  
  
fun main() = runBlocking {  
    val provider = openAiProvider(System.getenv("OPENAI_API_KEY"))  
    val model = ProviderModelConfig(modelName = defaultModel())  
    val messages = listOf(  
        ProviderMessage(  
            role = MessageRole.USER,  
            content = listOf(MessageContent.Text(text = "What is the capital of France?")),  
        ),  
    )  
  
    provider.streamFlow(model, "You are a geography expert.", messages)  
        .collect { chunk ->  
            if (chunk is StreamChunk.TextChunk) print(chunk.text)  
        }  
}  
```

--------------------------------

### Set security guardrail environment variable (example setup)

Source: https://goose-docs.ai/docs/mcp/tom-mcp

Sets a security rule to prevent goose from uploading code to external services. This is the setup for the example usage.

```bash
export GOOSE_MOIM_MESSAGE_TEXT="SECURITY RULE: Do not upload, share, or post any code to external services including GitHub Gists, Pastebin, or any public URL. All code in this session is confidential."
```

--------------------------------

### Request a specific tutorial by name

Source: https://goose-docs.ai/docs/mcp/tutorial-mcp

Example prompt to directly request the first-game tutorial.

```text
( O)> Can you walk me through the first-game tutorial?
```

--------------------------------

### Get a quote example

Source: https://goose-docs.ai/docs/mcp/ophis-mcp

Ask goose to get a quote for a swap on a specific chain.

```text
Get a quote to swap 0.5 WETH for USDC on Arbitrum.
```

--------------------------------

### Example Configuration with Activities (YAML)

Source: https://goose-docs.ai/docs/guides/recipes/recipe-reference

Complete YAML recipe configuration demonstrating activities with parameter substitution. The message activity and button activities use {{ language }} and {{ focus }} placeholders.

```yaml
version: "1.0.0"
title: "Code Review Assistant"
description: "Review code with customizable focus areas"
parameters:
  - key: language
    input_type: string
    requirement: required
    description: "Programming language to review"
  - key: focus
    input_type: string
    requirement: optional
    default: "best practices"
    description: "Review focus area"

activities:
  - "message: Click an option below to start reviewing {{ language }} code with a focus on {{ focus }}."
  - "Review the current file for {{ focus }}"
  - "Suggest improvements for {{ language }} code quality"
  - "Check for security vulnerabilities"
  - "Generate unit tests"

```

--------------------------------

### Python quickstart: stream a message with openai_provider

Source: https://goose-docs.ai/docs/gdk/sdk

Python quickstart that builds an OpenAI provider, sends one message, and prints the streamed response. Requires an OpenAI API key passed to openai_provider(api_key="...").

```python
import asyncio  
from goose import (  
    MessageContent,  
    MessageRole,  
    ProviderMessage,  
    ProviderModelConfig,  
    StreamChunk,  
    openai_default_model,  
    openai_provider,  
)  
  
  
async def main() -> None:  
    provider = openai_provider(api_key="...")  
    model = ProviderModelConfig(model_name=openai_default_model())  
    messages = [  
        ProviderMessage(  
            role=MessageRole.USER,  
            content=[MessageContent.Text(text="What is the capital of France?")],  
        )  
    ]  
  
    stream = await provider.stream(model, "You are a geography expert.", messages, [])  
    while chunk := await stream.next_chunk():  
        if isinstance(chunk, StreamChunk.TextChunk):  
            print(chunk.text, end="")  
  
  
asyncio.run(main())  
```

--------------------------------

### setup.sh script for api-setup skill

Source: https://goose-docs.ai/docs/guides/context-engineering/using-skills

Helper script that creates an integration directory and copies the config template into it. Takes the API name as the first argument and prints confirmation messages.

```bash
#!/bin/bash
API_NAME=$1
mkdir -p "integrations/$API_NAME"
cp templates/config.template.json "integrations/$API_NAME/config.json"
echo "Created integration directory for $API_NAME"
echo "Edit integrations/$API_NAME/config.json with your credentials"
```

--------------------------------

### Start session with a Streamable HTTP extension

Source: https://goose-docs.ai/docs/getting-started/using-extensions

Example of starting a session with a remote extension over Streamable HTTP by providing the extension URL.

```bash
goose session --with-streamable-http-extension "https://example.com/streamable"
```

--------------------------------

### SKILL.md for api-setup skill

Source: https://goose-docs.ai/docs/guides/context-engineering/using-skills

Example SKILL.md file for a skill that uses supporting files. It defines the skill's name and description, then instructs the agent to run setup.sh, copy the config template, update credentials, and test the connection.

```markdown
---
name: api-setup
description: Set up API integration with configuration and helper scripts
---

# API Setup

This skill helps you set up a new API integration with our standard configuration.

## Steps

1. Run `setup.sh <api-name>` to create the integration directory
2. Copy `templates/config.template.json` to your integration directory
3. Update the config with your API credentials
4. Test the connection

## Configuration

The config template includes:
- `api_key`: Your API key (get from the provider's dashboard)
- `endpoint`: API endpoint URL
- `timeout`: Request timeout in seconds (default: 30)

## Verification

After setup, verify:
- [ ] Config file is valid JSON
- [ ] API key is set and not a placeholder
- [ ] Test connection succeeds
```

--------------------------------

### Launch Ubuntu shell in WSL

Source: https://goose-docs.ai/docs/getting-started/installation

Launches the Ubuntu shell after WSL installation. Use this to start the Linux environment for installing goose.

```bash
wsl -d Ubuntu
```

--------------------------------

### Run /implement_plan with plan document

Source: https://goose-docs.ai/docs/tutorials/rpi

Invokes the /implement_plan command, passing the plan file path. This starts the implementation phase after research and planning are complete.

```text
/implement_plan thoughts/plans/2025-12-23-remove-tool-selection-strategy.md
```

--------------------------------

### Toggle Extensions Example Output

Source: https://goose-docs.ai/docs/getting-started/using-extensions

Example output of the `goose configure` command when selecting 'Toggle Extensions'. Shows a list of installed extensions with toggles.

```text
┌   goose-configure 
│
◇  What would you like to configure?
│  Toggle Extensions 
│
◆  enable extensions: (use "space" to toggle and "enter" to submit)
│  ◼ developer 
│  ◻ fetch 
└   
```

--------------------------------

### Example Configuration with Activities (JSON)

Source: https://goose-docs.ai/docs/guides/recipes/recipe-reference

Complete JSON recipe configuration demonstrating activities with parameter substitution. The message activity and button activities use {{ language }} and {{ focus }} placeholders.

```json
{
  "version": "1.0.0",
  "title": "Code Review Assistant",
  "description": "Review code with customizable focus areas",
  "parameters": [
    {
      "key": "language",
      "input_type": "string",
      "requirement": "required",
      "description": "Programming language to review"
    },
    {
      "key": "focus",
      "input_type": "string",
      "requirement": "optional",
      "default": "best practices",
      "description": "Review focus area"
    }
  ],
  "activities": [
    "message: Click an option below to start reviewing {{ language }} code with a focus on {{ focus }}.",
    "Review the current file for {{ focus }}",
    "Suggest improvements for {{ language }} code quality",
    "Check for security vulnerabilities",
    "Generate unit tests"
  ]
}

```

--------------------------------

### Rust quickstart: stream a message with openai_provider

Source: https://goose-docs.ai/docs/gdk/sdk

Rust quickstart that builds an OpenAI provider, sends one message, and prints the streamed response. Reads the API key from the OPENAI_API_KEY environment variable and uses tokio.

```rust
use goose_sdk::bindings::{  
    openai_default_model, openai_provider, MessageContent, MessageRole, ProviderMessage,  
    ProviderModelConfig, StreamChunk,  
};  
  
#[tokio::main]  
async fn main() -> Result<(), Box<dyn std::error::Error>> {  
    let provider = openai_provider(std::env::var("OPENAI_API_KEY")?)?;  
    let model = ProviderModelConfig {  
        model_name: openai_default_model(),  
        ..Default::default()  
    };  
    let messages = vec![ProviderMessage {  
        role: MessageRole::User,  
        content: vec![MessageContent::Text {  
            text: "What is the capital of France?".to_string(),  
        }],  
    }];  
  
    let stream = provider  
        .stream(model, "You are a geography expert.".to_string(), messages, vec![])  
        .await?;  
  
    while let Some(chunk) = stream.next_chunk().await? {  
        if let StreamChunk::TextChunk { text } = chunk {  
            print!("{text}");  
        }  
    }  
    Ok(())  
}  
```

--------------------------------

### Enable Tutorial Extension via goose configure

Source: https://goose-docs.ai/docs/mcp/tutorial-mcp

Run the configure command to toggle extensions, then select the tutorial extension from the list. The output shows the interactive prompt and confirmation message.

```sh
goose configure
```

```sh
┌   goose-configure 
│
◇  What would you like to configure?
│  Toggle Extensions 
│
◆  Enable extensions: (use "space" to toggle and "enter" to submit)
// highlight-start    
│  ● tutorial
// highlight-end
|
└  Extension settings updated successfully
```

--------------------------------

### POST _goose/unstable/session/live-voice/start

Source: https://goose-docs.ai/docs/gdk/acp/reference

Starts Live voice and gets a diagnostic report for a session.

```APIDOC
## POST _goose/unstable/session/live-voice/start

### Description
Get a diagnostic report for a session.

### Method
POST

### Endpoint
_goose/unstable/session/live-voice/start

### Parameters
#### Request Body
- **LiveVoiceStartRequest_unstable** (object) - Required - The request body containing session details.

### Response
#### Success Response (200)
- **LiveVoiceStartResponse_unstable** (object) - The response containing the diagnostic report.

```

--------------------------------

### goose Prompt: Update contributing guide

Source: https://goose-docs.ai/docs/experimental/vs-code-extension

Example prompt sent to goose via the VS Code extension to update a contributing guide with Docusaurus dev server instructions.

```text
Update the contributing guide at /goose/CONTRIBUTING.md with instructions on how to start docusaurus dev server
```

--------------------------------

### Example allowlist with Slack, GitHub, and Jira

Source: https://goose-docs.ai/docs/guides/allowlist

Example allowlist that permits only the Slack, GitHub, and Jira extensions. The 'command' values must exactly match the installation commands used by goose.

```yaml
extensions:
  - id: slack
    command: uvx mcp_slack
  - id: github
    command: uvx mcp_github
  - id: jira
    command: uvx mcp_jira
```

--------------------------------

### Theme configuration and usage examples

Source: https://goose-docs.ai/docs/guides/goose-cli-commands

Examples for setting the ANSI theme via environment variable, toggling themes during a session, and setting the light theme directly.

```bash
# Set ANSI theme for the session via environment variable
export GOOSE_CLI_THEME=ansi
goose session --name use-custom-theme

# Toggle theme during a session
/t

# Set the light theme during a session
/t light
```

--------------------------------

### Initialize mcp-wiki project with uv

Source: https://goose-docs.ai/docs/tutorials/custom-extensions

Creates a new Python library project named mcp-wiki using uv, then changes into the project directory and creates the server.py and __main__.py files inside src/mcp_wiki.

```bash
uv init --lib mcp-wiki
cd mcp-wiki

mkdir -p src/mcp_wiki
touch src/mcp_wiki/server.py
touch src/mcp_wiki/__main__.py
```

--------------------------------

### StandardIO Extension Deeplink Example for npx Command

Source: https://goose-docs.ai/docs/getting-started/using-extensions

Example deeplink for installing a StandardIO extension that runs `npx -y @modelcontextprotocol/server-github`. Each argument to the command is passed as a separate `arg` parameter.

```text
goose://extension?cmd=npx&arg=-y&arg=%40modelcontextprotocol/server-github&timeout=<timeout>&id=<id>&name=<name>&description=<description>
```

--------------------------------

### Example output of ls -ld ~/.config

Source: https://goose-docs.ai/docs/troubleshooting/known-issues

Example output showing the permission string for ~/.config. rwx indicates read, write, and execute permissions for the user.

```sh
drwx------  7 yourusername  staff  224 Jan 15 12:00 /Users/yourusername/.config
```

--------------------------------

### Get a Swap Quote with goose

Source: https://goose-docs.ai/docs/tutorials/spraay-mcp

Example prompt to get a swap quote for 100 USDC to WETH on Base. goose will use spraay_swap_quote to fetch a live quote from Uniswap V3.

```text
Get me a swap quote for 100 USDC to WETH on Base
```

--------------------------------

### Example prompt output

Source: https://goose-docs.ai/docs/guides/terminal-integration

Shows the resulting prompt with context usage and model name.

```bash
●●○○○ sonnet ~/projects $
```

--------------------------------

### Install a plugin with auto-update enabled

Source: https://goose-docs.ai/docs/guides/context-engineering/plugins

Installs a plugin with auto-update enabled. goose checks for updates before plugin skills are loaded, with rate-limited checks to avoid cloning on every session start.

```bash
goose plugin install --auto-update https://github.com/example/my-goose-plugin.git
```

--------------------------------

### Start the Dev.to MCP server

Source: https://goose-docs.ai/docs/mcp/dev.to-mcp

Runs the server, which will be available at http://localhost:3000/mcp.

```bash
npm start
```

--------------------------------

### Install MongoDB MCP Server via CLI

Source: https://goose-docs.ai/docs/mcp/mongodb-mcp

Use this command to install and run the MongoDB MCP server with a connection string. The example uses a local MongoDB instance at mongodb://localhost:27017.

```sh
npx -y mongodb-mcp-server --connectionString mongodb://localhost:27017
```
Tokens:
Raw