Goose, an open source AI agent that runs locally

Goose is an AI agent you run on your own machine and that carries out tasks itself: reading files, running commands, making changes, and checking the result. Written in Rust, released under Apache 2.0, available both as a graphical application and a command line tool. The trait that sets it apart from the competition: you connect any model you like, including one running locally.

The project has a new owner

I will start with the change that invalidates most older material about this tool, including an earlier version of this text. Goose was created at Block, the company behind Square and Cash App, and no longer belongs to it.

In December 2025 the Linux Foundation announced the formation of the Agentic AI Foundation, and goose joined it alongside Anthropic's Model Context Protocol and OpenAI's AGENTS.md standard. The repository moved in April 2026: block/goose now redirects to aaif-goose/goose, and the documentation shifted to a separate domain.

The practical significance is larger than it looks. The project stopped being one company's tool and became a foundation project with documented governance. For a team weighing adoption, that lowers the risk of development stalling when a single sponsor's priorities change. The scale is serious too: over 52 thousand GitHub stars and releases roughly weekly, the latest tagged 1.45.0 on 29 July 2026.

This is not only a coding tool

The description circulating online reduces goose to a coding agent, and that undersells the project itself. The documentation speaks plainly of a general purpose agent, useful for research, writing, automation, and data analysis as well.

The difference is real because it follows from the architecture. The agent has no built in knowledge of repositories and gives code no special treatment. It has a set of tools it can call, and you supply those tools yourself through extensions speaking the MCP protocol. Connect it to spreadsheets and a mailbox and it becomes an office agent as naturally as a programming one.

That carries a consequence worth understanding before the first run. A tool of this class is only as good as the toolset you hand it, and only as safe as the permissions you grant along the way. An agent with shell access can do anything on your machine that you can.

Any model, including your own

This is the trait that leads people to pick goose over solutions tied to a single vendor. You configure which model the agent talks to, and the list covers commercial services as well as models running locally through Ollama.

Three things follow. The first is cost: for repetitive, simple tasks you can drop to a cheaper model and reserve the strong one for hard work. The second is confidentiality: code that cannot leave the company can be handled by a local model, paying for it in output quality. The third is resilience against one vendor's pricing changes, since switching models is a configuration edit rather than a rewrite of your workflow.

It is only fair to add that local models perform noticeably worse on agentic tasks than leading commercial ones. An agent has to hold a plan across many steps, call tools correctly, and notice its own mistakes, and those are precisely the abilities smaller models lose most of. Treat the local option as an answer to a confidentiality requirement rather than a way to save money.

Why Goose?

The problem with typical AI assistants

Most AI coding tools are:

Reactive - Wait for commands, don't take initiative
Fragmentary - Help with code snippets, not entire projects
Require supervision - Every step needs approval
Lack context - Don't remember previous decisions
Isolated - Don't integrate with developer tools

The Goose solution

Code

TEXT

┌─────────────────────────────────────────────────────────────┐
│                    GOOSE WORKFLOW                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐  │
│   │ ANALYZE │ -> │  PLAN   │ -> │  CODE   │ -> │  TEST   │  │
│   └─────────┘    └─────────┘    └─────────┘    └─────────┘  │
│        │                                             │       │
│        │              ┌─────────┐                    │       │
│        └──────────────│  DEBUG  │<───────────────────┘       │
│                       └─────────┘                            │
│                            │                                 │
│                       ┌─────────┐                            │
│                       │ DEPLOY  │                            │
│                       └─────────┘                            │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Key advantages

Full autonomy - Goose plans and executes on its own
Multi-LLM - Optimize costs and performance between models
MCP servers - Extend capabilities through integrations
Open-source - Full control over the code
Desktop + CLI - Choose your preferred interface
Rust core - Fast and secure

Installation

Desktop App (macOS/Windows/Linux)

Code

Bash

# macOS (Homebrew)
brew install --cask block-goose

# Or download from releases
# https://github.com/aaif-goose/goose/releases

CLI

Code

Bash

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

# Or through Homebrew
brew install block-goose-cli

# Verification
goose --version

Model configuration

Code

Bash

# Set API key
export ANTHROPIC_API_KEY=your_key
# or
export OPENAI_API_KEY=your_key

# Wizard for provider, model and extensions
goose configure

# Current configuration and file paths
goose info -v

Configuration file

~/.config/goose/config.yaml

YAML

# ~/.config/goose/config.yaml
active_provider: anthropic
providers:
  anthropic:
    enabled: true
    model: claude-sonnet-4-5-20250929
    configured: true

GOOSE_MODE: "smart_approve"
GOOSE_MAX_TURNS: 1000

extensions:
  developer:
    bundled: true
    enabled: true
    name: developer
    timeout: 300
    type: builtin

Basic usage

Interactive mode

Code

Bash

# Start a session in the current directory
goose session

# Goose will analyze the project and ask about the task
Goose: I've analyzed your project. It's a Next.js app with TypeScript.
         What would you like me to do?

> Add a dark mode toggle to the navbar

One-time task

Code

Bash

# Execute task without interactive mode
goose run -t "Create a REST API with Express and MongoDB"

# With instruction file
goose run -i tasks.md

Example tasks

Code

Bash

# Create project from scratch
goose run -t "Create a React + Vite + TypeScript todo app with Zustand state management"

# Refactoring
goose run -t "Refactor the auth module to use JWT instead of sessions"

# Debugging
goose run -t "The tests in src/api are failing. Find and fix the issues"

# Migration
goose run -t "Migrate this project from JavaScript to TypeScript"

# Code review
goose run -t "Review the PR changes and suggest improvements"

Autonomous workflow

Phase 1: Analysis

Code

TEXT

Goose: Analyzing your request...

Task: Create a REST API with Express and MongoDB
Requirements identified:
- Express.js server setup
- MongoDB connection and models
- CRUD endpoints
- Error handling
- Environment configuration
- Basic authentication

Phase 2: Planning

Code

TEXT

Goose: Here's my implementation plan:

1. Initialize Node.js project with TypeScript
2. Set up Express server with middleware
3. Configure MongoDB with Mongoose
4. Create User model with validation
5. Implement auth endpoints (register, login)
6. Add CRUD endpoints for resources
7. Write tests with Jest
8. Add Docker configuration

Proceed? [Y/n]

Phase 3: Implementation

Code

TEXT

Goose: Starting implementation...

[1/8] Initializing project...
      [ok] Created package.json
      [ok] Installed dependencies
      [ok] Set up TypeScript config

[2/8] Setting up Express...
      [ok] Created src/index.ts
      [ok] Added middleware (cors, helmet, morgan)
      [ok] Configured error handling

[3/8] Configuring MongoDB...
      [ok] Created database connection
      [ok] Added connection retry logic
      [ok] Created .env.example

... continuing autonomously ...

Phase 4: Testing

Code

TEXT

Goose: Running tests...

PASS  src/__tests__/auth.test.ts
  [ok] should register a new user (45 ms)
  [ok] should login with valid credentials (23 ms)
  [ok] should reject invalid credentials (12 ms)

PASS  src/__tests__/users.test.ts
  [ok] should create a user (34 ms)
  [ok] should get all users (21 ms)
  ...

Test Suites: 4 passed, 4 total
Tests:       18 passed, 18 total

Phase 5: Debugging (if needed)

Code

TEXT

Goose: Found an issue in user validation...

Error: ValidationError: User validation failed
Location: src/models/User.ts:23

Fixing...
[ok] Updated email regex pattern
[ok] Added proper error messages
[ok] Retesting...

All tests passing now.

Multi-LLM configuration

Goose lets you split the planning model from the executing one, and override both for a single run:

~/.config/goose/config.yaml

YAML

# ~/.config/goose/config.yaml
active_provider: anthropic
providers:
  anthropic:
    enabled: true
    model: claude-sonnet-4-5-20250929
    configured: true

# A separate model for planning mode (/plan)
GOOSE_PLANNER_PROVIDER: "openai"
GOOSE_PLANNER_MODEL: "gpt-4.1"

Code

Bash

# Override the provider and model for a single run
goose run --provider ollama --model llama3.2 -t "Summarise the changes in this directory"

MCP integration

Goose integrates with MCP (Model Context Protocol) servers:

Built-in servers

~/.config/goose/config.yaml

YAML

# ~/.config/goose/config.yaml
extensions:
  developer:
    bundled: true
    enabled: true
    name: developer
    timeout: 300
    type: builtin
  memory:
    bundled: true
    enabled: true
    name: memory
    timeout: 300
    type: builtin

Custom MCP server

Code

Bash

# Add an extension through the wizard: Add Extension
goose configure

# Attach an extension for a single session only
goose session --with-extension "uvx mcp-server-fetch"

# Enable built in extensions for the session
goose session --with-builtin "developer,computercontroller"

Use cases

Prototyping

Code

Bash

goose run -t "Create a full-stack prototype for a booking system with:
- Next.js frontend
- Supabase backend
- Calendar component
- Payment integration mockup"

# Goose will create a working prototype in ~30 minutes

Legacy code migration

Code

Bash

goose run -t "Migrate this Express.js API to NestJS:
- Keep the same endpoints
- Use TypeORM instead of Mongoose
- Add Swagger documentation"

Bug fixing

Code

Bash

goose run -t "Users report that file upload fails for images > 5MB.
Find the issue and fix it, then add appropriate tests."

Code review assistant

Code

Bash

goose run -t "Review PR #42 and:
- Check for security issues
- Identify performance problems
- Suggest improvements
- Create a summary"

Documentation generation

Code

Bash

goose run -t "Generate comprehensive documentation for this project:
- API documentation with examples
- Architecture overview
- Setup guide
- Contributing guidelines"

Goose vs alternatives

Feature	Goose	Claude Code	Aider	Cursor
Licence	Apache 2.0	closed	Apache 2.0	closed
Graphical interface	yes	no, terminal and editor	no	yes, an editor
Command line	yes	yes	yes	limited
Model provider choice	any, local included	Anthropic models	any	built in
MCP extensions	yes	yes	none	yes
Billing	API call costs	subscription or API	API call costs	subscription

Security

Approval mode

~/.config/goose/config.yaml

YAML

# ~/.config/goose/config.yaml
# auto, approve, chat or smart_approve
GOOSE_MODE: "approve"

# Detection of instructions injected into content the agent reads
SECURITY_PROMPT_ENABLED: true
SECURITY_PROMPT_THRESHOLD: 0.8

Tool permissions

Code

Bash

# Permission levels for individual tools, stored in permission.yaml
goose configure

# Restrict installable extensions to an approved list
export GOOSE_ALLOWLIST=https://example.com/goose-allowlist.yaml

Audit log

Code

Bash

# List saved sessions
goose session list

# Export a run for analysis
goose session export -n my-session --format json > audit.json

# Paths to configuration, sessions and logs
goose info -v

Troubleshooting

Goose stuck in a loop

Code

Bash

# Limit turns and repeated calls to the same tool
goose run --max-turns 10 --max-tool-repetitions 3 -t "Task..."

# Or permanently in ~/.config/goose/config.yaml
# GOOSE_MAX_TURNS: 20

API costs too high

Code

Bash

# Show the estimated token cost in the command line
export GOOSE_CLI_SHOW_COST=true

# Compact the context automatically once it passes a fill threshold
export GOOSE_AUTO_COMPACT_THRESHOLD=0.6

# Compact the conversation by hand during a session: the /compact command

MCP problems

Code

Bash

# Enable and disable extensions
goose configure

# Session diagnostics report for a bug report
goose session diagnostics -o diagnostics.json

# Full tool responses in the console
goose session --debug

MCP extensions and what really follows from them

The MCP protocol is the layer through which the agent reaches anything beyond its own reasoning. Without extensions it can converse; with them it can act, and they decide what this tool is good for in your particular case.

The base set covers file operations and running commands, the minimum needed to work with a repository. The rest is a catalogue of ready made servers, from repository and issue tracker access through databases to a browser and external services. There is more on the protocol itself and on writing your own servers in the MCP toolkit writeup. Of the ready made extensions, the GitHub MCP server is the one most often added, because it closes the widest gap: the agent sees files, but without it sees neither issues, nor change proposals, nor build pipeline results. It comes in a remote variant needing no installation and a local one taking your own token, useful with a self hosted GitHub install.

Restraint pays here, though, because the mechanism runs counter to intuition. Every connected extension adds its tool descriptions to the context sent on every step. Twenty extensions means several dozen tool descriptions in each call, which raises cost and, worse, degrades selection accuracy. A model choosing among five tools picks correctly almost every time; a model facing sixty starts making mistakes.

The practical rule is therefore to connect what the task actually needs and disable the rest. Separate configuration profiles for different kinds of work serve better here than one set covering everything. Reviewing a repository needs files and commands; a task spanning issues and deployment gets what it needs added, and you return to the base set when it is done.

What it actually costs

The tool itself is free, so the entire bill consists of model calls. That deceptively simple answer hides a trap worth understanding before your first long task.

The agent does not make one call per instruction. It makes as many as it needs steps, and every step sends a growing conversation history: file contents, command output, earlier attempts. A task solved in fifteen steps can burn more input tokens than twenty ordinary conversations with a model, because context grows with each turn of the loop.

Several practical rules follow. Phrase tasks narrowly, since an agent turned loose on an entire project will spend the budget reading files that have nothing to do with it. Work in a directory scoped to the relevant part of the repository rather than at the root of a monorepo. Interrupt a session circling the same error, because each further turn costs more than the last and rarely produces a breakthrough.

It is also worth pricing one task before you make this a permanent part of the team's work. Run a typical instruction, check token consumption on the provider's side, and multiply by expected tasks per day and by headcount. That number tells you more than any price list comparison.

Safety, what to think about beforehand

An agent executing commands on your machine is a different risk from an assistant suggesting code, and it is worth naming plainly rather than settling for a feature list.

The basic principle: the agent runs with your permissions. If you can delete a directory, upload a file, or push to a repository, so can it. Approval mode exists precisely to put a human in front of irreversible actions, and switching it off for convenience is a decision to make deliberately.

The second risk concerns the content the agent reads. A file in a repository, a page fetched from the web, or an issue description can carry instructions aimed at the model, and the agent has no built in way to distinguish a command from you from one found in data. That is not theory but a known attack class against systems of this kind. The practical conclusion: run the agent on repositories you trust, and treat its contact with external content as contact with untrusted data.

The third matter is secrets. An agent reading project files will also read the environment variable file, and its contents go into the context sent to the model provider. If you work on a repository holding production keys, exclude those files from scope or work with a local model.

Common mistakes

The first is too broad an instruction. A sentence like "improve the application's performance" gives the agent too much latitude and ends in changes across a dozen files nobody wants to review. The narrower the task, the better the odds of an acceptable result.

The second is working without version control or on a dirty working tree. The agent changes files in place, so without a clean reference point you cannot separate its edits from your own. Start a session from a clean state so a single command can undo everything.

The third is accepting changes without reading them. The agent can write code that compiles, passes tests, and does something other than what you intended. Reviewing its diff is the same activity as reviewing a colleague's code, and skipping it converts saved time into debt.

The fourth is adding extensions without checking what they do. Every MCP extension expands what the agent can reach, and some grant access to external services using your credentials. They deserve the same scrutiny as project dependencies, meaning check the source before installing.

The fifth is expecting the agent to handle a task you cannot define yourself. If you cannot describe what a good result looks like, you will not be able to judge what you get or correct course halfway through.

FAQ

Is Goose free?

The tool itself is, under Apache 2.0. You pay only for model calls at your chosen provider, and with a locally run model you pay nothing beyond electricity and hardware.

Does Goose still belong to Block?

No. The project originated at Block but was contributed to the Agentic AI Foundation at the Linux Foundation, and the repository moved to the aaif-goose organisation. The old address redirects to the new one.

Which models does it support?

Both commercial services and locally run models. You configure the choice and can change it without changing how you work, which distinguishes this tool from single vendor solutions.

Can I work without network access?

Yes, with a local model. Expect noticeably weaker results on multi step tasks, since holding a plan across many steps is the ability smaller models lose most of.

How does it differ from Claude Code?

Mainly in openness and freedom of model choice. Goose is Apache 2.0, offers a graphical interface alongside the command line, and talks to any provider. Claude Code is closed and tied to one vendor's models, but more deeply polished for work on code.

The source and releases live in the project repository, and details of the move under the foundation are in the Linux Foundation announcement.