Goose

CLI

Block

An open source, extensible AI agent from Block that automates engineering tasks via MCP extensions, available as a CLI and desktop app.

Website Docs

MCP

Supported

MCP servers are configured as extensions under the extensions key in config.yaml. Supports local stdio and remote Streamable HTTP servers, plus built-in, platform, and inline Python extension types.

Verified 2026-07-12Docs

Transportsstdiohttp

Authheaders

Config files

Path	Scope	Format	Key
`~/.config/goose/config.yaml` macOS/Linux. On Windows: %APPDATA%/Block/goose/config/config.yaml.	Global	yaml	extensions

Fields

Field	Type	Description
`type`	"stdio" \| "streamable_http" \| "builtin" \| "platform" \| "frontend" \| "inline_python"	Extension type. stdio runs a local command; streamable_http connects to a remote MCP endpoint.
`name`	string	Internal extension name.
`display_name`	string	Human-readable name shown in the UI (optional).
`enabled`	boolean	Whether the extension is active.
`cmd`	string	Command to execute for a stdio extension.
`args`	string[]	Arguments passed to the command.
`uri`	string	Endpoint URL for a streamable_http extension. Supports environment-variable substitution.
`headers`	record<string, string>	HTTP headers for a streamable_http extension (e.g. Authorization).
`envs`	record<string, string>	Environment variable values passed to the extension.
`env_keys`	string[]	Names of required environment variables; missing values are prompted for and stored in the keyring.
`timeout`	number	Operation timeout in seconds.
`available_tools`	string[]	Filter to specific tool names; empty (default) loads all tools.
`bundled`	boolean	Whether the extension is included with goose.

Capabilities

ToolsSupported

PromptsSupported

ResourcesInformation missing

RootsSupported

ElicitationSupported

SamplingSupported

Examples

Local stdio extension

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

Remote Streamable HTTP extension

extensions:
  remote-tools:
    name: remote-tools
    type: streamable_http
    uri: https://example.com/mcp
    headers: { "Authorization": "Bearer <token>" }
    enabled: true
    timeout: 300

•Servers are configured as entries under the extensions key (not mcpServers).
•SSE transport is no longer supported; the sse type is kept only for config file compatibility (per the goose source).
•Extensions can also be added via `goose configure`, the Desktop UI, goose://extension deeplinks, session flags (--with-extension, --with-builtin, --with-streamable-http-extension), or in-session /extension and /builtin commands.
•Secrets referenced via env_keys are stored in the system keyring (or secrets.yaml with file-based storage), not in config.yaml.
•goose automatically checks external extensions for known malware before activation.

Skills

Supported

SKILL.md skill folders following the open Agent Skills standard, discovered at session start and loaded automatically when a request matches, or listed and loaded via the CLI /skills command.

Verified 2026-07-12Docs

Invokeautomatic/skills <name>natural language (e.g. 'use the code-review skill')

Config files

Path	Scope	Format	Key
`.agents/skills/<name>/SKILL.md` Project-level skills, scoped to the current project.	Project	markdown	—
`~/.agents/skills/<name>/SKILL.md` Global skills, available in all sessions.	Global	markdown	—
`~/.agents/plugins/<plugin-name>/` Skills provided by installed plugins, discovered at session startup.	Global	markdown	—

Fields

Field	Type	Description
`name`*	string	Skill identifier in the YAML frontmatter.
`description`*	string	What the skill does and when to use it; goose matches requests against it for automatic loading.

Examples

Code review skill

---
name: code-review
description: Comprehensive code review checklist for pull requests
---

# Code Review Checklist

When reviewing code, check each of these areas:

## Functionality
- [ ] Code does what the PR description claims
- [ ] Edge cases are handled

•Requires the built-in Summon platform extension (enabled by default, v1.25.0+); Summon replaced the deprecated Skills extension (v1.16.0-v1.24.0).
•Skills can bundle supporting files (scripts, templates); goose accesses them with the Developer extension's file tools.
•Skills can also come from installed plugins under ~/.agents/plugins/<plugin-name>/; Open Plugin skill names are namespaced as <plugin>:<skill>.
•Backward compatibility: goose also discovers skills from .goose/skills/, .claude/skills/, ~/.claude/skills/, and platform-specific config directories, but .agents/skills/ is the recommended standard.
•goose skills are compatible with Claude Desktop and other agents that support the Agent Skills standard.

Rules

Supported

Persistent context via .goosehints and AGENTS.md files, loaded globally from the config directory and locally from the project hierarchy into every request's system prompt.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`~/.config/goose/.goosehints` Global hints applied to all sessions.	Global	text	—
`.goosehints` Local hints at the project root and/or any directory in the hierarchy (nested hints supported).	Project	text	—
`AGENTS.md` Loaded by default alongside .goosehints, including nested AGENTS.md files.	Project	markdown	—
`~/.config/goose/AGENTS.md` Configured context filenames are also loaded globally from ~/.config/goose/.	Global	markdown	—

Examples

Local .goosehints

This is a simple example JavaScript web application that uses the Express.js framework.

Go through the @README.md for information on how to build and test it as needed.

Run tests with `npm run test` ideally after each change.

•By default goose looks for AGENTS.md then .goosehints at each level (both global and local); local hints take priority over global hints on conflict.
•Nested hint files are supported in git repositories: files load from the working directory up to the repo root at session start, and from nested subdirectories as goose accesses them.
•@filename.md syntax inside a hints file automatically inlines that file's content; plain references just point goose at files to read when needed.
•The CONTEXT_FILE_NAMES environment variable (JSON array, default ["AGENTS.md", ".goosehints"]) swaps in other rule filenames such as CLAUDE.md or .cursorrules.
•Hints require the Developer extension to be enabled.
•Hint files are plain text; markdown formatting is conventional but not required.

Hooks

Supported

Shell-command hooks that fire on session, prompt, tool, file, and shell lifecycle events, defined in hooks/hooks.json inside plugin directories following the Open Plugins hooks specification.

Verified 2026-07-12Docs

EventsSessionStartSessionEndStopUserPromptSubmitPreToolUsePostToolUsePostToolUseFailureBeforeReadFileAfterFileEditBeforeShellExecutionAfterShellExecution

Config files

Path	Scope	Format	Key
`~/.agents/plugins/<plugin-name>/hooks/hooks.json` User plugins, available across projects.	Global	json	hooks
`.agents/plugins/<plugin-name>/hooks/hooks.json` Project plugins, loaded when goose starts from that project.	Project	json	hooks

Fields

Field	Type	Description
`matcher`	string	Regular expression deciding whether the rule runs for the event; omitted means the rule runs for every event of that type.
`hooks[].type`	"command"	Action type. Only command is currently supported; defaults to command when omitted.
`hooks[].command`*	string	Shell command to run (via sh -c). Receives the event payload as JSON on stdin.
`hooks[].timeout`	number	Timeout in seconds for the command. Defaults to 30.

Examples

Format files after goose edits them

{
  "hooks": {
    "AfterFileEdit": [
      {
        "matcher": "\\.(ts|tsx|js|jsx|json|md)$",
        "hooks": [
          {
            "type": "command",
            "command": "${PLUGIN_ROOT}/scripts/prettier.sh"
          }
        ]
      }
    ]
  }
}

•Hooks belong to a plugin: a directory with plugin.json and hooks/hooks.json, placed under ~/.agents/plugins/<name>/ (user) or <project>/.agents/plugins/<name>/ (project).
•Commands run via sh -c and receive the event payload (event, session_id, matcher_context, tool_name, tool_input, message, working_dir, ...) as JSON on stdin.
•${PLUGIN_ROOT} in a command references the plugin directory; it is also set in the hook's environment.
•The matcher is a regex tested against the event's most relevant string (tool name, prompt text, file path, or shell command).
•AfterFileEdit and AfterShellExecution only run after successful tool calls; use PostToolUseFailure for failures. SubagentStart/SubagentStop are not currently emitted.
•Hook failures and timeouts are logged but never crash goose. Disable a plugin via disabledPlugins in ~/.config/goose/settings.json (or <project>/.config/goose/settings.json).

Commands

Supported

Custom slash commands are shortcuts that run recipes (reusable YAML/JSON task templates), mapped under the slash_commands key in config.yaml or assigned in the Desktop Recipes UI. Built-in CLI slash commands cover session control.

Verified 2026-07-12Docs

Invoke/command-name/command-name <parameter>

Config files

Path	Scope	Format	Key
`~/.config/goose/config.yaml` List of { command, recipe_path } mappings. On Windows: %APPDATA%/Block/goose/config/config.yaml.	Global	yaml	slash_commands

Fields

Field	Type	Description
`command`*	string	Command name without the leading slash.
`recipe_path`*	string	Absolute path to the recipe .yaml file to run.

Examples

Map slash commands to recipes

slash_commands:
  - command: "run-tests"
    recipe_path: "/path/to/recipe.yaml"
  - command: "daily-report"
    recipe_path: "/Users/me/.local/share/goose/recipes/report.yaml"

Minimal recipe file

version: "1.0.0"
title: "Code Review Assistant"
description: "Automated code review with best practices"
instructions: "You are a code reviewer..."
prompt: "Review the code in this repository"
extensions: []

•Running a custom command loads the recipe's instructions and prompt into the conversation without displaying them in chat.
•Custom commands accept at most one parameter; any other recipe parameters must have defaults. Names are case-insensitive, unique, and must not contain spaces.
•Custom names cannot shadow built-in CLI slash commands such as /recipe, /compact, /help, /plan, /mode, /prompts, /prompt, /skills, /extension, /builtin, /clear, /exit.
•Recipes are defined in .yaml (recommended, CLI + Desktop) or .json files; .yml is not supported by the CLI. See the recipe reference for the full schema (instructions, prompt, parameters, extensions, settings, retry, response, sub_recipes).
•If a mapped recipe file is missing or invalid, the command text is sent to the model as regular text.

Settings

Supported

Primary configuration lives in ~/.config/goose/config.yaml: provider and model, tool-execution mode, extensions, slash commands, and general settings.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`~/.config/goose/config.yaml` macOS/Linux. On Windows: %APPDATA%/Block/goose/config/config.yaml.	Global	yaml	—

Fields

Field	Type	Description
`GOOSE_PROVIDER`*	string	Primary LLM provider (e.g. anthropic, openai).
`GOOSE_MODEL`*	string	Default model to use.
`GOOSE_MODE`	string	Tool execution behavior.
`GOOSE_TEMPERATURE`	number	Model response randomness, between 0.0 and 1.0.
`GOOSE_MAX_TURNS`	number	Maximum number of turns allowed without user input (default 1000).
`GOOSE_AUTO_COMPACT_THRESHOLD`	number	Context-usage fraction (0.0-1.0) that triggers automatic session summarization; 0.0 disables it (default 0.8).
`GOOSE_RECIPE_GITHUB_REPO`	string	GitHub repository (org/repo) to load recipes from.
`GOOSE_SEARCH_PATHS`	string[]	Extra directories prepended to PATH when running extension commands.
`GOOSE_ALLOWLIST`	string	URL for the allowed-extensions list.
`extensions`	object	MCP extension configuration (see the mcp surface).
`slash_commands`	array	Custom slash-command to recipe mappings (see the commands surface).

Examples

Basic config.yaml

GOOSE_PROVIDER: "anthropic"
GOOSE_MODEL: "claude-4.5-sonnet"
GOOSE_MODE: "smart_approve"

extensions:
  developer:
    bundled: true
    enabled: true
    name: developer
    timeout: 300
    type: builtin

•Environment variables take precedence over config file settings, which take precedence over defaults.
•Companion files in ~/.config/goose/: permission.yaml (tool permission levels via goose configure), secrets.yaml (only with file-based secret storage), permissions/tool_permissions.json (auto-managed), and prompts/ (custom prompt templates).
•Store secrets in the system keyring, not in config.yaml.
•Many settings can also be managed via `goose configure` (CLI) or the Desktop Settings page.