Goose AI Agent Tutorial: CLI, MCP, Ollama and Recipes

Goose is a free, open-source AI agent that runs on your machine, distributed as a command-line interface (CLI), a desktop application, and an API. Unlike simple code assistants, Goose goes beyond suggestions: it runs shell commands, edits files, executes code, and orchestrates multi-step workflows autonomously. Goose connects to any large language model (LLM) provider, including models running locally, and extends its capabilities through Model Context Protocol (MCP) servers.

Block introduced Goose in January 2025 as "codename goose", and the project has evolved significantly since then. In December 2025, Block contributed Goose to the Linux Foundation's Agentic AI Foundation (AAIF), alongside Anthropic's MCP and OpenAI's AGENTS.md, so the project's future is shaped by the community under neutral governance. In April 2026, the repository moved to github.com/aaif-goose/goose and the documentation to goose-docs.ai. The project now styles its name in lowercase ("goose"); the old block/goose links still redirect, but the old documentation pages don't.

In this post, I'll guide you through installing the Goose CLI on Linux, macOS, and Windows, connecting it to a free cloud model (Google Gemini) or a fully local one (Ollama), extending it with an MCP server, and automating tasks with recipes and skills. I tested every step with Goose v1.54.0 in October 2026.

Goose comes in two flavors that share the same configuration: a desktop app and a command-line interface (CLI). The desktop app is the friendlier option if you prefer a chat window, and you can download it from the installation guide (on macOS, brew install --cask block-goose). I prefer the CLI because it's lightweight, scriptable, and lets me interact with the agent without leaving the terminal, so that's what this post focuses on.

For Linux and macOS, install the latest version of the Goose CLI using:

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

This script downloads the latest Goose binary for your operating system and architecture, installs it in ~/.local/bin, and launches goose configure right away. If you'd rather configure Goose later, put CONFIGURE=false in front of bash:

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

If ~/.local/bin is not in your PATH, the script offers to add it to your shell profile (with CONFIGURE=false, it only prints a warning and you add it yourself). Open a new terminal afterwards so that the goose command is found.

For macOS users (and Linux users with Homebrew), Goose is also available via Homebrew:

brew install block-goose-cli

Once installed, you can update Goose at any time by running:

goose update

If you installed Goose with Homebrew, run brew upgrade block-goose-cli instead so that Homebrew keeps track of the version.

On Windows, you can run the same curl command from Git Bash or MSYS2. From PowerShell, download the installation script and run it:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\download_cli.ps1

The Set-ExecutionPolicy line allows scripts only in the current PowerShell window, since Windows blocks them by default. The PowerShell script installs Goose in .local\bin under your user profile (from Git Bash, the bash script uses %USERPROFILE%\goose instead); if goose isn't found, add the directory the installer printed to your PATH. If you prefer a Linux environment, Goose works inside the Windows Subsystem for Linux (WSL) too: follow the Linux instructions from your WSL shell.

Next, configure Goose to use an LLM provider. Goose supports dozens of providers (the goose configure list has more than 80 entries in v1.54) across four main groups:

• API-based providers: Anthropic (Claude), OpenAI, Google Gemini, xAI (Grok), Mistral AI, Groq, DeepSeek, OpenRouter, and many more
• Cloud platforms: Amazon Bedrock, GCP Vertex AI, Azure OpenAI, Databricks, Snowflake
• Local providers: Ollama, LM Studio, and Goose's own built-in local inference (completely free, runs on your machine)
• Your existing subscriptions: Claude Code, Codex, and GitHub Copilot, which Goose drives through the Agent Client Protocol (ACP) so you can reuse a plan you already pay for

You only need one provider: I'll start with Gemini, the quickest free option, and then show a fully local alternative with Ollama.

I chose the Gemini API, Google's LLM provider, because it still offers a free tier (as of October 2026) for its Flash and Flash-Lite models, which handle tool calling well enough to drive an agent. Keep two caveats in mind. Google applies the free-tier limits per project and changes them often, so check your current quota in Google AI Studio. On the free tier, Google may also use your prompts to improve its products, so don't send it code you can't share.

To connect Goose to Gemini, you need a Google account and an API key. You can generate this key in Google AI Studio:

Press the "Create API key" button to generate a new API key.

We will use this API key to configure Goose to connect to Google Gemini. If the install script didn't already start the wizard, run the following command:

goose configure

The first time you run it, the goose configure wizard asks whether you want to share anonymous usage data, and then how you'd like to set up your provider. The first two options (OpenRouter and Tetrate Agent Router) sign you in through the browser; choose Manual Configuration instead. The provider list is long, so select Search all providers..., type Gemini, and pick Google Gemini (API Key). Avoid the plain "Gemini" entry, which signs in with your Google account and is now deprecated.

Paste your API key, select the default model, and finally choose the goose mode, which controls whether Goose uses its tools freely or asks for your approval first. The default, Auto Mode, lets Goose edit files and run commands without asking; if you're going to try Goose on a real project, pick Approve Mode or Smart Approve Mode instead (I explain the modes in the first session). Goose stores the key in your system keyring (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux); where there is none, as in WSL or on a server, it falls back to a plain-text secrets.yaml file in its configuration directory.

If the configuration is successful, you'll see a confirmation message. If you encounter issues, run goose info --check to test the provider connection; goose info also prints where Goose keeps its configuration and logs (~/.config/goose and ~/.local/state/goose/logs on Linux and macOS).

If you'd rather not send your code to a cloud provider, or you don't want to deal with rate limits, you can run Goose with a local model through Ollama. Everything stays on your machine, and the only limit is your hardware.

First, install Ollama and pull a model that supports tool calling, for example, the small Qwen 3 model I used for this post (a 2.5 GB download):

ollama pull qwen3:4b-instruct-2507-q4_K_M

Then run goose configure, choose Configure Providers (or Manual Configuration on the first run), search for Ollama, accept localhost as the host, answer No to the advanced settings, and select the model from the list of models you've downloaded:

Goose can also run models without Ollama: its built-in local inference downloads GGUF and MLX models from Hugging Face. Run goose local-models search qwen to find one and goose local-models download to fetch it.

Local models are free and private, but small models make mistakes that larger ones don't. qwen3:4b-instruct is a 4-billion-parameter small language model that runs comfortably on a laptop, and it handled file editing and shell commands well. However, when I gave it the browser automation task from later in this post, it called the right tools and then made up three of the four URLs instead of reading the results. If you go local, use the largest tool-calling model your machine can run (for example, a bigger Qwen 3.5 variant or gpt-oss:20b), and double-check its answers. Configuring Ollama also makes it your default provider: the rest of this post uses Gemini, so run goose configure and pick Google Gemini again before you try the browser example. With MCP, even smaller models can achieve expert-level performance on specialized tasks, but only when the tools hand them the right context.

Start a new session by running the following command:

goose session

This command launches a terminal-based chat session where you can interact with the LLM.

In the image above, you can see a Goose session running in the terminal with the local Ollama model. The header shows the provider, the model, the session ID, and the working directory, and the bar at the bottom tracks how much of the model's context window you've used. I asked Goose to create a Python script that prints today's date and run it. Goose used two tools from its built-in Developer extension: write to create the file and shell to run it.

By default, Goose runs in Auto mode, which means it edits files and runs commands without asking. That's convenient, but if you're trying Goose on a real project, switch to a mode that asks for approval first, for example by typing /mode approve in the session:

• auto: Goose uses its tools freely (the default).
• approve: Goose asks before every tool call.
• smart_approve: Goose asks only for actions it considers risky. It runs the tools that declare the readOnlyHint MCP tool annotation as true without asking, always asks for the ones that declare it as false, and lets the model judge the tools that don't declare it.
• chat: Goose doesn't use tools at all.

To change the default for every session, run goose configure and choose goose settings.

Goose also includes several other built-in slash commands that you can use during a session:

• /help - List all the available commands
• /model - Switch to a different model (or provider) without leaving the session
• /skills - List the available skills or load one by name
• /prompts - List available prompts
• /compact - Compact the conversation history
• /clear - Clear the conversation
• /exit - End the session

To pick up where you left off later, run goose session -r, which resumes your most recent session. Goose also reads project instructions automatically from AGENTS.md and .goosehints files, so you can describe your project's conventions once and reuse them in every session.

The MCP ecosystem has grown enormously since Goose's initial release: the official MCP Registry alone lists more than 40,000 servers (October 2026), covering developer tools, productivity suites, and specialized services.

To demonstrate Goose's extensibility, let's set up the Playwright MCP server from Microsoft. This server enables browser automation using Playwright's accessibility tree, making it fast and LLM-friendly without requiring vision models. You can configure it through the command line or by editing your config.yaml file. For this example, we will use the command line:

goose configure

The CLI will prompt:

This will update your existing config files
  if you prefer, you can edit them directly at /home/user/.config/goose

┌   goose-configure
│
◆  What would you like to configure?
│  ○ Configure Providers (Change provider or update credentials)
│  ○ Custom Providers
│  ● Add Extension (Connect to a new extension)
│  ○ Toggle Extensions
│  ○ Remove Extension
│  ○ goose settings
└

Select Add Extension, choose Command-line Extension, and enter the following details for the Playwright MCP server:

┌   goose-configure
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Command-line Extension
│
◇  What would you like to call this extension?
│  playwright
│
◇  What command should be run?
│  npx @playwright/mcp@latest
│
◇  Please set the timeout for this tool (in secs):
│  300
│
◇  Enter a description for this extension:
│  Playwright
│
◇  Would you like to add environment variables?
│  No
│
└  Added playwright extension
└  Configuration saved successfully to /home/user/.config/goose/config.yaml

The wizard stores the extension in your config.yaml file (run goose info to find it on Windows), so you can also add it by hand:

extensions:
  playwright:
    enabled: true
    type: stdio
    name: playwright
    description: Playwright
    cmd: npx
    args:
    - '@playwright/mcp@latest'
    timeout: 300

To try an MCP server for a single session without saving it, pass it on the command line instead: goose session --with-extension "playwright:npx @playwright/mcp@latest".

To demonstrate Goose's capabilities with the Playwright MCP server, make sure Gemini (or another capable cloud model) is your provider, start a new goose session so that Goose loads the extension, and type the following prompt:

Open a new browser window and navigate to https://blog.marcnuri.com, evaluate the links to find the author's LinkedIn, Bluesky, GitHub, and Twitter URLs

Goose opens a browser window, navigates to the website, and analyzes the page's accessibility tree. It then extracts the author's LinkedIn, Bluesky, GitHub, and Twitter URLs and reports them back.

In the previous image, you can see the Goose session with the Playwright MCP server running in the terminal, this time with Gemini as the provider. I took this screenshot with an older Goose version, so the session header looks different, but the flow is the same.

After I submitted the prompt, Goose executed these steps:

1. Goose sends my prompt and available tools to the LLM.
2. The LLM responds with Playwright actions, and Goose executes them:
   • Opens a browser window.
   • Navigates to the website.
   • Scans the page's accessibility snapshot for social media links.
3. Goose sends the results back to the LLM for interpretation.
4. Goose displays the final answer.

In this case, it interacted with a single MCP server, but you can add multiple servers to further extend Goose's capabilities.

In the desktop app, Goose also supports MCP Apps (an experimental feature), which let extensions show interactive user interfaces such as forms, data visualizations, and configuration wizards instead of text-only responses.

Beyond MCP servers, Goose supports Recipes, a way to package and share reusable AI workflows. A recipe is a YAML file that bundles instructions, a prompt, required extensions, parameters, and even retry logic into a shareable configuration.

Here's a simple recipe that generates a weekly status report:

version: "1.0.0"
title: Weekly Status Report
description: Generate a summary of work completed this week
instructions: |
  Analyze the git history and open issues to create a brief status report.
  Focus on commits from the past 7 days.
prompt: Summarize what I accomplished this week.
extensions:
  - type: builtin
    name: developer

The instructions tell the agent how to behave, while the prompt is the task it runs when you start the recipe from the CLI. Each entry under extensions is an object with a type and a name, not just the extension's name. You can check a recipe before running it:

goose recipe validate weekly-report.yaml

Run a recipe from the CLI:

goose run --recipe weekly-report.yaml

Recipes can include parameters for dynamic input (--params key=value), retry logic for automated validation, and sub-recipes for composing complex workflows. You can also schedule recipes to run automatically using cron expressions:

goose schedule add --schedule-id daily-report --cron "0 9 * * *" --recipe-source ./recipes/daily-report.yaml

The scheduler is built into Goose rather than your system's cron, so a schedule only fires while a long-running Goose process is up: the desktop app, or goose serve --enable-scheduler on a machine without it. Scheduled runs always use auto mode, whatever default you chose, so be careful with recipes that read text other people write, such as issues or web pages.

The Goose community shares ready-made recipes in the Recipes Cookbook, and you can browse MCP servers that work with Goose in the extensions directory.

Recipes are workflows that you start explicitly. Skills are the other half of the story: reusable instructions that Goose loads on its own when your request matches them. A skill is a directory with a SKILL.md file that has a name, a description, and the instructions:

---
name: release-notes
description: Draft release notes from the commits since the last tag
---

List the commits since the latest git tag, group them by type, and draft release notes in Markdown.

Goose discovers skills in ~/.agents/skills/ (global) and .agents/skills/ (per project), and it also reads the .claude/skills/ directories used by Claude Code. When I ran goose skills list in this blog's repository, it listed the Claude Code skills I use to maintain the blog alongside my global one, without any extra configuration. In a session, /skills lists them, and /skills release-notes loads one by name. If you want to see how far skills can go, check out Superpowers, a skills framework for coding agents.

One of my favorite features of Goose is its ability to connect to different LLM providers. So far we've used Google Gemini and a local Ollama model, but you may want to switch to a different provider for various reasons.

Let's try connecting to Groq, an LLM provider known for its speed. Groq runs open-weight models, such as OpenAI's gpt-oss, on its own Language Processing Unit (LPU) inference hardware, which makes it ideal for real-time AI tasks.

Groq offers a free plan too, but its tokens-per-minute limit (8,000 for gpt-oss-120b as of October 2026) is often too small for agent sessions. Goose sends the definitions of every enabled tool with each request, and a single MCP server like Playwright adds about two dozen of them.

To connect Goose to Groq, you need to create an account on the Groq website and obtain an API key. You can generate this key in the Groq cloud console:

Then run goose configure, choose Configure Providers, search for Groq, paste your API key, and select the default model, just like we did for Gemini. You can also switch providers in the middle of a session with /model --provider groq. Switching providers doesn't change anything else: your extensions, recipes, and skills keep working.

With so many AI coding agents available, you might wonder how Goose compares to the other terminal agents. Here's how it stacks up against Claude Code, OpenAI's Codex CLI, and OpenCode as of October 2026:

All four run locally in your terminal and work on your files; the difference is where the model runs and who controls the agent.

When to choose Goose: You want a free, fully open-source agent under neutral governance, with complete model flexibility (including local models), workflow automation via recipes, and no vendor lock-in.

When to choose Claude Code: You prefer a polished, ready-to-use experience built around Anthropic's Claude models and don't mind the subscription cost.

When to choose Codex CLI: You already pay for ChatGPT and want an open-source agent tuned for OpenAI's models.

When to choose OpenCode: You want another open-source, model-agnostic terminal agent with a polished text user interface; it's Goose's closest alternative.

What about Cursor? Cursor is primarily an AI-first IDE; it also has a CLI agent, but its strength is the editor, so it plays in a different category. Goose also ships as a native Agent Client Protocol (ACP) agent, so you can drive it from editors like Zed and JetBrains IDEs, narrowing the IDE-integration gap without giving up its open-source, model-agnostic core.

Is Goose completely free?

Yes. Goose is open source under the Apache 2.0 license with no subscription fees. However, you'll need access to an LLM provider. You can use a free tier (Google Gemini, Groq), a paid API, or run models locally with Ollama for a completely free setup.

Who maintains Goose now?

Block created Goose and contributed it to the Linux Foundation's Agentic AI Foundation (AAIF) in December 2025. Since April 2026, the code lives at github.com/aaif-goose/goose and the documentation at goose-docs.ai, replacing the old block.github.io/goose site.

Is Goose a free alternative to Claude Code?

For many tasks, yes. Both run locally in your terminal, but Goose is free, open source, and model-agnostic, while Claude Code is built for Anthropic's Claude models and requires a Claude subscription or API billing. Goose can also run entirely offline with a local model. Claude Code provides a more polished out-of-the-box experience.

Does Goose work on Windows?

Yes. Goose provides a desktop app for Windows, and you can install the CLI from PowerShell, Git Bash, or WSL, as shown in the Windows installation section.

Can I use Goose offline?

Yes, by pairing Goose with a local LLM provider like Ollama or using its built-in local inference. This gives you complete privacy and no rate limits, as long as your machine can run a capable model.

Which model works best with Goose?

Goose works best with models that are good at tool calling. Frontier cloud models give the most reliable results; for local use, pick the largest tool-calling model your hardware can run, as explained in the Ollama section.

What are MCP servers and do I need them?

MCP (Model Context Protocol) servers extend Goose's capabilities by connecting it to external tools and services. They're optional. You can add capabilities like browser automation, GitHub integration, or Kubernetes management without writing custom code.

How do I add an MCP server to Goose?

Run goose configure, select Add Extension, and enter the command that starts the server, or add it to the extensions section of your config.yaml file, as shown in the Playwright MCP section.

What's the difference between Goose recipes and skills?

A recipe is a YAML workflow that you start explicitly with goose run --recipe or on a schedule. A skill is a SKILL.md file with instructions that Goose loads on its own when your request matches it.

In this post, I introduced Goose, an open-source AI agent that runs on your machine, connects to dozens of LLM providers including Google Gemini, Groq, and local Ollama models, and extends its capabilities via MCP servers, recipes, and skills. I demonstrated how to install Goose on Linux, macOS, and Windows, configure Google Gemini or a local model, use Playwright MCP for browser automation, and automate workflows with recipes and skills.

Since its January 2025 release, Goose has grown up. As of October 2026, the project has published more than 120 stable releases, gained over 55,000 GitHub stars, and attracted more than 450 contributors. The MCP ecosystem has expanded to tens of thousands of servers covering developer tools (GitHub, VS Code, Docker), productivity suites (Google Drive, Asana, Slack), and specialized services like the Kubernetes MCP Server. Since the move to the Linux Foundation's Agentic AI Foundation, its development also happens under neutral governance, next to MCP and AGENTS.md, with backing from AWS, Anthropic, Google, Microsoft, OpenAI, and other industry leaders.

If you want an agent where you choose the model, the tools, and how much freedom it gets, Goose is a good place to start. This shift towards machine-based developers is reshaping how we think about developer tools and workflows.