Goose

Goose is an open-source agentic AI platform that automates coding, DevOps, and system workflows through conversational interaction. Created by Block and now managed by the Agentic AI Foundation at the Linux Foundation, Goose integrates Model Context Protocol (MCP) extensions to extend AI capabilities across developer tools, cloud services, and local systems.

Installation

macOS (Homebrew)

brew install block/tap/goose
goose version  # Verify installation

Linux / macOS (Cargo)

cargo install goose-cli
goose version

Windows / Cross-Platform (Cargo)

cargo install goose-cli
goose version

Desktop Applications

Download platform-specific installers from the official Goose repository:

• macOS: .dmg installer
• Windows: .exe installer
• Linux: .AppImage or .deb package

Package Managers (Alternative)

# Using npm (if available)
npm install -g goose

# Using pipx (Python)
pipx install goose-cli

# Using cargo (recommended)
cargo install goose-cli

Quick Start

Starting an Interactive Session

goose  # Start interactive Goose session

Once in a session, prompt naturally:

> Create a Python script that checks if a port is open
> Modify the docker-compose.yml file to add a PostgreSQL service
> Refactor this JavaScript function for performance

Session Basics

# Start a new session
goose

# View session history
goose session list

# Resume previous session
goose session resume

# Exit session
exit

Basic Workflow

1. Start Goose: goose
2. Describe your task in natural language
3. Review suggested actions before approval (depending on mode)
4. Let Goose execute multi-step workflows autonomously

CLI Commands

Command	Description
goose	Start interactive session in default mode
goose configure	Configure API keys and LLM providers
goose session list	List all saved sessions
goose session resume <id>	Resume a previous session
goose session delete <id>	Delete a session
goose update	Update Goose to latest version
goose version	Display installed version
goose help	Show CLI help
goose run --recipe <file>	Execute automation recipe

Session Management Examples

# List all sessions with metadata
goose session list

# Resume specific session (shows recent interaction history)
goose session resume 1234abcd

# Start fresh session
goose

# Run headless recipe (no interactive prompts)
goose run --recipe automation.yaml

Slash Commands

Slash commands control Goose behavior within a session:

Command	Syntax	Purpose
/mode	/mode auto | /mode approve | /mode chat	Switch execution mode
/extension	/extension list | /extension add <name>	Manage extensions
/builtin	/builtin list	List built-in extensions
/plan	/plan	Show current action plan
/clear	/clear	Clear conversation history
/retry	/retry	Retry last action
/restart	/restart	Restart current task
/help	/help	Show command list

Slash Command Examples

> /mode auto
> /mode approve
> /extension list
> /builtin list
> /plan
> /clear
> /retry
> /restart

Configuration

Initial Setup

goose configure

This interactive command prompts for:

• Default LLM provider (OpenAI, Anthropic, Google, Ollama, OpenRouter)
• API keys for selected provider
• Default model selection
• Extension preferences

Setting API Keys

Environment Variables (Recommended)

# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Google
export GOOGLE_API_KEY="AIza..."

# Custom OpenRouter
export OPENROUTER_API_KEY="sk-or-..."

# Ollama (local)
export OLLAMA_BASE_URL="http://localhost:11434"

Via goose configure

goose configure

# Select provider: anthropic
# Enter API key when prompted
# Select default model: claude-3-5-sonnet

Configuration File Location

# macOS / Linux
~/.config/goose/config.yaml

# Windows
%APPDATA%\goose\config.yaml

Sample config.yaml

provider: anthropic
model: claude-3-5-sonnet
api_key: sk-ant-...
extensions:
  - developer
  - computeruse
  - memory
temperature: 0.7
max_tokens: 4096

Extensions (MCP)

Goose uses Model Context Protocol (MCP) to extend AI capabilities. Extensions provide tools for file operations, shell execution, cloud services, and specialized workflows.

Built-in Extensions

Extension	Purpose	Tools Provided
Developer	File editing, shell commands	edit files, run commands, create directories
Computeruse	GUI automation, screenshot capture	desktop control, visual task automation
Memory	Persistent knowledge storage	save/retrieve context between sessions
JetBrains	IntelliJ/PyCharm integration	code navigation, refactoring
Google Drive	Document/spreadsheet access	read/write Google Docs, Sheets, Drive files

Listing Extensions

# List available extensions
goose /builtin list

# In session: view all extensions
> /builtin list

# View loaded extensions
> /extension list

Adding Extensions

Enable Built-in Extension

> /extension add developer
> /extension add computeruse
> /extension add memory

Add Custom MCP Server

# Configure in config.yaml
extensions:
  - name: my-custom-server
    type: command-line
    command: python
    args:
      - /path/to/mcp_server.py

Or interactively:

> /extension add custom-server

Extension Types

# Built-in extension
- name: developer
  type: builtin

# Command-line MCP server
- name: postgres
  type: command-line
  command: npx
  args:
    - "@modelcontextprotocol/server-postgres"
    - "--connection-string"
    - "postgresql://user:pass@localhost/db"

# Remote MCP server
- name: remote-service
  type: remote
  url: "http://mcp-server:3000"

Profiles

Profiles let you switch between different extension sets and configurations for various workflows.

Creating a Profile

# ~/.config/goose/profiles.yaml
profiles:
  web-dev:
    model: claude-3-5-sonnet
    extensions:
      - developer
      - memory
    temperature: 0.5
    
  devops:
    model: claude-3-5-sonnet
    extensions:
      - developer
      - computeruse
    temperature: 0.7
    
  research:
    model: claude-3-sonnet
    extensions:
      - memory
      - google-drive
    temperature: 0.3

Switching Profiles

# Start with specific profile
goose --profile web-dev

# In session, switch profiles
> /profile switch devops

Recipes

Recipes enable headless automation and scripted workflows without interactive prompts.

Recipe File Format (YAML)

name: "Deploy API Service"
description: "Build, test, and deploy Node.js API"
steps:
  - task: "Review package.json and identify dependencies"
  - task: "Run npm install to install dependencies"
  - task: "Execute npm test to run test suite"
  - task: "Build Docker image with tag api:latest"
  - task: "Push image to registry"
  - task: "Update deployment manifest with new image"
  - task: "Apply Kubernetes changes with kubectl apply"
mode: approve
extensions:
  - developer
  - computeruse

Running Recipes

# Execute recipe file
goose run --recipe deploy-api.yaml

# Run with custom variables
goose run --recipe setup.yaml --vars '{"env":"production","region":"us-west-2"}'

# Run multiple recipes in sequence
goose run --recipe prep.yaml && goose run --recipe deploy.yaml

Recipe Examples

Python Project Setup

name: "Setup Python Project"
description: "Initialize Python project with dependencies and testing"
steps:
  - task: "Create src/ and tests/ directories"
  - task: "Create requirements.txt with Flask, pytest, black, flake8"
  - task: "Run pip install -r requirements.txt"
  - task: "Create pytest configuration in pyproject.toml"
  - task: "Add GitHub Actions CI workflow"
  - task: "Initialize git repository"
mode: approve

Docker Multi-Stage Build

name: "Build Multi-Stage Docker Image"
description: "Create optimized Node.js Docker image"
steps:
  - task: "Create Dockerfile with builder and runtime stages"
  - task: "Test build locally with docker build"
  - task: "Tag image as myapp:latest and myapp:v1.0"
  - task: "Push images to Docker registry"
mode: auto

Provider Configuration

OpenAI

# Set API key
export OPENAI_API_KEY="sk-proj-..."

# Configure in goose
goose configure
# Select: openai
# Model: gpt-4o or gpt-4-turbo

# Specify model in recipe
model: gpt-4o

Anthropic (Claude)

export ANTHROPIC_API_KEY="sk-ant-..."

goose configure
# Select: anthropic
# Model: claude-3-5-sonnet or claude-3-opus

# Most recommended for Goose
model: claude-3-5-sonnet

Google Gemini

export GOOGLE_API_KEY="AIza..."

goose configure
# Select: google
# Model: gemini-2.0-flash or gemini-1.5-pro

model: gemini-2.0-flash

Ollama (Local/Open-Source)

# Start Ollama service
ollama serve

# In another terminal, pull model
ollama pull mistral

# Configure Goose
export OLLAMA_BASE_URL="http://localhost:11434"

goose configure
# Select: ollama
# Model: mistral or llama2

model: mistral

OpenRouter (Multi-Provider)

export OPENROUTER_API_KEY="sk-or-..."

goose configure
# Select: openrouter
# Model: any OpenRouter model (claude-3-5-sonnet, gpt-4o, mistral, etc.)

model: claude-3-5-sonnet

Developer Extension

The Developer extension provides core file and system operations.

File Editing

# In Goose session:
> Create a file called utils.py with helper functions
> Modify src/index.js line 45 to add error handling
> Delete old test fixtures in tests/old/

Goose automatically:

• Creates/modifies files
• Maintains proper indentation
• Preserves file structure
• Validates syntax where applicable

Shell Commands

# Execute system commands
> Run npm test
> Check git status and show recent commits
> Install dependencies with pip install -r requirements.txt
> Build project with cargo build --release

Project Setup Tools

# Initialize project structure
> Create a Python project with src/, tests/, and docs/ directories

# Generate configuration files
> Create .gitignore for Node.js projects
> Add ESLint and Prettier configuration

# Set up development tools
> Create GitHub Actions workflow for CI/CD
> Initialize Docker with Dockerfile and docker-compose.yml

Advanced Usage

Custom MCP Server Creation

Create a Python-based MCP server:

# custom_mcp_server.py
from mcp.server import Server
from mcp.types import Tool

server = Server("my-custom-server")

@server.tool()
def get_system_info():
    """Get system information"""
    import platform
    return f"OS: {platform.system()}, Python: {platform.python_version()}"

@server.tool()
def execute_query(query: str):
    """Execute database query"""
    # Custom logic here
    return f"Results for: {query}"

if __name__ == "__main__":
    server.run()

Register in config.yaml:

extensions:
  - name: custom-server
    type: command-line
    command: python
    args:
      - /path/to/custom_mcp_server.py

Docker Integration

# Build Docker container with Goose
> Create Dockerfile for Python service with health checks
> Build with docker build -t myservice:latest .
> Test container with docker run --rm myservice:latest

# Docker Compose automation
> Generate docker-compose.yml with PostgreSQL, Redis, and Node.js services
> Set environment variables and networks
> Validate with docker-compose config

Headless Automation (CI/CD)

#!/bin/bash
# ci-deploy.sh

# Export credentials
export ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}

# Run deployment recipe
goose run --recipe deploy.yaml

# Check exit code
if [ $? -eq 0 ]; then
  echo "Deployment successful"
else
  echo "Deployment failed"
  exit 1
fi

API Mode (Programmatic Access)

# Use Goose as a library
from goose import Goose

goose = Goose(
    provider="anthropic",
    model="claude-3-5-sonnet"
)

result = goose.execute("Create a Python CLI tool for file processing")
print(result.output)

Troubleshooting

API Key Not Found

# Verify environment variable
echo $ANTHROPIC_API_KEY

# Or set directly in config
goose configure
# Enter API key when prompted

# Check config file permissions
ls -la ~/.config/goose/config.yaml

MCP Server Connection Failed

# Verify MCP server is running
ps aux | grep mcp

# Test MCP connection
mcp-client --connect localhost:3000

# Check firewall/port access
netstat -an | grep 3000

Session Not Resuming

# List all sessions
goose session list

# Check session ID format
goose session resume <full-session-id>

# If corrupted, start fresh
goose

Out of Context/Token Limits

# Clear conversation history
> /clear

# Or start new session
exit
goose

# Reduce max_tokens in config.yaml
max_tokens: 2048

Extension Not Loading

# Verify extension in config
cat ~/.config/goose/config.yaml

# List available extensions
goose /builtin list

# Restart Goose
exit
goose

Best Practices

1. Start with Specific Tasks

✓ "Create a Python script that validates CSV files"
✗ "Do something useful"

2. Use Profiles for Different Workflows

• Web Development: Lower temperature (0.3-0.5)
• DevOps: Standard temperature (0.7)
• Brainstorming: Higher temperature (0.8-0.9)

3. Leverage Recipes for Repeated Tasks

# Save common workflows as recipes
goose run --recipe weekly-backup.yaml
goose run --recipe security-audit.yaml

4. Test Before Production

# Use /mode approve to review actions
> /mode approve

# Verify changes before proceeding
# Then switch to /mode auto for efficiency
> /mode auto

5. Organize Extensions by Purpose

extensions:
  - developer      # Always needed
  - memory         # Preserve context
  - computeruse    # For GUI tasks
  # Add only necessary extensions to reduce overhead

6. Monitor Token Usage

# Use lower token limits for quick tasks
max_tokens: 1024

# Use higher for complex work
max_tokens: 4096

7. Use Sessions for Long-Running Tasks

# Resume interrupted work
goose session resume previous-id

# Maintain context across multiple interactions

Related Tools

Tool	Purpose	Integration
Claude (Anthropic)	Primary LLM provider	Via ANTHROPIC_API_KEY
OpenAI GPT-4	Alternative LLM	Via OPENAI_API_KEY
MCP (Model Context Protocol)	Extension framework	Native support
Ollama	Local LLM execution	Via OLLAMA_BASE_URL
Docker	Container automation	Via Developer extension
GitHub Actions	CI/CD workflows	Can be configured by Goose
Kubernetes	Orchestration automation	Via kubectl commands
Terraform	Infrastructure as Code	Via Developer extension
VS Code	Code editor integration	Via JetBrains extension
Google Drive	Document storage	Via Google Drive extension