Configure Goose extensions, hints, recipes and permissions

The main config file is ~/.config/goose/config.yaml on macOS and Linux, or %APPDATA%\Block\goose\config\config.yaml on Windows. Environment variables override config file settings, which override defaults.

To add an extension interactively, run goose configure, choose Add Extension, then pick a type: Built-In, Command-Line (a local stdio command), Remote (SSE) or Remote (Streaming HTTP). The default extension timeout is 300 seconds.

extensions:
  knowledge-graph:
    name: Knowledge Graph Memory
    cmd: npx
    args: [-y, '@modelcontextprotocol/server-memory']
    enabled: true
    type: stdio
    timeout: 300
  remote-service:
    name: Remote Service
    url: http://localhost:8080/sse
    enabled: true
    type: sse
    timeout: 300

Streaming HTTP extensions use type streamable_http with a uri key. You can also enable an extension for one session with a CLI flag.

goose session --with-extension "YOUR_COMMAND"
goose session --with-remote-extension "YOUR_SSE_URL"
goose session --with-streamable-http-extension "YOUR_HTTP_URL"
goose session --with-builtin "YOUR_EXTENSION_ID"

By default Goose looks for AGENTS.md and then .goosehints files. A global .goosehints file at ~/.config/goose/.goosehints applies to every session, and a .goosehints file in a project directory applies when you work there. When both exist Goose uses both, with local hints taking priority.

Goose also loads hint files from nested directories as it touches files in them, which suits monorepos. Hints are plain natural language, and the @ syntax pulls in another file's content.

• Set CONTEXT_FILE_NAMES to a JSON list to use other file names, such as .cursorrules.
• Keep build, test and approval rules in hints so Goose follows them every session.
• Point to longer docs instead of pasting them in full.

export CONTEXT_FILE_NAMES='[".cursorrules", "AGENTS.md"]'

Recipes package instructions, a starting prompt, parameters and extensions into a reusable YAML workflow. A recipe needs a title, a description, and at least one of instructions or prompt. Parameters are referenced with double curly brace placeholders.

version: "1.0.0"
title: "Code Review"
description: "Review code in a chosen language"
instructions: "You are a code reviewer. Focus on {{ language }} best practices."
prompt: "Review the changes in this project"
parameters:
  - key: language
    input_type: string
    requirement: required
    description: "Language to review"

goose run --recipe code-review.yaml --params language=Python
goose run --recipe code-review.yaml --interactive

Goose finds recipes in the current directory, in folders listed in GOOSE_RECIPE_PATH, and in a GitHub repository set with GOOSE_RECIPE_GITHUB_REPO.

• Completely Autonomous (auto): Goose edits files, uses extensions and deletes files without asking. This is the default.
• Manual Approval (approve): Goose asks before using any tool or extension.
• Smart Approval (smart_approve): low risk actions run automatically and others are flagged for approval.
• Chat Only (chat): no extension use or file changes.

In the CLI, switch modes mid session with the /mode command, or run goose configure and choose Goose Settings, then Goose Mode. The GOOSE_MODE setting holds the same values.

/mode smart_approve