Yes. Goose is open source under the Apache-2.0 license and costs nothing. You pay your model provider for the tokens it uses, or run a local model through Ollama, LM Studio or Docker Model Runner at no token cost.

Block created Goose and contributed it to the Agentic AI Foundation (AAIF) under the Linux Foundation in December 2025. Since April 2026 the code lives at github.com/aaif-goose/goose and the docs at goose-docs.ai.

Can Goose use my Claude Code or ChatGPT subscription?

Yes, through ACP providers, which let Goose drive an existing Claude Code or ChatGPT Plus/Pro login. The older CLI providers that did this are deprecated in favour of ACP providers.

Does Goose read AGENTS.md or CLAUDE.md?

Goose reads AGENTS.md and then .goosehints at each level from the working folder up to the git root. To also load CLAUDE.md or .cursorrules, add them to the CONTEXT_FILE_NAMES environment variable.

Does Goose ask before running commands?

Not by default. The default mode is auto, which runs tools without asking. Approve mode asks before every tool call, smart_approve asks only for risky ones, and chat mode turns tools off.

How to use Goose: a step-by-step guide to the Goose CLI

To use Goose, you install the CLI with curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash, answer the goose configure questions to choose a provider and a model, then run goose session inside a project and describe what you want. Goose starts in auto mode, so it runs commands without asking until you switch to approve mode.

This guide covers each step for the Goose CLI as of November 2026 (version 1.58): install, setup, modes, sessions, extensions, instructions files and recipes, plus the mistakes that cost people the most time.

What Goose is

Goose is a general-purpose AI agent that runs on your machine. It comes as a CLI, a desktop app for macOS, Linux and Windows, and an API, all built in Rust. It is model-agnostic: you bring a provider such as Anthropic, OpenAI, Gemini, OpenRouter or a local model, and Goose does the tool calling, editing and shell work.

Block created Goose and contributed it to the Agentic AI Foundation under the Linux Foundation in December 2025, together with MCP and AGENTS.md. In April 2026 the repository moved to aaif-goose/goose and the docs to goose-docs.ai. Older links to block/goose and block.github.io/goose still redirect. It is released under Apache-2.0, and new versions come out about once a week.

Step 1: install the CLI

On macOS, Linux, or Git Bash on Windows:

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

On macOS you can use Homebrew instead. The package names still say “block”:

brew install block-goose-cli        # CLI
brew install --cask block-goose     # desktop app

On Windows PowerShell:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"; .\download_cli.ps1

The Windows binary lands in %USERPROFILE%\.local\bin, which you may need to add to PATH. Update later with goose update. The CLI and the desktop app share one configuration, so providers and extensions you set in one show up in the other.

Step 2: run goose configure

The first run starts goose configure by itself. You get three paths: sign in to OpenRouter, sign in to Tetrate Agent Router Service, or configure manually by choosing a provider, pasting its key and naming a model. Since version 1.54 it also asks which mode to start in.

Keys go into your system keyring (the Keychain on macOS). If there is no keyring, or you set GOOSE_DISABLE_KEYRING, they go to a plain-text secrets.yaml instead. You can also export them:

export ANTHROPIC_API_KEY=...
export GOOSE_PROVIDER=anthropic
export GOOSE_MODEL=claude-sonnet-5-5

A key written into config.yaml is ignored. Run goose configure again any time to change the provider, add or toggle extensions, or open the settings for mode and tool permissions.

If you already pay for Claude Code or ChatGPT Plus/Pro, look at ACP providers: they let Goose use that login instead of an API key.

Step 3: start a session

cd my-project
goose session -n checkout-fix

Describe the task in plain words. Useful keys and commands inside a session:

Ctrl+J adds a new line; Ctrl+C stops the current request, or exits on an empty line.
/mode, /model, /extension and /builtin change the setup without leaving.
/compact shortens the conversation when it gets long; /clear starts over.
/status shows the session, including its ID.

To come back later, run goose session -r -n checkout-fix. goose session list shows every session, and --fork copies one so you can try a different direction without losing the original.

Step 4: choose a mode before real work

Goose has four modes:

Mode	What it does
`auto` (default)	Runs every tool without asking
`approve`	Asks before every tool call
`smart_approve`	Asks only for calls it rates as risky
`chat`	No tools; talk only

Switch with /mode approve in a session, set GOOSE_MODE, or pick a default in goose configure. For finer control, set permissions per tool in goose configure; they are saved in permission.yaml. On a repository you care about, start in approve or smart_approve and loosen it once you trust the setup.

Step 5: extensions and MCP servers

Extensions are how Goose gets tools, and every MCP server is an extension. The Developer extension (shell and file editing) is on by default. Others built in include Computer Controller, Memory and Auto Visualiser.

To add one for good, run goose configure → Add Extension and choose a command-line (stdio) or remote (Streamable HTTP) server. For a single session:

goose session --with-extension "memory:npx -y @modelcontextprotocol/server-memory"
goose session --with-streamable-http-extension https://example.com/mcp

Saved extensions live under extensions: in ~/.config/goose/config.yaml (Windows: %APPDATA%\Block\goose\config\config.yaml). SSE servers are no longer supported; use Streamable HTTP.

Step 6: AGENTS.md and .goosehints

Goose reads AGENTS.md, then .goosehints, at every level from the working folder up to the git root, and picks up nested ones as it works in subfolders. A global file at ~/.config/goose/.goosehints applies to every project.

If your project already has a CLAUDE.md, you don’t need to copy it:

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

Keep the file short: the stack, how to run tests, what not to touch, and what “done” means. Our guide to CLAUDE.md and AGENTS.md covers what to put in it.

Step 7: goose run and recipes

For one-off tasks without a chat, use goose run:

goose run -t "add a unit test for the price formatter"
goose run -i task.md --output-format json

A recipe is a YAML file that saves a task with its instructions, extensions and parameters, so a teammate or a scheduled job can repeat it:

goose run --recipe release-notes.yaml --params version=2.4.0
goose schedule add --schedule-id weekly-notes --cron "0 0 9 * * 1" --recipe-source release-notes.yaml

goose recipe validate checks a file before you share it. Two other commands worth knowing: goose review asks for an AI review of your git diff, and goose info -v shows the version and where the config, sessions and logs are.

Common pitfalls

Leaving auto mode on. The default runs shell commands without asking. Switch modes before the first task on a real repository.
Following old docs. Tutorials from 2025 point to block/goose and block.github.io. The commands mostly still work, but current docs are at goose-docs.ai.
Putting keys in config.yaml. Goose ignores them there. Use the keyring, goose configure or environment variables.
Using the deprecated CLI providers. To run on a Claude Code or ChatGPT login, set up an ACP provider instead.
Long sessions. Auto-compaction keeps the context under control, but a fresh named session per task keeps answers sharper.

Running Goose next to other CLIs in AgentVera

Goose has its own desktop app, and if Goose is the only agent you use, it may be all you need. It gets harder when Goose runs next to Claude Code, Codex or Gemini CLI on the same project. AgentVera is a desktop app that runs these CLIs side by side in real terminals, with your own installs and keys. Goose support works like this:

One named session per agent. Each Goose agent gets its own session name, and AgentVera reopens it with goose session --resume --name on later launches, so the conversation survives an app restart.
Your provider and keys. Goose keeps using the provider from goose configure. Under Settings → Accounts you can add API-key accounts (Anthropic, OpenAI, OpenRouter, Google) for Goose agents.
Model, effort and role. The model you pick is passed with --model, the effort level through GOOSE_THINKING_EFFORT, and the agent’s role with --system.
MCP and the browser. Servers from AgentVera’s MCP manager are passed as --with-extension or --with-streamable-http-extension, so you set them once for every CLI.
Panes, worktrees and review. Run Goose in the workspace grid next to other agents, each in its own git worktree, and check their changes with code review.

The free plan includes up to 18 agents, MCP, Git, Docker, SSH, code review and token savings. Pro is $9.99 a month; if you have never had a trial, your first sign-in to the app turns on Pro for 7 days with no card. To try it, download AgentVera.

Wrapping up

Goose takes three commands to start: install, goose configure, goose session. The settings that matter most come right after: switch from auto to approve mode, add the extensions you need, and give the project an AGENTS.md. Once a task repeats, save it as a recipe.

Sources: Goose installation, CLI commands, permissions, extensions, hints files, releases.