# goose User Guide

**goose** is a free, open source, on-machine AI agent that automates engineering and everyday computer tasks. Unlike a chat window that only talks, goose actually *does the work*: it runs commands, edits files, drives browsers, queries databases, and orchestrates tools on your behalf — all under your direction, on your own machine, using the LLM you choose.

goose is built on the **Model Context Protocol (MCP)**, so it connects to a large ecosystem of "extensions" (tools) that give it new capabilities. It ships in two interchangeable forms — a **Desktop app** and a **command-line interface (CLI)** — that share the same configuration, the same extensions, and the same underlying agent engine.

> [!NOTE]
> goose is **model-agnostic**. It works with 40+ LLM providers — hosted (Anthropic, OpenAI, Google Gemini, Groq, Databricks, Amazon Bedrock, and many more) and fully local (Ollama, LM Studio, llama.cpp). You supply the model; goose supplies the agent.

This guide covers everything you need to install goose, connect a model, run sessions, add extensions, automate work with recipes and schedules, and troubleshoot common problems.

---

## Table of Contents

1. [What goose Can Do](#1-what-goose-can-do)
2. [Quick Start](#2-quick-start)
3. [Installation](#3-installation)
4. [Connecting an LLM Provider](#4-connecting-an-llm-provider)
5. [Running goose](#5-running-goose)
6. [How goose Works (the Agent Loop)](#6-how-goose-works-the-agent-loop)
7. [Controlling Autonomy: goose Modes & Permissions](#7-controlling-autonomy-goose-modes--permissions)
8. [CLI Command Reference](#8-cli-command-reference)
9. [Working with Extensions (MCP)](#9-working-with-extensions-mcp)
10. [Recipes: Reusable Agents](#10-recipes-reusable-agents)
11. [Subagents & Running Tasks](#11-subagents--running-tasks)
12. [Scheduling Jobs](#12-scheduling-jobs)
13. [Terminal Integration & TUI](#13-terminal-integration--tui)
14. [Agent Client Protocol (ACP)](#14-agent-client-protocol-acp)
15. [Local & Offline Models](#15-local--offline-models)
16. [Managing Sessions](#16-managing-sessions)
17. [Code Review with goose](#17-code-review-with-goose)
18. [Gateways & Plugins](#18-gateways--plugins)
19. [Tips & Best Practices](#19-tips--best-practices)
20. [Troubleshooting](#20-troubleshooting)
21. [Frequently Asked Questions](#21-frequently-asked-questions)
22. [Reference](#22-reference)

---

## 1. What goose Can Do

goose is a general-purpose agent. The specific things it can do depend on which **extensions** are enabled, but out of the box (with the built-in **Developer** extension) it can:

- **Write, edit, and refactor code** across an entire repository, running your build and tests as it goes.
- **Execute shell commands** and interpret their output.
- **Read, create, and modify files** anywhere you point it.
- **Debug and fix CI failures**, run migrations, and scaffold projects.
- **Review your local diff** for bugs before you commit (`goose review`).
- **Automate repetitive tasks** with reusable **recipes** and **scheduled jobs**.
- **Delegate work to subagents** that run in parallel.

Adding extensions extends this to web scraping, browser automation (Playwright, Puppeteer), databases (PostgreSQL, MongoDB), cloud platforms (Cloudflare, Vercel, Netlify, Supabase), design tools (Figma, Blender), and hundreds of other systems.

### Core capabilities at a glance

| Capability | What it means for you |
|---|---|
| **Two interfaces** | A polished Desktop app and a scriptable CLI — same config, same extensions |
| **40+ LLM providers** | Bring your own model; switch any time without re-learning goose |
| **MCP extensions** | Connect goose to tools you already use; build your own |
| **Recipes** | Package an agent (prompt + extensions + parameters) into a shareable file |
| **Subagents** | Run multiple agents concurrently on sub-tasks |
| **Scheduling** | Run recipes on a cron schedule, unattended |
| **Local-first** | Run entirely offline with a local model — your data never leaves your machine |
| **ACP** | Use goose inside editors (Zed, JetBrains), or delegate to Claude Code / Codex |

> [!TIP]
> goose is **autonomous by default**. With the Developer extension enabled, it can run commands and modify files *without asking first*. This is powerful but means you should run it on work you can review (use version control). See [Controlling Autonomy](#7-controlling-autonomy-goose-modes--permissions) to change this behavior.

---

## 2. Quick Start

The fastest path from zero to a working agent:

=== "goose CLI"

    ```bash
    # 1. Install the CLI (macOS / Linux / Git Bash on Windows)
    curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

    # 2. Configure a provider (interactive)
    goose configure

    # 3. Start a session in your project directory
    cd ~/my-project
    goose session
    ```

    Then just type what you want:

    ```text
    > Add input validation to the signup form and run the tests
    ```

=== "goose Desktop"

    1. Download goose Desktop for your platform (see [Installation](#3-installation)).
    2. Launch the app. On the welcome screen, choose how to connect a model — the easiest is **Agent Router by Tetrate** (includes free credits) or **Quick Setup with API Key**.
    3. Type your task into the input box and press Enter.

> [!NOTE]
> On first run, goose walks you through provider setup automatically — you don't need to edit any files. The CLI enters configuration mode; the Desktop shows a welcome screen.

---

## 3. Installation

goose offers a **Desktop** app and a **CLI** for macOS, Linux, and Windows. They share configuration, so you can install both and switch freely.

### 3.1 macOS

=== "goose Desktop"

    **Option 1 — Download:** Download the macOS build from the goose website and unzip it, then run the executable to launch the app.

    **Option 2 — Homebrew** (handles updates for you):

    ```bash
    brew install --cask block-goose
    ```

    > [!IMPORTANT]
    > On Apple Silicon (M3), if the Desktop app launches with **no window**, ensure your `~/.config` directory has read/write access — goose needs it to create its log files. See [macOS Permission Issues](#error-goose-desktop-shows-no-window-on-launch-macos).

=== "goose CLI"

    **Option 1 — Install script:**

    ```bash
    curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
    ```

    To skip the interactive configuration step (e.g. for scripted installs):

    ```bash
    curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash
    ```

    **Option 2 — Homebrew:**

    ```bash
    brew install block-goose-cli
    ```

### 3.2 Linux

=== "goose Desktop"

    Download the build for your distribution. For Debian/Ubuntu:

    ```bash
    sudo dpkg -i goose_<version>.deb
    ```

    Then launch goose from your application menu.

=== "goose CLI"

    ```bash
    curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
    ```

    Add `CONFIGURE=false` before `bash` to skip interactive setup.

### 3.3 Windows

goose runs **natively** on Windows. You need one of:

- **Git Bash** (recommended) — comes with [Git for Windows](https://git-scm.com/download/win)
- **MSYS2** — from [msys2.org](https://www.msys2.org/)
- **PowerShell** — built into Windows 10/11

=== "goose Desktop"

    Download the Windows build, unzip it, and run the executable.

=== "Git Bash / MSYS2"

    ```bash
    curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
    ```

=== "PowerShell"

    ```powershell
    Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
    .\download_cli.ps1
    ```

> [!WARNING]
> **Windows PATH:** If you see a warning that goose is not on your PATH, add `~/.local/bin` (Git Bash) or `%USERPROFILE%\.local\bin` (PowerShell) to your PATH and restart your shell. Full steps are in the in-installer notes.

> [!TIP]
> Prefer a Linux-like environment? You can install the CLI under **WSL** (`wsl --install`, then run the install script inside Ubuntu). If extraction fails, install `bzip2` first: `sudo apt update && sudo apt install bzip2 -y`.

### 3.4 Keeping goose Updated

Keep goose current to get new providers, extensions, and fixes:

=== "goose CLI"

    ```bash
    goose update                 # latest stable
    goose update --canary        # latest pre-release
    goose update --reconfigure   # update and re-run configuration
    ```

=== "goose Desktop"

    The Desktop app updates itself. You can also reinstall via Homebrew (`brew upgrade --cask block-goose`).

### 3.5 Verifying Your Install

```bash
goose --version
goose info -v          # show full config, including config.yaml
goose info --check     # test the provider connection
goose doctor           # check that your setup is working end-to-end
```

```text
$ goose doctor
✓ Configuration file found
✓ Provider configured (anthropic)
✓ Provider connection OK
✓ Developer extension enabled
```

---

## 4. Connecting an LLM Provider

goose needs an LLM to think. You connect a **provider** (the service that hosts the model) and pick a **model**.

### 4.1 First-Time Setup

=== "goose Desktop"

    On the welcome screen you can choose:

    - **Quick Setup with API Key** — paste any provider's API key; goose auto-detects the provider.
    - **ChatGPT Subscription** — sign in with an active ChatGPT Plus/Pro subscription (browser OAuth).
    - **Agent Router by Tetrate** *(recommended for new users)* — browser sign-in; includes built-in rate limiting and automatic failover.
    - **OpenRouter** — browser sign-in to a unified gateway.
    - **Other Providers** — pick any supported provider and enter its credentials.

=== "goose CLI"

    The CLI enters configuration mode automatically on first run, or any time via:

    ```bash
    goose configure
    ```

    A typical flow:

    ```text
    ┌   goose-configure
    │
    ◇  What would you like to configure?
    │  Configure Providers
    │
    ◇  Which model provider should we use?
    │  Anthropic
    │
    ◇  Provider Anthropic requires ANTHROPIC_API_KEY, please enter a value
    │  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
    │
    ◇  Select a model:
    │  claude-sonnet-4-5 (default)
    │
    └  Configuration saved successfully
    ```

> [!IMPORTANT]
> **Free credits:** The first time you authenticate with **Tetrate Agent Router** through goose, you receive **$10 in free credits** (for new and existing Tetrate users).

### 4.2 Supported Providers

goose supports a large catalogue of providers. Configure any of them with `goose configure` (CLI) or **Settings → Models** (Desktop).

| Provider | Notes | Key parameters |
|---|---|---|
| **Anthropic** | Claude models | `ANTHROPIC_API_KEY`, `ANTHROPIC_HOST` (opt.) |
| **OpenAI** | gpt-4o, o1, plus OpenAI-compatible endpoints. *o1-mini/o1-preview unsupported (no tool calling).* | `OPENAI_API_KEY`, `OPENAI_HOST` (opt.), `OPENAI_ORGANIZATION` (opt.) |
| **Google Gemini** | Multimodal; free tier available | `GOOGLE_API_KEY` |
| **Amazon Bedrock** | Claude, Jurassic-2, others. *AWS env vars must be set in advance.* | `AWS_PROFILE` or `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_REGION` |
| **Amazon SageMaker TGI** | TGI models on SageMaker endpoints | `SAGEMAKER_ENDPOINT_NAME`, `AWS_REGION` (opt.) |
| **Azure OpenAI** | Azure-hosted GPT models | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT_NAME`, `AZURE_OPENAI_API_KEY` (opt.) |
| **Databricks** | Unified data + AI platform | `DATABRICKS_HOST`, `DATABRICKS_TOKEN` |
| **GCP Vertex AI** | Gemini + Claude on Google Cloud | `GCP_PROJECT_ID`, `GCP_LOCATION` |
| **GitHub Copilot** | OpenAI/Anthropic/Google via Copilot; device-flow auth | Copilot-enabled GitHub account |
| **ChatGPT Codex** | GPT-5 Codex; requires ChatGPT Plus/Pro; browser OAuth | — |
| **Groq** | Very fast inference; free tier | `GROQ_API_KEY` |
| **OpenRouter** | Unified gateway with rate-limit management | `OPENROUTER_API_KEY` |
| **Tetrate Agent Router** | Multi-model gateway with failover; PKCE auth | `TETRATE_API_KEY`, `TETRATE_HOST` (opt.) |
| **Mistral AI** | General + Codestral + Pixtral | `MISTRAL_API_KEY` |
| **xAI** | Grok models | `XAI_API_KEY` |
| **Perplexity** | Chat with real-time web grounding | `PERPLEXITY_API_KEY` |
| **Cerebras** | Wafer-scale fast inference | `CEREBRAS_API_KEY` |
| **Snowflake** | Cortex models incl. Claude | `SNOWFLAKE_HOST`, `SNOWFLAKE_TOKEN` |
| **VMware Tanzu** | Enterprise-managed LLM access | `TANZU_AI_API_KEY`, `TANZU_AI_ENDPOINT` |
| **LiteLLM** | LiteLLM proxy; auto prompt caching | `LITELLM_HOST`, `LITELLM_API_KEY` (opt.) |
| **Ollama / Ollama Cloud** | Local & hosted open models | `OLLAMA_HOST` / `OLLAMA_CLOUD_API_KEY` |
| **LM Studio** | Local OpenAI-compatible server | none (default `localhost:1234`) |
| **Docker Model Runner** | Local models in Docker Desktop/CE | `OPENAI_HOST`, `OPENAI_BASE_PATH` |
| **NEAR AI Cloud** | TEE-backed private inference | `NEARAI_API_KEY` |
| **Novita AI / Avian / Venice / Scaleway / OVHcloud / SaladCloud / Routstr / FuturMix** | OpenAI-compatible aggregators & open-model hosts | provider-specific key |

> [!NOTE]
> This table lists the most common providers. goose also supports **CLI providers** (e.g. `cursor-agent`, which uses your Cursor subscription) and **ACP providers** (`claude-acp`, `codex-acp` — see [Agent Client Protocol](#14-agent-client-protocol-acp)). For the full live list, run `goose configure` and browse the provider menu.

> [!TIP]
> **Prompt caching for Claude:** goose automatically enables Anthropic prompt caching when using Claude via Anthropic, Bedrock, Databricks, OpenRouter, and LiteLLM — reducing cost on long conversations.

### 4.3 Choosing & Switching Models

After picking a provider, choose a model. Some providers fetch their model list live; others let you type a model name.

**Per-session override (CLI):** Don't want to change your default? Set the model for one run:

```bash
goose run --provider anthropic --model claude-sonnet-4-0 -t "summarize this repo"
```

**Change your default:**

=== "goose Desktop"

    Settings → **Models** → *Switch models* (or *Configure providers* to change credentials). Click the model name in the bottom bar for a fast *Change Model* shortcut.

=== "goose CLI"

    ```bash
    goose configure   # → Configure Providers
    ```

    > [!NOTE]
    > `goose configure` cannot enter *custom* model names. To use a model not in the provider's list, use goose Desktop or set `GOOSE_MODEL` directly in your [`config.yaml`](#226-key-file-locations).

### 4.4 Custom & OpenAI-Compatible Endpoints

The built-in **OpenAI** provider works with any OpenAI-compatible endpoint — self-hosted vLLM/KServe, corporate proxies, or enterprise OpenAI:

```bash
export OPENAI_HOST=https://your-vllm-endpoint.internal
export OPENAI_API_KEY=your-internal-api-key
```

For more flexibility, create a **Custom Provider** (Settings → Models → *Add Custom Provider*, or `goose configure → Custom Providers`). Custom providers support OpenAI/Anthropic/Ollama-compatible APIs, a saved model list, custom display names, custom headers, and per-provider keys. They're stored as JSON in your `custom_providers/` config directory and can be checked into a repo for sharing.

---

## 5. Running goose

### 5.1 Starting a Session

=== "goose Desktop"

    Open the app and type your task into the input field. goose starts working immediately. You can run multiple sessions and let goose spin up multiple agents for concurrent tasks.

=== "goose CLI"

    Navigate to the directory you want goose to work in, then:

    ```bash
    goose session            # start a new interactive session
    goose                    # same thing — bare `goose` opens a session
    ```

### 5.2 Interactive Session Basics

Inside a session you converse naturally. goose plans, calls tools, shows you its work, and reports back. Useful in-session controls (CLI):

| Action | How |
|---|---|
| Interrupt / stop | Press `Ctrl+C` (hold to fully cancel) |
| Insert a newline | `Ctrl+J` (customizable via `GOOSE_CLI_NEWLINE_KEY`) |
| Add an extension mid-session | `/extension npx -y @modelcontextprotocol/server-memory` |
| Add a built-in mid-session | `/builtin developer` |
| Toggle full/debug output | `/r` (toggles `GOOSE_DEBUG`) |

### 5.3 One-Shot & Headless Runs

For automation, CI, or piping, use `goose run` instead of an interactive session:

```bash
# Run a single instruction and exit
goose run -t "bump the version in package.json to 2.0.0"

# Run instructions from a file
goose run -i tasks.md

# Read instructions from stdin
echo "list the largest files in this repo" | goose run -i -

# Run without saving a session file (clean automation)
goose run --no-session -t "lint and report"

# Machine-readable output for scripts
goose run -t "count TODOs" --output-format json
```

`--output-format` accepts `text` (default), `json`, or `stream-json`.

> [!TIP]
> Add `-s` / `--interactive` to `goose run` to *continue* in an interactive session after the initial input is processed — handy for kicking off a task non-interactively and then taking over.

---

## 6. How goose Works (the Agent Loop)

Understanding the loop helps you steer goose effectively. goose has three parts:

- **Interface** — the Desktop app or CLI you type into.
- **Agent** — the core loop that talks to the model and runs tools.
- **Extensions** — MCP servers that expose **tools** (run a command, edit a file, search Drive, etc.).

A single turn works like this:

```text
   You ──▶ (1) Request
            │
            ▼
   (2) Agent sends your request + available tools to the LLM provider
            │
            ▼
   (3) LLM replies — possibly with a tool call (JSON)
            │
            ▼
   (4) Agent EXECUTES the tool and collects the result
            │
            ▼
   (5) Result is fed back to the model ──┐  (repeat tools as needed)
            │                            │
            ▼                            │
   (6) Context revision (drop stale data, manage tokens)
            │                            │
            ▼                            │
   (7) Model's final answer ◀────────────┘
            │
            ▼
   You ◀── Response  (loop restarts on your next message)
```

Two design choices are worth knowing as a user:

- **Errors don't break the flow.** Invalid JSON, a missing tool, or a failed command are sent *back to the model* as tool results so it can correct course and continue — rather than crashing the session.
- **Context revision manages cost.** goose summarizes with smaller/faster models, deletes old or irrelevant content, prefers find-and-replace over rewriting whole files, and summarizes verbose command output. This keeps long sessions affordable. You can tune it (see [Reference → Session variables](#223-session--context-environment-variables)).

---

## 7. Controlling Autonomy: goose Modes & Permissions

By default goose runs autonomously — with the Developer extension it can execute commands and edit files **without asking**. The **`GOOSE_MODE`** setting controls this:

| Mode | Behavior |
|---|---|
| `auto` | Run all tool calls automatically (most autonomous) |
| `approve` | Ask for your approval before every tool call |
| `smart_approve` | *(default)* Approve low-risk actions automatically; prompt for risky ones |
| `chat` | Chat only — goose does **not** execute tools (safest) |

Set it for a session or globally:

```bash
export GOOSE_MODE=approve      # prompt before each action
export GOOSE_MODE=chat         # disable tool execution entirely
```

> [!CAUTION]
> Because goose can modify files and run commands, **use version control**. Stage your own edits; leave goose's edits unstaged until you've reviewed them, and consider committing goose's changes separately so they're easy to revert. See [goose Edits Files](#good-practice-protect-your-work).

goose also supports finer-grained controls — per-tool permissions and `.gooseignore` files to keep goose away from sensitive paths. These are covered in the [Admin Guide](aaif-goose__goose__AdminGuide.md).

---

## 8. CLI Command Reference

`goose <command> [options]`. Running `goose` with no command opens an interactive session. Many commands have short aliases (shown below).

### 8.1 Command Summary

| Command | Alias | Purpose |
|---|---|---|
| `session` | `s` | Start or resume an interactive chat session |
| `run` | | Execute instructions/recipe from a file, text, or stdin |
| `configure` | | Configure providers, extensions, and settings (interactive) |
| `info` | | Show goose configuration info (`-v` verbose, `--check` test provider) |
| `doctor` | | Check that your setup works |
| `update` | | Update the goose CLI (`--canary`, `--reconfigure`) |
| `recipe` | | Recipe utilities (`validate`, `deeplink`, `open`, `list`) |
| `run --recipe` | | Run a recipe (see [Recipes](#10-recipes-reusable-agents)) |
| `schedule` | `sched` | Manage scheduled jobs (cron) |
| `mcp` | | Run one of the MCP servers bundled with goose |
| `acp` | | Run goose as an ACP agent server over stdio |
| `serve` | | Run goose as an ACP server over HTTP/WebSocket |
| `project` | `p` | Open the last project directory |
| `projects` | `ps` | List recent project directories |
| `skills` | | Skill utilities (`list`) |
| `plugin` | | Manage plugins (`install`, `update`) |
| `gateway` | `gw` | Manage platform gateways (e.g. Telegram) |
| `term` | | Terminal-integrated session (one session per terminal) |
| `tui` | | Launch the terminal UI |
| `local-models` | `lm` | Manage local inference models |
| `review` | | Review your current git diff using goose |
| `completion` | | Generate shell completion scripts |

### 8.2 `session` — Interactive Chat

```bash
goose session                          # new session
goose session --name project-x         # named session
goose session -r                       # resume the most recent session
goose session -r --name project-x      # resume a specific named session
goose session -r --history             # resume and show prior messages
goose session -r --fork                # fork a session (copy its history into a new one)
```

`session` subcommands manage your session history:

```bash
goose session list                     # list all sessions (--format json, --ascending, --limit N)
goose session remove --name old-thing  # remove a session (or -r <regex>; interactive if no args)
goose session export --name demo -o demo.md       # export to Markdown (also json, yaml)
goose session import path/to/transcript.jsonl     # import Claude Code / Codex / Pi transcripts
goose session diagnostics --name demo  # generate a diagnostics zip for support
```

Session start flags (shared with `run`):

| Flag | Purpose |
|---|---|
| `-n, --name <NAME>` | Name the session |
| `--session-id <ID>` | Target a specific session id (with `--resume`) |
| `--debug` | Full, untruncated tool output |
| `--max-turns <N>` | Cap turns without user input (default 1000) |
| `--max-tool-repetitions <N>` | Limit identical consecutive tool calls (loop guard) |
| `--container <ID>` | Run extensions inside a Docker container |
| `--with-builtin <name[,name]>` | Enable built-in extensions for this session |
| `--with-extension "<cmd>"` | Add a stdio MCP extension for this session |
| `--with-streamable-http-extension "<url>"` | Add a remote (Streamable HTTP) extension |
| `--no-profile` | Ignore your default extensions; use only the ones specified |

### 8.3 `run` — Headless / Scripted

```bash
goose run -t "<text>"                   # run inline text
goose run -i <file>                     # run instructions from a file ( - for stdin)
goose run --recipe <name|path>          # run a recipe
goose run --recipe r.yaml --params k=v  # pass recipe parameters (repeatable)
goose run --recipe r.yaml --explain     # show a recipe's title/description/params
goose run --recipe r.yaml --render-recipe  # print the rendered recipe without running
goose run --system "<text>"             # add a system prompt
goose run --sub-recipe sub.yaml         # include sub-recipes (repeatable)
```

Additional `run` flags: `-q/--quiet` (only print the model response), `--output-format <text|json|stream-json>`, `--provider`, `--model`, `-s/--interactive`, `--no-session`, `-r/--resume`.

### 8.4 Other Common Commands

```bash
# Recipes
goose recipe validate my-recipe.yaml
goose recipe list --verbose
goose recipe deeplink my-recipe.yaml -p name=alice
goose recipe open my-recipe.yaml          # open in goose Desktop

# Code review (see §17)
goose review main...HEAD

# Skills & plugins
goose skills list
goose plugin install https://github.com/owner/some-goose-plugin
goose plugin update some-goose-plugin

# Shell completion
goose completion zsh > ~/.goose-completion.zsh
```

> [!TIP]
> Run `goose <command> --help` for the exhaustive, always-current flag list for any command — it's generated directly from the CLI definitions.

---

## 9. Working with Extensions (MCP)

**Extensions** are how goose gains capabilities. They are [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers that expose **tools** — discrete actions like "run a shell command", "search a Google Drive", or "query Postgres". You can use goose's bundled extensions, install any third-party MCP server, or build your own.

### 9.1 Built-in Extensions

goose ships with several extensions you can use immediately:

| Extension | Default | What it does |
|---|---|---|
| **Developer** | ✅ enabled | General software-development tools: shell, file edit/create, code editing. The workhorse. |
| **Computer Controller** | off | General computer control: web scraping, file caching, automations |
| **Memory** | off | Teaches goose to remember your preferences across sessions |
| **Tutorial** | off | Interactive in-product tutorials |
| **Auto Visualiser** | off | Generates graphical data visualizations inline in conversations |

goose also includes **platform extensions** — always-available global features:

| Platform extension | Default | What it does |
|---|---|---|
| **Extension Manager** | ✅ | Discover, enable, and disable extensions dynamically mid-session |
| **Summon** | ✅ | Load skills/recipes and delegate tasks to subagents |
| **Todo** | ✅ | Manage task lists and track progress across sessions |
| **Apps** | off | Create, manage, and launch custom HTML apps in standalone windows |
| **Chat Recall** | off | Search conversation content across all your session history |
| **Code Mode** | off | Execute JavaScript for tool discovery and tool calling |
| **Top of Mind** | off | Inject persistent instructions into goose's working memory every turn |

> [!WARNING]
> The **Developer** extension combined with autonomous mode lets goose execute commands and modify files without approval. To constrain this, configure your [goose mode](#7-controlling-autonomy-goose-modes--permissions), tool permissions, and `.gooseignore` files.

### 9.2 The Extensions Directory

Beyond the built-ins, goose connects to **any** MCP server. The official **[extensions directory](https://www.pulsemcp.com/servers)** lists hundreds. A representative sample of what's available:

| Category | Examples |
|---|---|
| **Dev & code** | GitHub, JetBrains, VS Code, Chrome DevTools, Repomix, Code Mode |
| **Browser & web** | Playwright, Puppeteer, Selenium, Browserbase, Firecrawl, Fetch, Tavily, Exa, Brave |
| **Data & DB** | PostgreSQL, MongoDB, Neon, Supabase, DataHub, OpenMetadata, Knowledge Graph, Cognee |
| **Cloud & deploy** | Cloudflare, Vercel, Netlify, Apify |
| **Design & media** | Figma, Blender, Excalidraw, Cloudinary, ElevenLabs, Nano Banana, Speech |
| **Productivity** | Asana, Google Drive, Google Maps, Reddit, YouTube Transcript, PDF, Memory, Todo |
| **Commerce** | Square, Cash App, Alby |

> [!NOTE]
> Each directory extension has a step-by-step tutorial in the goose docs. There are 100+ documented extensions — browse the directory and the tutorials category to find one for the tool you need.

### 9.3 Adding an Extension

There are four ways to add an extension:

#### A. From the directory (easiest)

Click an extension in the [directory](https://www.pulsemcp.com/servers) — it installs via goose's deep-link protocol straight into the Desktop app.

#### B. Via the CLI / Desktop UI

=== "goose CLI"

    ```bash
    goose configure        # → Add Extension
    ```

    Choose the type:
    - **Built-In Extension** — pre-bundled with goose
    - **Command-Line Extension** — a local command/script (stdio MCP server)
    - **Remote Extension (Streamable HTTP)** — a remote MCP server over HTTP

    Example (Knowledge Graph Memory via `npx`):

    ```text
    ◇  What type of extension would you like to add?
    │  Command-line Extension
    ◇  What would you like to call this extension?
    │  Knowledge Graph Memory
    ◇  What command should be run?
    │  npx -y @modelcontextprotocol/server-memory
    ◇  Please set the timeout for this tool (in secs):
    │  300
    └  Added Knowledge Graph Memory extension
    ```

=== "goose Desktop"

    Sidebar → **Extensions** → *Add custom extension*. Fill in the type, name, command (e.g. `npx -y @modelcontextprotocol/server-memory`), timeout, and any environment variables, then click **Add**.

#### C. Per-session (CLI flags)

Enable an extension just for one session without installing it permanently:

```bash
# Built-in extensions
goose session --with-builtin "developer,computercontroller"

# External stdio extension
goose session --with-extension "uvx mcp-server-fetch"

# With environment variables
goose session --with-extension "GITHUB_PERSONAL_ACCESS_TOKEN=<token> npx -y @modelcontextprotocol/server-github"

# Remote Streamable HTTP extension
goose session --with-streamable-http-extension "https://example.com/streamable"
```

> [!NOTE]
> Many external extensions need a package runner — `npx` (Node.js) or `uvx` (Python). Install [Node.js](https://nodejs.org/) and/or [uv](https://github.com/astral-sh/uv) for these to work.

#### D. By editing the config file

For advanced users, add extensions directly to `~/.config/goose/config.yaml`:

```yaml
extensions:
  github:
    name: GitHub
    cmd: npx
    args: [-y @modelcontextprotocol/server-github]
    enabled: true
    envs: { "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>" }
    type: stdio
    timeout: 300
```

### 9.4 Enabling, Disabling & Removing

- **Default extensions (future sessions):** Desktop → Extensions toggles; CLI → `goose configure → Toggle Extensions` (space to toggle).
- **Mid-session:** Desktop → puzzle-piece button; CLI → `/extension <cmd>` or `/builtin <name>`.
- **Remove:** disable it first, then `goose configure → Remove Extension` (CLI) or the gear → *Remove Extension* (Desktop).

### 9.5 Smart Extension Recommendations

When you ask for something goose can't yet do, it **searches its available extensions** and offers to enable a relevant one. For example, "find all pending orders in our production database" prompts goose to enable the `postgresql` extension:

```text
■  goose would like to enable the following extension, do you approve?
| ● Yes, for this session
| ○ No
```

> [!NOTE]
> Dynamically enabled extensions apply only to the **current session**. To keep one enabled for future sessions, toggle it on in your defaults.

### 9.6 Security: Malware Scanning

goose automatically checks external extensions (those installed via `npx`/`uvx`) for known malware before activation, using the OSV database. A blocked package shows a clear error:

```text
Blocked malicious package: package-name@1.0.0 (npm). OSV MAL advisories: MAL-2024-1234
```

> [!TIP]
> Only install extensions from trusted, official sources. If you believe a block is a false positive, [open an issue](https://github.com/aaif-goose/goose/issues).

---

## 10. Recipes: Reusable Agents

A **recipe** packages a complete agent configuration — instructions, prompt, the extensions it needs, and parameters — into a single shareable YAML file. Recipes turn "the way I asked goose to do X" into a repeatable, parameterized command.

### 10.1 What a Recipe Looks Like

```yaml
version: 1.0.0
title: Readme Bot
author:
  contact: DOsinga
description: Generates or updates a README
instructions: You are a documentation expert
activities:
  - Scan project directory for documentation context
  - Generate a new README draft
  - Compare new draft with existing README.md
extensions:
  - type: builtin
    name: developer
    display_name: Developer
    timeout: 300
    bundled: true
prompt: |
  Here's what to do step by step:
    1. Scan the current project and learn as much as possible.
    2. Write a README covering description, getting started, and running tests.
    3. Write it to README.tmp.md, compare to the existing README.md, and only
       replace it if your version is clearly better.
    4. Clean up after yourself.
```

### 10.2 Running and Sharing Recipes

```bash
# Run a recipe by name or path
goose run --recipe readme-bot.yaml

# Pass parameters
goose run --recipe deploy.yaml --params environment=staging --params region=us-east-1

# Inspect before running
goose run --recipe deploy.yaml --explain        # show title/description/params
goose run --recipe deploy.yaml --render-recipe  # print the fully rendered recipe

# Validate, list, and create deep links
goose recipe validate deploy.yaml
goose recipe list --verbose
goose recipe deeplink deploy.yaml -p environment=staging
goose recipe open deploy.yaml                   # open in goose Desktop
```

> [!IMPORTANT]
> **Recipe trust:** The first time you run a recipe in goose Desktop, you'll see a **New Recipe Warning** showing the recipe's title, description, and instructions. Review it and click **Trust and Execute** if you trust it. This protects you from running unfamiliar recipe code.

### 10.3 Where Recipes Come From

goose can find recipes from local paths, additional directories (`GOOSE_RECIPE_PATH`), or a GitHub repository (`GOOSE_RECIPE_GITHUB_REPO`, format `owner/repo`). You can also wire a recipe to a custom slash command via `slash_commands` in your config (see [Admin Guide](aaif-goose__goose__AdminGuide.md)).

---

## 11. Subagents & Running Tasks

goose can **delegate work to subagents** — separate agent instances that run concurrently on sub-tasks and report back. This is how goose handles large, parallelizable jobs (e.g. "review these 5 files independently" or "research these 3 topics at once").

Subagents are powered by the **Summon** platform extension (enabled by default). Key controls:

| Setting | Default | Purpose |
|---|---|---|
| `GOOSE_MAX_BACKGROUND_TASKS` | 5 | Max concurrent subagent tasks |
| `GOOSE_SUBAGENT_MAX_TURNS` | 25 | Max turns a subagent runs before timeout |

You typically don't invoke subagents directly — you ask goose to do something parallelizable and it orchestrates them. **Sub-recipes** (`--sub-recipe`) let a recipe delegate to other recipes, optionally in parallel.

```bash
# A recipe that fans out to sub-recipes
goose run --recipe pipeline.yaml --sub-recipe lint.yaml --sub-recipe test.yaml
```

---

## 12. Scheduling Jobs

goose can run recipes **on a cron schedule**, unattended — perfect for daily standups, nightly maintenance, or periodic checks.

```bash
# Add a scheduled job (every weekday at 9 AM)
goose schedule add --schedule-id daily-standup --cron "0 9 * * 1-5" \
  --recipe-source ~/recipes/standup.yaml --params team=platform

# List, inspect, and manage schedules
goose schedule list
goose schedule sessions --schedule-id daily-standup --limit 10
goose schedule run-now --schedule-id daily-standup
goose schedule remove --schedule-id daily-standup

# Cron help with examples
goose schedule cron-help
```

Common cron expressions:

| Expression | Meaning |
|---|---|
| `0 * * * *` | Every hour, on the hour |
| `0 */2 * * *` | Every 2 hours |
| `@hourly` | Every hour (shorthand) |
| `0 9 * * *` | Every day at 9:00 AM |
| `0 9 * * 1` | Every Monday at 9:00 AM |
| `0 0 1 * *` | First day of every month at midnight |

> [!NOTE]
> Scheduling is built in — no external scheduler service is required. The `schedule services-status` / `services-stop` subcommands are deprecated and exist only for backward compatibility.

---

## 13. Terminal Integration & TUI

### 13.1 `goose term` — One Session Per Terminal

`goose term` ties a persistent goose session to your terminal window — it resumes automatically every time you open that terminal, and you can fire prompts at it with a short alias.

**Setup (zsh/bash):**

```bash
echo 'eval "$(goose term init zsh)"' >> ~/.zshrc
source ~/.zshrc
```

**Setup (Nushell):**

```bash
let init = ($nu.cache-dir | path join "goose-term-init.nu")
^goose term init nu | save --force $init
source $init
```

**Usage:**

```bash
goose term run list files in this directory
@goose "create a python script"     # alias
@g "why did that fail"              # short alias
```

Add `--default` to `goose term init` to make goose the handler for **any** command your shell doesn't recognize (supported for zsh, bash, and nu):

```bash
echo 'eval "$(goose term init zsh --default)"' >> ~/.zshrc
```

> [!CAUTION]
> The `--default` mode sends *anything you type that isn't a valid command* to goose. It's powerful but easy to trigger by accident — adopt it deliberately.

### 13.2 `goose tui` — Terminal UI

```bash
goose tui
```

Launches the goose terminal UI (the `@aaif/goose` npm package). It resolves a local `ui/text/dist/tui.js` if present, otherwise runs via `npx`. Requires `node`/`npx` on your PATH.

---

## 14. Agent Client Protocol (ACP)

The **[Agent Client Protocol (ACP)](https://agentclientprotocol.com/)** lets goose interoperate with editors and other agents. goose plays both sides:

### 14.1 goose as an ACP Server

Expose goose to editors like **Zed** and **JetBrains** IDEs:

```bash
# Over stdio (editors launch this)
goose acp --with-builtin developer

# Over HTTP + WebSocket
goose serve --host 127.0.0.1 --port 3284 --with-builtin developer
```

The editor connects and drives goose directly, with your configured extensions available as tools.

### 14.2 ACP Agents as Providers

goose can **delegate** to external ACP agents — using **Claude Code** or **OpenAI Codex** as the "brain" while goose passes your configured extensions through as MCP servers:

| ACP Provider | Install | Requires |
|---|---|---|
| **Claude ACP** (`claude-acp`) | `npm install -g @agentclientprotocol/claude-agent-acp` | Active Claude Code subscription |
| **Codex ACP** (`codex-acp`) | `npm install -g @zed-industries/codex-acp` | Active ChatGPT Plus/Pro subscription |

Configure these like any other provider via `goose configure`.

---

## 15. Local & Offline Models

goose is a **local agent** — pair it with a local LLM to keep your data private, work offline, and avoid per-token cost.

> [!WARNING]
> goose relies heavily on **tool calling**. Models without tool-calling support can only chat. If you use such a model (e.g. native DeepSeek-R1), you must [disable all extensions](#94-enabling-disabling--removing). Prefer tool-calling models like `qwen2.5`.

### 15.1 Ollama

```bash
# 1. Install Ollama, then run a tool-calling model
ollama run qwen2.5

# 2. In another terminal, configure goose → Ollama, host http://localhost:11434
goose configure
```

> [!TIP]
> If goose ignores extensions or `.goosehints`, the model's context window is probably too small. Raise it with `OLLAMA_CONTEXT_LENGTH` (Ollama) or the `--ctx-size` flag (Ramalama).

### 15.2 LM Studio

Download LM Studio, load a tool-calling model, and start its local server (default `http://localhost:1234`). Then `goose configure → LM Studio` (no API key required).

### 15.3 Built-in Local Inference

goose can run **GGUF** models directly via its bundled local-inference engine — no separate server needed. Manage models with:

```bash
goose local-models search llama          # search HuggingFace for GGUF models (alias: goose lm)
goose local-models download bartowski/Llama-3.2-1B-Instruct-GGUF:Q4_K_M
goose local-models list
goose local-models delete <id>
```

---

## 16. Managing Sessions

Every conversation is a **session** that goose saves so you can resume it later.

```bash
goose session list                          # see all sessions
goose session list --format json --limit 20 # machine-readable, limited
goose session -r                            # resume the most recent
goose session -r --name project-x           # resume a specific session
goose session -r --fork                     # branch off a copy
goose session -r --history                  # resume and replay messages
```

**Export & share:**

```bash
goose session export --name demo -o demo.md            # Markdown (also --format json|yaml)
goose session export --name demo --nostr               # publish as an encrypted Nostr share link
```

**Import** from other agents:

```bash
goose session import transcript.jsonl                  # Claude Code / Codex / Pi .jsonl, or a goose export
goose session import "goose://sessions/nostr/..." --nostr
```

**Diagnostics** for support requests:

```bash
goose session diagnostics --name demo -o ./diag.zip
```

> [!TIP]
> For large or complex tasks, break work into **smaller sessions**. Long sessions can occasionally enter a "doom spiral" — ending and starting fresh usually fixes it.

---

## 17. Code Review with goose

`goose review` reviews your **current git diff** for bugs, using goose as the reviewer. It discovers project-specific review prompts and check subagents and runs them in parallel.

```bash
goose review                       # review working tree vs HEAD
goose review main...HEAD           # review a specific range
goose review --checks-only         # run only the check subagents
goose review --summary-only        # just summarize the diff
goose review --dry-run             # show the assembled prompt + discovered checks
goose review --severity low        # surface every finding (default hides 'low')
goose review --files src/auth.rs   # restrict the review to specific files
goose review -i "this is a refactor, flag any behavior change"
```

How it works: goose discovers `**/.agents/checks/*.md` subagent reviewers and `**/.agents/REVIEW.md` scoped prompt overrides, builds a review request from your diff, and dispatches one `goose run` subprocess per check (up to 4 concurrent) so wall-clock time is bounded by the slowest check. Use `--no-orchestrate` to fall back to a single in-process agent.

| Flag | Purpose |
|---|---|
| `--model` / `--provider` | Model/provider for the main review agent |
| `--override-model <M>` | Force every check to use this model |
| `--turn-limit <N>` | Default turn limit for orchestrated checks |
| `--check-filter <name>` | Only run named checks |
| `--check-scope <dir>` | Search a different directory for checks |
| `--prompt <file>` | Replace the embedded base review prompt |
| `-q, --quiet` | Suppress non-result output |

---

## 18. Gateways & Plugins

### 18.1 Gateways — Chat with goose on External Platforms

**Gateways** connect goose to messaging platforms (e.g. Telegram) so you can talk to your agent from a chat app:

```bash
goose gateway start telegram --bot-token <TELEGRAM_BOT_TOKEN>
goose gateway pair telegram        # generate a pairing code
goose gateway status
goose gateway stop telegram
```

> [!NOTE]
> Gateway sessions can have a stricter turn cap than CLI/Desktop via `GOOSE_GATEWAY_MAX_TURNS` (defaults to `GOOSE_MAX_TURNS`, then 5) — useful for keeping chat-driven sessions bounded.

### 18.2 Plugins & Skills

**Plugins** are git-backed bundles that can add skills to goose:

```bash
goose plugin install https://github.com/owner/some-goose-plugin
goose plugin update some-goose-plugin
goose skills list                  # list all skills available to the agent
```

---

## 19. Tips & Best Practices

> [!TIP]
> **Protect your work with version control.** Stage your own edits, leave goose's unstaged until reviewed, and keep goose's changes in separate commits for easy reverts.

- **Be specific.** "Add a `--json` flag to the `report` command and update its tests" beats "improve the CLI."
- **Use `.goosehints`** to give goose persistent project context (build commands, conventions). Multiple context filenames are supported via `CONTEXT_FILE_NAMES`.
- **Pick the right mode.** Use `chat` to brainstorm safely, `smart_approve` for daily work, `auto` for trusted automation.
- **Right-size the model.** A fast model handles routine edits cheaply; reserve a frontier model for hard reasoning. Set a separate `GOOSE_FAST_MODEL` for auxiliary calls.
- **Tame runaway dev servers.** Commands like `npm run dev` never exit and will hang goose. Use the `GOOSE_TERMINAL` env var to neutralize them in your shell (see [Customizing Shell Behavior](#error-goose-hangs-on-npm-run-dev-or-similar)).
- **Break big tasks into smaller sessions** to keep context focused and costs down.
- **Use recipes** for anything you do more than twice, and **schedule** the ones you do on a cadence.

---

## 20. Troubleshooting

Format for each: the symptom, the cause, and the fix.

### Error: API errors / `404 Not Found` from your provider

**Cause:** Exhausted API credits or an invalid/misconfigured API key.
**Solution:** Check your provider dashboard for remaining credits; then reconfigure your key:

```bash
goose configure
```

**Prevention:** Use a gateway provider with rate limiting (Tetrate, OpenRouter) and monitor your credit balance.

### Error: `429` rate limit exceeded

**Cause:** Too many requests to the LLM provider in a short window.
**Solution:** Switch to a provider with built-in rate limiting (Tetrate Agent Router, OpenRouter), which handles backoff and failover for you.

### Error: `ExecutionError(... http://localhost:11434/v1/chat/completions)` (Ollama)

**Cause:** The Ollama model isn't downloaded/running, or the host is wrong.
**Solution:** Run `ollama run qwen2.5` first, then point goose at `http://localhost:11434`. On WSL, `localhost` may differ — find the IP with `ip route show | grep -i default | awk '{ print $3 }'` and use `http://<that-ip>:11434`.

### Error: `Context length exceeded`

**Cause:** Your input exceeds the model's token limit.
**Solution:** Break the request into smaller parts; use `.goosehints` for durable context; let goose auto-compact (`GOOSE_AUTO_COMPACT_THRESHOLD`). For local models, raise the context window.

### Error: `Failed to access keyring` / `org.freedesktop.secrets was not provided`

**Cause:** No system keyring is available (common in containers, headless Linux, CI).
**Solution:** Force file-based secret storage:

```bash
GOOSE_DISABLE_KEYRING=1 goose configure
```

Or set provider keys via environment variables and answer **No** when asked to save to the keyring. Secrets then live in `~/.config/goose/secrets.yaml` (macOS/Linux) or `%APPDATA%\Block\goose\config\secrets.yaml` (Windows).

### Error: `Could not run extension command (...): No such file or directory`

**Cause:** The extension's package runner (`npx`, `uvx`) isn't installed.
**Solution:** Install [Node.js](https://nodejs.org/) for `npx`-based extensions and [uv](https://github.com/astral-sh/uv) for `uvx`-based ones.

### Error: `Node.js installer script not found` (Windows)

**Cause:** Node.js is installed somewhere other than `C:\Program Files\nodejs\`.
**Solution:** Find it with `where.exe node`, then create a symlink (PowerShell as Admin):

```powershell
mklink /D "C:\Program Files\nodejs" "D:\Program Files\nodejs"
```

Restart goose and retry.

### Error: `hermit:fatal` when installing an extension

**Cause:** A stale Hermit cache (goose uses Hermit to provide `npx`/`uvx`).
**Solution (macOS):**

```bash
sudo rm -rf ~/Library/Caches/hermit
```

### Error: `Blocked malicious package: ...`

**Cause:** goose's OSV malware scan flagged a package used by an external extension.
**Solution:** Find an alternative extension, verify the source, and report false positives via a GitHub issue. Only install from trusted sources.

### Error: goose Desktop shows no window on launch (macOS)

**Cause:** goose can't write to `~/.config` to create its logs.
**Solution:**

```bash
ls -ld ~/.config            # confirm you have rwx
chmod u+rw ~/.config        # grant access (mkdir -p ~/.config first if missing)
```

Also check **System Settings → Privacy & Security → Files & Folders** and grant goose access.

### Error: goose hangs on `npm run dev` or similar

**Cause:** Long-running commands (dev servers) never exit, so goose waits forever.
**Solution:** Detect goose in your shell config via `GOOSE_TERMINAL` and block/redirect such commands:

```bash
# ~/.zshenv or ~/.bashrc
if [[ -n "$GOOSE_TERMINAL" ]]; then
  git() { [[ "$1" == "commit" ]] && { echo "❌ blocked under goose"; return 1; }; command git "$@"; }
fi
```

### Issue: Extensions fail in airgapped / corporate networks

**Cause:** goose's packaged `npx`/`uvx` shims try to download runtimes via Hermit, which restricted networks block.
**Solution:** Create alternatively named runners that bypass the shims, and reference them in your config:

```bash
ln -s /usr/local/bin/uvx /usr/local/bin/runuv
ln -s /usr/local/bin/npx /usr/local/bin/runnpx
```

```yaml
extensions:
  example:
    cmd: runuv          # bypasses goose's shim
    args: [mcp-server-example]
```

### Issue: Behind a corporate proxy / firewall

**Cause:** goose can't reach your provider through the proxy.
**Solution:** Set standard proxy variables and restart goose:

```bash
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal"
```

### Known bugs (from the issue tracker)

| Issue | Status | Workaround |
|---|---|---|
| MCP Apps fail to render when Code Execution extension is enabled (#9598) | Open | Disable Code Mode while using MCP Apps |
| Desktop ignores `GOOSE_MODEL` from `config.yaml` (#9451) | Closed | Set the model via Settings → Models |
| `shell` tool returns empty stdout/stderr on Windows in ACP stdio mode (#9582) | Open | — |
| Desktop creates empty "New Chat" sessions on reconnection when `goosed` is unreachable (#9608) | Open | Ensure `goosed` is running/reachable |
| Browser doesn't launch for auth on Windows (#9184) | Open | Complete OAuth manually if the browser doesn't open |

> [!TIP]
> Still stuck? Generate a diagnostic report (`goose session diagnostics`) and ask in the [Discord community](https://discord.gg/goose-oss).

---

## 21. Frequently Asked Questions

**Q: Is goose free?**
Yes — goose is free and open source (Apache-2.0). You pay only for the LLM you use, and even that can be free with a local model or a free provider tier (Groq, Google Gemini, Tetrate's free credits).

**Q: Do the Desktop app and CLI share settings?**
Yes. Provider config, model selection, and extensions are stored centrally and shared between both interfaces. Switch freely.

**Q: Where does goose store my data and secrets?**
Config in `~/.config/goose/` (macOS/Linux) or `%APPDATA%\Block\goose\` (Windows). Secrets go in your system keyring by default, falling back to `secrets.yaml` when no keyring is available. See [Reference → File locations](#226-key-file-locations).

**Q: Can goose run completely offline?**
Yes — use a local model via Ollama, LM Studio, or goose's built-in GGUF inference. Your prompts and code never leave your machine.

**Q: Will goose change my files without asking?**
In the default `smart_approve` mode goose prompts for risky actions and auto-approves safe ones. Set `GOOSE_MODE=approve` to be asked every time, or `chat` to disable tool execution entirely. Always use version control.

**Q: What's the difference between an extension and a recipe?**
An **extension** gives goose a *capability* (a set of tools). A **recipe** is a packaged *agent configuration* (prompt + which extensions + parameters) for a repeatable task.

**Q: Can I use my ChatGPT or Claude Code subscription instead of an API key?**
Yes. Use the **ChatGPT Codex** provider (browser OAuth) for ChatGPT subscriptions, or the **Claude ACP** / **Codex ACP** providers to delegate to Claude Code / Codex.

**Q: How do I keep goose away from sensitive files?**
Use `.gooseignore` files and per-tool permissions (covered in the Admin Guide), and run in `approve` mode when working near secrets.

**Q: What models should I use?**
Use a strong tool-calling model. goose works well with Claude Sonnet/Opus, GPT-4o, Gemini 2.x, and capable open models (Qwen, Llama 3.x, Kimi). The [Berkeley Function-Calling Leaderboard](https://gorilla.cs.berkeley.edu/leaderboard.html) is a good guide. Note OpenAI `o1-mini`/`o1-preview` are unsupported (no tool calling).

**Q: How do I run goose in CI/CD?**
Use `goose run --no-session --output-format json`, pin a version with `GOOSE_VERSION`, and use a recipe. Set `GOOSE_DISABLE_KEYRING=1` and pass provider keys via env vars.

**Q: How do I completely uninstall goose?**
Stop all goose processes, delete the "goose" credential from your keychain/credential manager, and remove `~/.config/goose`, `~/.local/share/goose`, `~/.local/state/goose` (Linux) or the equivalent `%APPDATA%`/`%LOCALAPPDATA%` folders (Windows), plus the Desktop app.

**Q: Can goose remember things between sessions?**
Yes — enable the **Memory** extension. It stores your preferences and recalls them in future sessions.

**Q: How do I see goose's reasoning?**
For models that expose thinking (DeepSeek-R1, Kimi, Gemini), set `GOOSE_CLI_SHOW_THINKING=1` in the CLI; the Desktop shows a collapsible "Show reasoning" toggle automatically.

---

## 22. Reference

### 22.1 Essential Commands

```bash
goose                      # start an interactive session
goose session -r           # resume the last session
goose run -t "<task>"      # one-shot task
goose configure            # configure providers/extensions/settings
goose info -v              # show full config
goose doctor               # health check
goose update               # update the CLI
```

### 22.2 Core Model Environment Variables

| Variable | Purpose | Default |
|---|---|---|
| `GOOSE_PROVIDER` | LLM provider to use | (must configure) |
| `GOOSE_MODEL` | Model to use | (must configure) |
| `GOOSE_FAST_MODEL` | Model for auxiliary calls (titles, classification) | provider default |
| `GOOSE_TEMPERATURE` | Response randomness (0.0–1.0) | model default |
| `GOOSE_MAX_TOKENS` | Max tokens per response | model default |
| `GOOSE_MODE` | Tool execution behavior (`auto`/`approve`/`smart_approve`/`chat`) | `smart_approve` |
| `GOOSE_CONTEXT_LIMIT` | Override the model's context window | model default |

### 22.3 Session & Context Environment Variables

| Variable | Purpose | Default |
|---|---|---|
| `GOOSE_MAX_TURNS` | Max turns without user input | 1000 |
| `GOOSE_CONTEXT_STRATEGY` | On context-limit: `summarize`/`truncate`/`clear`/`prompt` | `prompt` (interactive) |
| `GOOSE_AUTO_COMPACT_THRESHOLD` | Auto-summarize at this fraction of context used | 0.8 |
| `GOOSE_MAX_BACKGROUND_TASKS` | Max concurrent subagents | 5 |
| `GOOSE_SUBAGENT_MAX_TURNS` | Max turns per subagent | 25 |
| `GOOSE_CLI_THEME` | CLI markdown theme (`light`/`dark`/`ansi`) | `dark` |
| `GOOSE_CLI_SHOW_THINKING` | Show model reasoning in the CLI | off |
| `GOOSE_CLI_SHOW_COST` | Show cost estimates in the CLI | off |
| `CONTEXT_FILE_NAMES` | Custom hint/context filenames | `[".goosehints"]` |

### 22.4 Recipe Environment Variables

| Variable | Purpose |
|---|---|
| `GOOSE_RECIPE_PATH` | Extra directories to search for recipes |
| `GOOSE_RECIPE_GITHUB_REPO` | GitHub repo (`owner/repo`) to search for recipes |

### 22.5 Provider Quick Reference

Configure via `goose configure` (CLI) or Settings → Models (Desktop). Common keys:

| Provider | Required key(s) |
|---|---|
| Anthropic | `ANTHROPIC_API_KEY` |
| OpenAI | `OPENAI_API_KEY` (+ `OPENAI_HOST` for custom endpoints) |
| Google Gemini | `GOOGLE_API_KEY` |
| Groq | `GROQ_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Tetrate Agent Router | `TETRATE_API_KEY` (or browser auth) |
| Databricks | `DATABRICKS_HOST`, `DATABRICKS_TOKEN` |
| Amazon Bedrock | AWS credentials (set in advance) |
| Ollama (local) | `OLLAMA_HOST` |

### 22.6 Key File Locations

| What | macOS/Linux | Windows |
|---|---|---|
| Config | `~/.config/goose/config.yaml` | `%APPDATA%\Block\goose\config\config.yaml` |
| Secrets (fallback) | `~/.config/goose/secrets.yaml` | `%APPDATA%\Block\goose\config\secrets.yaml` |
| Custom providers | `~/.config/goose/custom_providers/` | `%APPDATA%\Block\goose\config\custom_providers\` |
| Session data | `~/.local/share/goose/` (Linux) | `%APPDATA%\Block\goose\` |
| Logs | `~/.local/state/goose/` (Linux) | `%LOCALAPPDATA%\Block\goose\` |

Override the root for all of the above with `GOOSE_PATH_ROOT` (useful for isolated/test environments).

### 22.7 Built-in MCP Servers

These ship with goose and can be run standalone (`goose mcp <name>`) or used by any MCP client:

| `goose mcp ...` | Extension |
|---|---|
| `developer` *(via `--with-builtin`)* | Developer tools |
| `computercontroller` | Computer Controller |
| `memory` | Memory |
| `tutorial` | Tutorial |
| `autovisualiser` | Auto Visualiser |

---

_Generated June 2026 from aaif-goose/goose at 2f99664. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._