Goose is Block's free, open-source AI agent that writes code, runs commands, and fixes its own errors. Here's how to install it, connect your model, and ship your first app.
This guide is reviewed for clarity, service accuracy, and AI-search readability. The next quarterly content review is tracked internally before unsupported metrics or client proof are added.
There's a free, open-source AI agent that doesn't just talk about code — it builds it. You describe what you want in plain English, and it writes the files, runs the commands, installs what it needs, and fixes its own errors until something real is running on your screen.
It's called Goose, built and open-sourced by Block (the company behind Square and Cash App). It's free, it runs on your own machine, and it works with whatever AI model you already trust.
This is the full guide. By the end you'll have Goose installed, connected to a model, and you'll have shipped your first working app just by asking for it. No prior coding experience required.
What Goose Actually Is (and Why It's Not a Chatbot)
A chatbot answers. An agent acts.
When you ask a normal AI chatbot to build something, it hands you a block of code and a pat on the back. You still have to create the files, install the right tools, run the commands, read the error messages, and paste them back to ask for a fix. You're doing the work — it's just narrating.
Goose closes that loop. It runs on your computer with permission to use it, so a single plain-language request turns into real action:
- It plans — breaks your request into steps before touching anything.
- It writes code — creates and edits the actual files on your machine.
- It runs commands — starts servers, runs scripts, executes the build.
- It installs dependencies — pulls in the libraries your project needs.
- It self-corrects — when something breaks, it reads the error, diagnoses it, and fixes it without you copy-pasting anything.
It's built in Rust for speed, it's licensed under Apache 2.0 (genuinely free and open), and it's general-purpose — people use it for code, research, writing, data analysis, and automation. The project has 45k+ GitHub stars, 500+ contributors, and is now stewarded by the open Agentic AI Foundation (AAIF).
The headline for solo founders: you're not renting this from anyone. Your code and your data stay on your machine unless you choose a cloud model. You bring your own AI key. There's no subscription and no vendor lock-in.
System Requirements + The Two Ways to Install
Goose comes in two flavors. You can install one or both.
- Goose Desktop — a native app for macOS, Windows, and Linux. Point-and-click setup. Best if you're new.
- Goose CLI — a terminal command. Best if you live in the terminal or want to script it.
What you need:
- macOS (Apple Silicon or Intel), Windows, or Linux.
- An internet connection for setup and for cloud models.
- An API key from an AI provider — or Ollama for a free local model (covered below).
- For the CLI on Windows, you'll want WSL (Windows Subsystem for Linux) for the smoothest experience.
Option A — Install Goose Desktop (recommended for beginners)
On macOS, the cleanest path is Homebrew, because it also handles updates:
promptbrew install --cask block-goose
Don't have Homebrew or prefer a direct download? Grab the right build for your Mac:
- macOS Apple Silicon:
https://github.com/aaif-goose/goose/releases/download/stable/Goose.zip - macOS Intel:
https://github.com/aaif-goose/goose/releases/download/stable/Goose_intel_mac.zip
Then:
prompt1. Unzip the downloaded file. 2. Double-click the app to launch Goose Desktop.
On Windows and Linux, download the Desktop build from the official downloads page (https://goose-docs.ai/docs/getting-started/installation) and run the installer.
macOS note: on some Apple Silicon Macs (M3), the window may not appear on first launch. Make sure your
~/.configdirectory has read and write access — Goose needs it to create its log files. Then relaunch.
Option B — Install the Goose CLI
On macOS or Linux, run the official install script:
promptcurl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
On Windows, run that same command inside WSL for the most reliable setup.
After it finishes, confirm it's installed:
promptgoose --version
If you get a "command not found," close and reopen your terminal so it picks up the new path, then try again.
First-Time Setup: Connect Your AI Model
Goose doesn't ship with a brain. You plug one in. This is a one-time step.
Desktop setup
- Launch Goose Desktop.
- When prompted, choose your model provider (for example, Anthropic for Claude).
- Paste your API key into the field and save.
That's it — you're ready to build. Get an API key from your provider's dashboard (for Anthropic, that's console.anthropic.com; for OpenAI, platform.openai.com).
CLI setup
Run the configuration wizard:
promptgoose configure
It walks you through:
prompt1. Choose a provider (e.g. Anthropic, OpenAI, Google, Ollama). 2. Pick a model. 3. Paste your API key when asked.
Then start a session and begin working:
promptgoose session
The free, fully local option
Don't want to pay for an API or send anything to the cloud? Use Ollama to run an open model entirely on your own machine.
- Install Ollama from
ollama.com. - Pull a model, for example:
promptollama pull llama3.1
- In
goose configure, choose Ollama as your provider. No API key needed.
This keeps everything 100% local and free. The trade-off: local models are generally less capable at the multi-step tool-calling Goose leans on, so results vary. Great for privacy and tinkering; cloud models like Claude are stronger for serious builds.
The Full List of Supported Model Providers
Goose is model-agnostic — it works with 15+ providers. Here are the main ones and when to pick each:
- Anthropic (Claude) — Recommended default. Goose relies heavily on tool calling and currently works best with Claude 4 models. Set
ANTHROPIC_API_KEY. - OpenAI (GPT) — Strong, well-rounded option. Set
OPENAI_API_KEY. - Google (Gemini) — Big context window, good value for large projects.
- Groq — Extremely fast inference when you want speed.
- Ollama — Free, local, private. No API key. Best for privacy and experimentation.
- OpenRouter — One key, access to many models. Handy for comparing models.
- Azure OpenAI — For teams already on Microsoft's cloud.
- Amazon Bedrock — Hosts Claude and others on AWS. Note: AWS credentials must be set as environment variables in advance, not through
goose configure. - Amazon SageMaker TGI — Run Text Generation Inference models via SageMaker endpoints (AWS creds required up front).
- Atomic Chat — Run local models through an OpenAI-compatible server.
You can also use your existing Claude, ChatGPT, or Gemini subscriptions instead of a separate API key, via Goose's ACP support — useful if you already pay for one of those.
Not sure which to pick? Start with Anthropic (Claude) for the best build quality, or Ollama if you want it free and local. You can switch anytime by re-running goose configure.
Your First Build: From Plain English to a Running App
Here's the moment that makes Goose click. You're going to describe an app and watch it get built, run, and debugged for you.
Open Goose (Desktop or a goose session in the terminal), then paste this:
promptBuild me a simple expense tracker web app. Let me add an expense with a name, amount, and category, show a running total, and save everything to a local file so my data persists between visits. Use plain HTML, CSS, and JavaScript so it runs in my browser with no build step. When it's finished, start a local server and open it so I can try it.
Here's what Goose does on its own:
- Plans — it lays out the steps: create the HTML structure, add the styling, write the JavaScript logic, set up local storage, then serve it.
- Writes the files — it creates
index.html,style.css, andapp.js(or similar) directly in a project folder on your machine. - Runs it — it starts a local web server and opens the app in your browser.
- Fixes its own errors — if the server throws an error or the totals don't add up, Goose reads the message, edits the code, and re-runs — no copy-pasting from you.
- Confirms — it tells you it's done and where the files live.
When it pauses to ask for permission to run a command or edit a file, approve it. That permission step is a safety feature, not a bug — Goose only acts on your machine when you say so.
If something isn't quite right, just talk to it:
promptThe total isn't updating when I delete an expense. Fix that, and make the buttons a bit bigger on mobile.
It edits the same project and re-runs. That back-and-forth — in plain English — is the whole workflow.
8 Ready-to-Use Prompts for Common Builds
Copy any of these into Goose to start a real project. Swap in your own details.
A web app:
promptBuild a single-page habit tracker. I want to add habits, check them off each day, and see a 7-day streak for each one. Save data locally so it persists. Plain HTML/CSS/JS, no frameworks. Run it when done.
A useful script:
promptWrite a Python script that scans a folder I give it, finds all images, and resizes any wider than 1200px down to 1200px while keeping the aspect ratio. Install any libraries it needs and run it on ~/Desktop/test.
A data tool:
promptI have a CSV of sales data with columns date, product, and amount. Build a small script that reads it, totals revenue per product, and outputs a clean summary table plus a simple bar chart saved as a PNG.
An automation:
promptCreate a script that renames every file in a folder to a consistent format: lowercase, spaces replaced with dashes, and a date prefix from the file's modified time. Show me a dry-run preview before renaming.
A simple API:
promptBuild a tiny REST API with one endpoint that takes a city name and returns a fake 3-day weather forecast as JSON. Use a lightweight framework, install dependencies, and start it locally so I can test it.
A landing page:
promptBuild a clean, modern one-page landing site for a productivity app called FocusFlow: hero headline, three feature cards, a pricing section, and an email signup form. Make it responsive and run it locally.
A personal utility:
promptMake a command-line tool that takes a YouTube-style transcript text file and outputs a bullet-point summary and 5 suggested social captions. Use my configured AI model for the summarizing.
A learning project:
promptTeach me by building: create a working to-do app in React, explain each file as you go, install what's needed, and run it. Keep it beginner-friendly.
Extensions and MCP Servers: Giving Goose More Reach
Out of the box, Goose can write and run code. Extensions let it reach into the rest of your world — files, the web, GitHub, databases, Google Drive, and more.
Goose does this through the Model Context Protocol (MCP), an open standard for connecting AI agents to external tools and data. Goose was one of the earliest adopters, and there are 70+ extensions available.
A few examples of what extensions unlock:
- GitHub — read issues, open pull requests, manage repos.
- Web / browser — fetch live information and interact with pages.
- File system — work across your local files and folders.
- Google Drive / databases / APIs — pull in real data to build against.
How to enable an extension:
In the CLI, run the configure wizard and choose the extensions menu:
promptgoose configure
prompt1. Select "Add Extension." 2. Pick a built-in extension or add one by command. 3. Provide any required keys or settings.
In Desktop, open Settings → Extensions, then toggle on the ones you want and enter any required credentials. Browse what's available in the official extensions directory on the Goose docs site.
Start minimal. Add an extension when a task actually needs it — for example, enable GitHub the day you want Goose to open a pull request for you.
Goose Desktop vs CLI: Which to Use
Both run the same engine. The difference is the interface.
Use Goose Desktop when:
- You're new and want a clean, visual setup.
- You like clicking through settings and seeing your session in a window.
- You want interactive UIs that some extensions can render right inside the app.
Use the Goose CLI when:
- You're comfortable in the terminal.
- You want to script Goose into your own workflows or run it on a server.
- You want the fastest, most keyboard-driven loop.
Most solo builders start on Desktop, then graduate to the CLI for speed once they're hooked. There's no wrong answer — install both and use whichever fits the moment.
Troubleshooting Checklist
When something stalls, work down this list.
API key / authentication errors:
- Re-run
goose configureand re-paste the key — watch for stray spaces or line breaks. - Confirm the right environment variable name for your provider (e.g.
ANTHROPIC_API_KEY,OPENAI_API_KEY). - Check that your provider account has billing enabled and credit available.
- For Amazon Bedrock/SageMaker, remember AWS credentials must be set as environment variables before launching — not inside
goose configure.
Rate limits:
- Slow down or wait a minute, then retry.
- Switch to a higher-tier plan with your provider, or to a different model/provider.
- Fall back to a free local model via Ollama to keep working.
Failed runs:
- Let Goose try again — it's designed to read errors and self-correct.
- Add context: tell it what you expected versus what happened.
- Approve the permission prompts; a blocked command can look like a failure.
- Restart the session if it gets confused, and restate the goal clearly.
Install / launch issues:
- "Command not found" after CLI install → restart your terminal so PATH updates.
- Desktop shows no window on an Apple Silicon Mac → grant read/write on
~/.config, then relaunch. - On Windows, run the CLI inside WSL if native install acts up.
Where to get help:
- Docs:
https://goose-docs.ai - GitHub (issues, code, releases):
https://github.com/aaif-goose/goose - Community Discord:
https://discord.gg/goose-oss
Why This One Is Actually Yours
Most AI tools rent you a window into someone else's system. Goose is different on the points that matter to a founder building lean:
- Open source (Apache 2.0) — the code is public, auditable, and free to use and modify.
- Runs locally — it works on your machine; nothing leaves it unless you choose a cloud model.
- Model-agnostic — bring your own key, swap providers anytime, or run fully local. No lock-in.
That combination means the agent building your apps answers to you, not a vendor's roadmap or pricing page. Go deeper any time at the docs (https://goose-docs.ai) and the source (https://github.com/aaif-goose/goose).
If you found this through Hypd, that's the whole point of what we share here — free, open tools that put real building power in your hands without a subscription. Install Goose, describe one small thing you've always wanted to exist, and let it ship.
FAQ
Do I need to know how to code to use Goose? No. You describe what you want in plain English and Goose writes, runs, and fixes the code for you. Knowing a little helps you give better instructions and spot when something's off, but your first build doesn't require it. Start with one of the example prompts above.
Is Goose really free? Yes — Goose itself is free and open-source under Apache 2.0, with no subscription. The only potential cost is the AI model behind it: cloud providers like Anthropic or OpenAI charge for API usage. If you want zero cost, run a local model with Ollama and you pay nothing at all.
Is it safe to let an AI run commands on my computer? Goose asks for permission before it runs commands or edits files, so you stay in control of every action. It also includes safety features like tool-permission controls and a sandbox mode. Start in a fresh project folder, review the prompts before approving, and you keep a clear boundary around what it can touch.