# Goose An open source, extensible AI agent from Block that automates engineering tasks via MCP extensions, available as a CLI and desktop app. Schema: 1.0 · Data: ee5de863c30bdbe4fe7dd3e07c7e22ea9bf4ab2248dbc7c35cdbf60bc28be1db ## Configuration ### MCP Status: 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. - global: `~/.config/goose/config.yaml` (yaml) — key: extensions — macOS/Linux. On Windows: %APPDATA%/Block/goose/config/config.yaml. - `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 — HTTP headers for a streamable_http extension (e.g. Authorization). - `envs`: record — 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. - transports: stdio, http - auth: headers - Tools: supported - Prompts: supported — MCP prompts are listed and run via the CLI /prompts and /prompt commands. - Resources: missing — Not yet verified from official docs. - Roots: supported — goose advertises roots support and shares the session working directory (single root). - Elicitation: supported — Form-mode elicitation requests render as forms in Desktop and prompts in the CLI; 5-minute timeout. - Sampling: supported — Sampling-aware extensions automatically get access to the LLM goose is using. - 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. Local stdio extension ```yaml extensions: github: name: GitHub cmd: npx args: [-y @modelcontextprotocol/server-github] enabled: true envs: { "GITHUB_PERSONAL_ACCESS_TOKEN": "" } type: stdio timeout: 300 ``` Remote Streamable HTTP extension ```yaml extensions: remote-tools: name: remote-tools type: streamable_http uri: https://example.com/mcp headers: { "Authorization": "Bearer " } enabled: true timeout: 300 ``` Source: https://goose-docs.ai/docs/getting-started/using-extensions Checked: 2026-07-12 ### Skills Status: 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. - project: `.agents/skills//SKILL.md` (markdown) — Project-level skills, scoped to the current project. - global: `~/.agents/skills//SKILL.md` (markdown) — Global skills, available in all sessions. - global: `~/.agents/plugins//` (markdown) — Skills provided by installed plugins, discovered at session startup. - `name`: string (required) — Skill identifier in the YAML frontmatter. - `description`: string (required) — What the skill does and when to use it; goose matches requests against it for automatic loading. - invocation: automatic, /skills , natural language (e.g. 'use the code-review skill') - 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//; Open Plugin skill names are namespaced as :. - 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. Code review skill ```markdown --- 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 ``` Source: https://goose-docs.ai/docs/guides/context-engineering/using-skills Checked: 2026-07-12 ### Rules Status: 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. - global: `~/.config/goose/.goosehints` (text) — Global hints applied to all sessions. - project: `.goosehints` (text) — Local hints at the project root and/or any directory in the hierarchy (nested hints supported). - project: `AGENTS.md` (markdown) — Loaded by default alongside .goosehints, including nested AGENTS.md files. - global: `~/.config/goose/AGENTS.md` (markdown) — Configured context filenames are also loaded globally from ~/.config/goose/. - 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. Local .goosehints ```markdown 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. ``` Source: https://goose-docs.ai/docs/guides/context-engineering/using-goosehints Checked: 2026-07-12 ### Hooks Status: 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. - global: `~/.agents/plugins//hooks/hooks.json` (json) — key: hooks — User plugins, available across projects. - project: `.agents/plugins//hooks/hooks.json` (json) — key: hooks — Project plugins, loaded when goose starts from that project. - `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 (required) — 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. - events: SessionStart, SessionEnd, Stop, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, BeforeReadFile, AfterFileEdit, BeforeShellExecution, AfterShellExecution - Hooks belong to a plugin: a directory with plugin.json and hooks/hooks.json, placed under ~/.agents/plugins// (user) or /.agents/plugins// (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 /.config/goose/settings.json). Format files after goose edits them ```json { "hooks": { "AfterFileEdit": [ { "matcher": "\\.(ts|tsx|js|jsx|json|md)$", "hooks": [ { "type": "command", "command": "${PLUGIN_ROOT}/scripts/prettier.sh" } ] } ] } } ``` Source: https://goose-docs.ai/docs/guides/context-engineering/hooks Checked: 2026-07-12 ### Commands Status: 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. - global: `~/.config/goose/config.yaml` (yaml) — key: slash_commands — List of { command, recipe_path } mappings. On Windows: %APPDATA%/Block/goose/config/config.yaml. - `command`: string (required) — Command name without the leading slash. - `recipe_path`: string (required) — Absolute path to the recipe .yaml file to run. - invocation: /command-name, /command-name - 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. Map slash commands to recipes ```yaml 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 ```yaml 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: [] ``` Source: https://goose-docs.ai/docs/guides/context-engineering/slash-commands Checked: 2026-07-12 ### Settings Status: supported Primary configuration lives in ~/.config/goose/config.yaml: provider and model, tool-execution mode, extensions, slash commands, and general settings. - global: `~/.config/goose/config.yaml` (yaml) — macOS/Linux. On Windows: %APPDATA%/Block/goose/config/config.yaml. - `GOOSE_PROVIDER`: string (required) — Primary LLM provider (e.g. anthropic, openai). - `GOOSE_MODEL`: string (required) — Default model to use. - `GOOSE_MODE`: string — Tool execution behavior. Values: auto, approve, chat, smart_approve - `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). - 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. Basic config.yaml ```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 ``` Source: https://goose-docs.ai/docs/guides/config-files Checked: 2026-07-12 ## Search, browser & identification Not researched. Unknown does not mean unsupported.