goose AI agent: install, providers, extensions, recipes and skills

What is the goose AI agent?

goose is an open source AI agent that runs on your own machine and can write code, run commands, edit files and call external tools through MCP. It comes as a desktop app, a command line tool and an API, and it works with many model providers rather than one.

The goose repository describes it as "an open source, extensible AI agent that goes beyond code suggestions." The README adds that goose is not only for code: it can also handle research, writing, automation and data analysis. It is written in Rust and licensed under Apache 2.0.

goose was founded by Block. On 7 April 2026 the goose blog announced that Block donated goose to the Agentic AI Foundation (AAIF) at the Linux Foundation, "alongside Anthropic's Model Context Protocol (MCP) and OpenAI's AGENTS.md." The code moved from block/goose to aaif-goose/goose, and the docs moved to goose-docs.ai. Old links redirect.

This guide follows the official docs as read on 26 October 2026, when the latest release was v1.56.0 (23 October 2026).

How do you install goose?

The installation page offers a desktop app for macOS, Linux and Windows, and a CLI for all three.

For the desktop app on macOS you can download the zip or use Homebrew:

brew install --cask block-goose

Linux users get DEB, RPM and Flatpak packages, and Windows users get a zip to unzip and run.

For the CLI on macOS, Linux, or Windows through Git Bash or MSYS2, run the install script:

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

Add CONFIGURE=false before bash to skip the interactive setup. On macOS, brew install block-goose-cli also works, and Windows has a PowerShell script. Update the CLI later with goose update.

How do you connect a model to goose?

Run goose configure, choose Configure Providers, pick a provider and paste your key. The README says goose works with "15+ providers," naming Anthropic, OpenAI, Google, Ollama, OpenRouter, Azure and Bedrock. The quickstart walks through Tetrate Agent Router as its example.

Then start a session in your project:

cd my-project
goose session

Press Ctrl+C to exit and goose session -r to resume the last session. Inside a session, /model switches models and /model --provider <name> switches providers.

If you already pay for an AI subscription, look at ACP providers. The docs say they let you use goose with an existing Claude Code or ChatGPT Plus or Pro subscription, with "no per-token API costs." They wrap other agents through the Agent Client Protocol and pass your goose extensions to them as MCP servers. The current limitation is that goose session resume and goose session fork do not work with them yet.

What are goose extensions?

Extensions are how goose gets tools, and they are built on MCP. The README says goose can connect to "70+ extensions via the Model Context Protocol." Some ship with goose: the Developer extension gives it file and shell tools, and Computer Controller "enables webscraping, file caching, and automations," per the quickstart.

You can add extensions three ways:

• In the desktop app, open Extensions in the sidebar and toggle them on.
• In the CLI, run goose configure and choose Add Extension.
• For one session, pass flags such as --with-builtin developer, --with-extension "npx -y some-mcp-server" or --with-streamable-http-extension <url>.

Any MCP server you already use with another agent should work here. The MCP servers roundup is a good place to find candidates.

How do goose permission modes work?

goose has four permission modes that set how much it does without asking:

The docs warn that "Autonomous Mode is applied by default." If you are trying goose on a repo you care about, switch to Smart Approval or Manual Approval first. In the desktop app the default is under Settings > Chat > Default Mode, and in the CLI it lives under goose configure > goose settings > goose mode.

Subagents depend on this setting. goose can spin up subagents on its own to run tasks in parallel or keep the main conversation clean, but the subagents page says this only happens in autonomous mode and that subagents are disabled in the other three.

How do you give goose project rules?

goose reads two kinds of context files. The hints page says that by default "goose looks for both AGENTS.md and .goosehints at each level," loading them from your working directory up to the repository root and picking up nested ones as it works in subfolders. A global ~/.config/goose/.goosehints applies to every session, and local hints win when the two conflict. Hints need the Developer extension enabled.

If your repo already has an AGENTS.md, goose uses it with no extra setup. To read other agents' files too, set CONTEXT_FILE_NAMES:

export CONTEXT_FILE_NAMES='["AGENTS.md", "CLAUDE.md", ".goosehints"]'

Inside a hints file, an @ reference such as @README.md pulls that file into context straight away, while a plain mention points goose to a file it can read when needed.

Does goose support Agent Skills?

Yes. The skills page says a built-in Skills extension, enabled by default, adds each skill's name and description to goose's instructions at the start of a session, then loads the full SKILL.md when your request matches or when you ask for it by name.

goose looks in these places:

• ~/.agents/skills/ for global skills
• .agents/skills/ for project skills
• ~/.agents/plugins/<plugin-name>/ for skills that come with plugins

For backward compatibility it also reads .goose/skills/, .claude/skills/ and ~/.claude/skills/. A skill needs YAML frontmatter with name and description, and can include scripts or templates next to the SKILL.md. Run goose skills list to see what goose found, or load skills in a CLI session with /skills code-review edge-case-finder. goose ships one built-in skill, web-search.

The format matches the Agent Skills standard, so a skill written for Claude Code or Codex works in goose unchanged.

What are goose recipes?

Recipes are goose's way to package a whole setup for reuse. The recipe reference says they are "reusable goose configurations that package up instructions and settings so the setup can be easily shared and launched by others." A recipe is a YAML (recommended) or JSON file. title and description are required, plus at least one of instructions or prompt, and you can add parameters, extensions, settings for the provider and model, and sub_recipes.

version: "1.0.0"
title: "Weekly dependency check"
description: "List outdated dependencies and open a summary"
instructions: "Check {{ project }} for outdated dependencies and explain the risky upgrades."
parameters:
  - key: project
    input_type: string
    requirement: required
    description: "Path to the project"

The CLI commands page shows how to run and schedule them:

goose run --recipe recipe.yaml --params project=./api
goose run --recipe recipe.yaml --interactive
goose schedule add --schedule-id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml

For one-off headless work, goose run -t "your prompt" runs a prompt and exits, and goose run -i plan.md reads instructions from a file.

Can goose review your code?

Yes. goose review reviews your working tree against HEAD, or a range such as main...HEAD. It can discover extra review checks from .agents/checks/*.md and scoped instructions from .agents/REVIEW.md, then runs the checks in parallel. Useful flags include --instructions to add intent, --files to narrow the review, --dry-run to preview the prompt and --severity low to see every finding.

How does goose compare with Claude Code and Codex?

Claude Code's memory docs say it reads AGENTS.md when a repo has no CLAUDE.md, so one AGENTS.md can steer all three. Choose goose if you want a model-agnostic agent with a desktop app, recipes and governance under a foundation. Choose Claude Code or Codex if you mainly use one vendor's models and want that vendor's tight integration. The Codex vs Claude Code comparison covers those two, and OpenCode is another open source, multi-provider option.

Where do you keep the prompts and skills you use with goose?

Because goose reads AGENTS.md and .agents/skills/, the same files can serve goose and your other agents. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, with {{name}} blanks and Cmd+K search, and installs every skill in the repo with one command: npx skills add https://github.com/<you>/<repo>.git --all -g.