Goose by Block — Complete Guide

Sections explored

0 / 15

Get Started

What Is Goose?

The autonomous, local-first AI agent

Key Points

Open-source autonomous AI agent built by Block (the company behind Square & Cash App), released under Apache 2.0
Goes far beyond code suggestions — it installs, executes, edits files, runs tests, calls APIs and self-corrects until a task is complete
Runs 100% locally on your machine — your data never leaves it
Works with any LLM: Claude (recommended), GPT, Gemini, or local Ollama
Connects to tools via MCP (Model Context Protocol) extensions — available as both a Desktop GUI and a CLI

Why It's Different

Local-first — maintains context across a whole session, plans a sequence of actions, executes them and iterates on the results. Any LLM — Block recommends Claude 4 models for best performance, since Goose relies heavily on tool-calling. Not a chatbot — it does the work, it doesn't just talk about it. Free & open-source · 27K+ GitHub stars.

✦ Open SourceApache 2.0Local-FirstAny LLM

Installation

Desktop app or CLI — mac / Linux / Windows

Key Points

Desktop app is recommended for beginners — download, unzip, run (macOS, Linux, Windows)
macOS users can install via Homebrew: brew install --cask block-goose
The CLI is for power users — one install script on macOS, Linux and WSL
Linux ships as .deb, .rpm and Flatpak packages
Keep Goose current with goose update

Commands

# CLI — macOS / Linux / WSL curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash # Homebrew (macOS CLI) brew install block-goose-cli # Homebrew (macOS Desktop) brew install --cask block-goose # Linux .deb sudo dpkg -i goose_*.deb # Keep updated goose update

Desktop GUICLIHomebrewLinux .deb / .rpm / Flatpak

Configuration & LLM Provider Setup

Connect Goose to a model

Key Points

After install you must connect Goose to an LLM provider — run goose configure
Three quick paths: OpenRouter login (200+ models, pay-per-use), Tetrate Agent Router ($10 free credits), or manual with your own API key
Pick any provider — Anthropic Claude, OpenAI, Google Gemini, or local Ollama
Persist API keys across sessions by exporting them in your shell profile
Re-run goose configure → Configure Providers any time to switch model or provider

Commands

# Launch the config wizard goose configure # Example manual flow (Gemini) Which model provider? → Google Gemini GOOGLE_API_KEY → •••••••••••• Enter a model → gemini-2.0-flash-exp Configuration saved successfully # Persist a key across sessions echo 'export OPENAI_API_KEY=your_api_key' >> ~/.bashrc source ~/.bashrc # Change provider / model later goose configure → "Configure Providers"

OpenRouterTetrate · $10 freeManual API KeyClaude Recommended

Starting Your First Session

Desktop input box or goose session

Key Points

Desktop: open the app, choose your provider, type your task — Goose starts working immediately
CLI: navigate to your working directory and run goose session
Name a session with -n so you can resume it later
Speak in plain natural language — describe the outcome, not the steps

Commands

# New interactive session goose session # Named session goose session -n my-project # Example instruction > Add a health check endpoint to the FastAPI app and write a test for it

Natural LanguageNamed SessionsRun From Any Folder

Daily Driver

Core CLI Commands Reference

Sessions · tasks · info · scheduling

Key Points

Session management: start, name, resume, fork, list, export and remove sessions
Non-interactive runs: feed Goose a file (-i) or a single prompt (-t) for scripted, one-shot tasks
System & info: check version, config location and storage paths with goose info
Scheduling: register recipes on a cron and trigger or inspect them on demand

Commands

# Sessions goose session --resume -n my-project goose session --resume --fork --name my-project goose session list --limit 10 goose session export -n my-session -o session.md goose session remove -n my-project # Non-interactive tasks goose run -i plan.md goose run -t "your prompt here" goose run --no-session -i instructions.txt # System & info goose info # version, config, storage paths goose info -v # detailed config goose --version # Scheduling goose schedule list goose schedule run-now --schedule-id daily-report goose schedule remove --schedule-id daily-report

Resume & ForkHeadless RunsExport to MarkdownCron Scheduling

Extensions (MCP Servers)

How Goose plugs into your tools

Key Points

Extensions add capabilities by connecting Goose to external tools — in Goose's terms, MCP servers are called extensions
Built-in: developer (files, code, shell) and computercontroller (browser & desktop apps)
Add them via goose configure → Add extension, or inline when starting a session
Popular use cases: GitHub PRs & issues, Google Drive, Jira, Selenium/browser, Square API, AWS CloudWatch
Browse the official list at block.github.io/goose and community servers at pulsemcp.com

Commands

# Add via wizard goose configure → "Add extension" # Inline at session start goose session --with-builtin developer goose session --with-extension "npx -y @modelcontextprotocol/server-memory" goose session --with-streamable-http-extension "http://localhost:8080/mcp" # During an active session /builtin developer /extension npx -y @modelcontextprotocol/server-memory # Find more https://block.github.io/goose/v1/extensions/ https://www.pulsemcp.com/servers

developer (built-in)computercontrollerGitHub · Jira · DriveMCP Ecosystem

Recipes — Reusable AI Workflows

Bookmark your perfect session

Key Points

Recipes package your extensions, instructions, prompt and settings into a reusable, shareable file — the most powerful Goose automation feature
Create from Desktop: Settings → Make Agent From This Session, then name it and edit the instructions
Create from CLI: run /recipe my-recipe.yaml inside an active session to capture it
Validate, run, parameterise and share recipes; generate a deep link for Desktop users
Schedule a recipe on a cron for daily reports, nightly tests or recurring analysis

Commands & YAML

# Capture current session as a recipe /recipe my-recipe.yaml # Validate · run · parameterise goose recipe validate recipe.yaml goose run --recipe recipe.yaml goose run --recipe recipe.yaml --params repo_name=my-app goose recipe deeplink recipe.yaml goose recipe list --verbose # recipe.yaml (shape) version: 1.0.0 title: "Code Review Assistant" description: "Reviews PRs and suggests improvements" instructions: | You are a code review expert... activities: - "Review the latest open PR" extensions: - type: builtin name: developer params: - key: repo_name input_type: string # Schedule it goose schedule add --schedule-id daily-report \ --cron "0 0 9 * * *" \ --recipe-source ./recipes/daily-report.yaml

ReusableShareable Deep LinksParameterisedCron-Schedulable

Interactive Session Slash Commands

Press / + Tab to see them all

Key Points

/plan enters plan mode — Goose drafts a step-by-step plan before acting; /endplan exits
/mode switches agent behaviour (auto, approve, chat, smart_approve) mid-session
/compact summarises and compresses the conversation to free up context
/recipe saves the session; /builtin and /extension add capabilities on the fly
/prompts, /skills, /clear, /t (theme) and /exit round out the set

Slash Commands

/help or /? show help menu /plan <msg> plan before acting /endplan exit plan mode /recipe [path] save session as recipe /mode <name> auto · approve · chat · smart_approve /builtin <name> add built-in extensions /extension <cmd> add a stdio extension /compact compress the conversation /clear clear chat history /prompts list extension prompts /skills list available skills /t toggle theme (light/dark/ansi) /exit or /quit leave the session

Plan ModeMode SwitchingContext Compaction

Power & Context

Context Engineering with .goosehints

Stop repeating yourself every session

Key Points

.goosehints files tell Goose about your project and preferences — auto-included in every conversation
Project-level: create .goosehints in your project directory for stack, code style and common tasks
Global: place it at ~/.config/goose/.goosehints to apply to all sessions
Use clear headers and bullet points — structured hints parse far better than prose

Example .goosehints

# Project: eatcookjoy-uae.com ## Stack - Frontend: React + Tailwind CSS - Backend: Node.js + Express - Database: PostgreSQL ## Code Style - Use async/await, not callbacks - Prefer functional components - API responses: { success, data, error } ## Common Tasks - Run tests: npm test - Deploy: npm run deploy:staging # Global hints location ~/.config/goose/.goosehints

Project + GlobalAuto-IncludedStructured = Better

Keyboard Shortcuts (CLI)

Move faster in the terminal

Key Points

Ctrl+C clears the line, interrupts a request, or exits the session
Ctrl+J adds a newline for multi-line input
Ctrl+R / Ctrl+S reverse / forward search through command history
Cmd+Up / Cmd+Down navigate previous commands

Shortcuts

Ctrl+C clear line / interrupt / exit Ctrl+J add a newline (multi-line) Ctrl+R reverse search history Ctrl+S forward search history Cmd+Up/Down navigate previous commands

InterruptMulti-Line InputHistory Search

Goose Agent Modes

How much autonomy to grant

Key Points

auto — Goose acts fully autonomously, executing every step without pausing
approve — asks for confirmation before each action
chat — responds conversationally without executing any tools
smart_approve — auto-approves low-risk actions, prompts on high-risk ones
Switch any time mid-session with /mode <name>

Modes

auto run everything, no pauses approve confirm before each action chat talk only, no tool execution smart_approve auto low-risk, prompt high-risk # Switch during a session /mode approve

autoapprovechatsmart_approve

Apply It

Top Use Cases

Where Goose earns its seat

For Developers

Code migration — convert between frameworks (Ember → React, Ruby → Kotlin)
Onboarding — quickly understand unfamiliar codebases
Testing — generate unit tests and push coverage above a target
Debugging — fix issues and re-run tests until they pass
API scaffolding — endpoints, Datadog monitors, feature flags

For Automation & Business

Data analysis — feed Goose a CSV, get visualisations + an HTML report, no data-science skills needed. MCP → business tools — connect to Square inventory and manage it in natural language. SRE / DevOps — query AWS CloudWatch logs, reason about incidents, automate first response. Scheduled workflows — turn one-off tasks into cron-scheduled automations via recipes. Email automation — build email MCP servers to send payment links automatically.

MigrationTesting & DebugData → ReportSRE / DevOps

Where Goose Stores Data

Config, sessions, recipes & plugins

Key Points

Config lives in ~/.config/goose/config.yaml (Windows: %APPDATA%\Block\goose\)
Sessions are kept in a local sessions.db under ~/.local/share/goose/sessions/
Scheduled recipes sit in ~/.local/share/goose/scheduled_recipes/
Plugins install to ~/.agents/plugins/<name>/; global hints at ~/.config/goose/.goosehints

Locations (Unix)

Config ~/.config/goose/config.yaml Sessions DB ~/.local/share/goose/sessions/sessions.db Scheduled recipes ~/.local/share/goose/scheduled_recipes/ Plugins ~/.agents/plugins/<plugin-name>/ Global hints ~/.config/goose/.goosehints

Local ConfigSQLite SessionsPortable Recipes

Goose Roadmap (Coming Soon)

Where the project is headed

Key Points

Sub-agent orchestration — spawn multiple specialised agents in parallel
Dynamic model switching — agents change LLMs mid-task based on cost or capability
Self-improving recipes — Goose maintains and refines its own recipe collection
Unified UI — multiple active agents, project workspaces and recipe management in one view
Containerized agents — run Goose inside Docker for isolated, reproducible environments

Note

Roadmap items are actively in development and may change. Track the live roadmap and releases on the official GitHub: https://github.com/block/goose Goose ships updates frequently — run goose update to stay current.

Sub-AgentsModel SwitchingContainerized

Recommended Getting Started Flow

The fastest path to value

Do These In Order

Install the Desktop app, then configure one provider (Anthropic Claude or OpenRouter)
Run a test task in a safe directory — e.g. "Analyze this CSV and create a summary"
Enable the developer extension to unlock file & code operations
Add a project .goosehints so Goose knows your codebase
Create your first recipe from a successful session, then schedule it if it recurs

Checklist

1. Install Desktop (mac / Linux / Windows) 2. goose configure → pick a provider 3. Run a safe test task 4. Enable the developer extension 5. Add project .goosehints 6. /recipe to save a winning session 7. goose schedule add for recurring work 8. Explore extensions: GitHub, Drive, Jira…

Start SafeHints → RecipeThen Schedule

Want an AI agent doing the work in your business?

I build local-first AI agents, automations and fast websites for Gulf SMEs — using tools like Goose, Claude and n8n. Let's map your highest-ROI workflow.

Talk on WhatsApp →

Goose by Block — The Full Guide

Want an AI agent doing the work in your business?