How to Start Using Goose

After work you may want a local-first open-source agent that can edit files, run shell commands, and grow through MCP extensions — without locking you to one cloud IDE. Goose (also documented historically under Block’s Goose project at block.github.io/goose) is an extensible on-machine agent with both a desktop app and a CLI. It talks to many LLM providers (OpenAI, Anthropic, Google, Ollama, and more) and adds tools through MCP “extensions.”

This post is an evening CLI start plus one tiny Python task. Recipes, deep extension catalogs, and desktop polish can wait.

What Goose is

Per goose-docs.ai, Goose runs on your machine with access to your development environment, connects to tools via MCP, and is available as desktop + CLI. Core ideas: providers (LLM backends), extensions (MCP servers — GitHub, Slack, databases, etc.), sessions, recipes (reusable task templates), and project hints (.goosehints / AGENT.md). Built-in developer tooling covers shell, file edits, and code analysis. Config typically lives under ~/.config/goose/ (profiles.yaml, config.yaml).

Goose originated at Block and is maintained as open source under the Agentic AI Foundation ecosystem — use the current install URLs on goose-docs.ai rather than outdated mirrors.

Who it is for

Learners who are comfortable installing a CLI, can supply at least one provider API key (or a local Ollama model), and want an agent that stays on their laptop. Prefer hosted agents if you will not manage providers tonight. Prefer Goose when local control and MCP extensibility matter more than a polished SaaS onboarding wizard.

Start steps (one evening)

1. Install the CLI. From official docs: curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash. On macOS you can also brew install --cask block-goose for the desktop app; desktop installers for other OSes are linked from the installation docs. Confirm the goose command is available in a new terminal.
2. Configure a provider. Run the project’s configure flow (commonly goose configure / first-run prompts — follow the providers guide). Pick one provider you already have keys for, or Ollama if you want fully local inference.
3. Start in a practice directory. cd into a disposable Python folder and start a CLI session (see CLI commands for the current session entry command).
4. Orient, then one edit. Ask Goose what the folder contains. Then request a single bounded change and watch the tool calls.
5. Verify yourself. Run python on the file. Do not enable a pile of extensions until the base loop works.

First tiny exercise (15–20 minutes)

Create numbers.py:

def mean(values):
    return sum(values) / len(values)

if __name__ == "__main__":
    print(mean([2, 4, 6]))

Start Goose in that folder. Ask: Add a median for a non-empty list, call it from main after mean, keep the file under 40 lines, explain before editing.

Then:

python numbers.py

End the session when outputs look right. Leave recipes and extra MCP extensions for another evening.

Common pitfalls

• No provider configured. The binary alone cannot think; finish provider setup before blaming Goose.
• Too many extensions night one. MCP is powerful; each server adds auth and failure modes when you are tired.
• Production secrets in a practice session. Use a throwaway folder and keys with least privilege.
• Skipping local verification. Always run python (or tests) yourself after agent edits.
• Following stale URLs. Prefer goose-docs.ai install commands; community mirrors drift.

Next: Python under the agent

Goose can automate chores. You still read every diff. Introduction to Python Programming supports after-work learners. Check the course page for the current enrollment window.

Tonight: install, one provider, one small edit, one successful python run. Stop on that win.