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
2. Quick Start
3. Installation
4. Connecting an LLM Provider
5. Running goose
6. How goose Works (the Agent Loop)
7. Controlling Autonomy: goose Modes & Permissions
8. CLI Command Reference
9. Working with Extensions (MCP)
10. Recipes: Reusable Agents
11. Subagents & Running Tasks
12. Scheduling Jobs
13. Terminal Integration & TUI
14. Agent Client Protocol (ACP)
15. Local & Offline Models
16. Managing Sessions
17. Code Review with goose
18. Gateways & Plugins
19. Tips & Best Practices
20. Troubleshooting
21. Frequently Asked Questions
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

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 to change this behavior.

2. Quick Start

The fastest path from zero to a working agent:

goose CLI

# 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:

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

goose Desktop

1. Download goose Desktop for your platform (see 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):

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.

goose CLI

Option 1 — Install script:

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):

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

Option 2 — Homebrew:

brew install block-goose-cli

3.2 Linux

goose Desktop

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

sudo dpkg -i goose_<version>.deb

Then launch goose from your application menu.

goose CLI

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
• MSYS2 — from msys2.org
• PowerShell — built into Windows 10/11

goose Desktop

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

Git Bash / MSYS2

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

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

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

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

$ 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:

goose configure

A typical flow:

┌   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).

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). 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:

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

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.

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:

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:

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):

5.3 One-Shot & Headless Runs

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

# 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:

   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).

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:

Set it for a session or globally:

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.

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.

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

8.2 session — Interactive Chat

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:

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):

8.3 run — Headless / Scripted

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

# 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) 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:

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

Warning

The Developer extension combined with autonomous mode lets goose execute commands and modify files without approval. To constrain this, configure your goose mode, tool permissions, and .gooseignore files.

9.2 The Extensions Directory

Beyond the built-ins, goose connects to any MCP server. The official extensions directory lists hundreds. A representative sample of what's available:

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 — it installs via goose's deep-link protocol straight into the Desktop app.

B. Via the CLI / Desktop UI

goose CLI

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):

◇  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:

# 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 and/or uv for these to work.

D. By editing the config file

For advanced users, add extensions directly to ~/.config/goose/config.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:

■  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:

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.

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

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

# 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).

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:

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.

# 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.

# 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:

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):

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

Setup (Nushell):

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

Usage:

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):

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

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) 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:

# 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:

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. Prefer tool-calling models like qwen2.5.

15.1 Ollama

# 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:

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.

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:

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:

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:

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.

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.

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:

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:

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).
• 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:

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:

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 for npx-based extensions and 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):

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):

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:

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:

# ~/.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:

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

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:

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

Known bugs (from the issue tracker)

Tip

Still stuck? Generate a diagnostic report (goose session diagnostics) and ask in the Discord community.

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.

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 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

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

22.3 Session & Context Environment Variables

22.4 Recipe Environment Variables

22.5 Provider Quick Reference

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

22.6 Key File Locations

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: