Frequently Asked Questions

Common questions about goose and their answers

Find answers to common questions about using goose, from basic setup to advanced features.

Getting Started

What is goose?

goose is an open-source, on-machine AI agent capable of automating complex development tasks from start to finish. Unlike simple code completion tools, goose can build entire projects, write and execute code, debug failures, orchestrate workflows, and interact with external APIs autonomously.

goose works with any LLM provider, supports multi-model configuration, integrates with MCP servers, and is available as both a desktop app and CLI tool.

Learn more: Introduction

How do I install goose?

goose is available in multiple formats:

Desktop App (Recommended for beginners):

• Download from the goose website
• Available for macOS, Linux, and Windows
• Includes built-in UI and automatic updates

CLI (For developers and automation):

# macOS/Linux
curl -fsSL https://github.com/block/goose/releases/latest/download/goose-install.sh | sh

# Windows (PowerShell)
irm https://github.com/block/goose/releases/latest/download/goose-install.ps1 | iex

From source:

git clone https://github.com/block/goose.git
cd goose
source bin/activate-hermit
cargo build --release

See the Installation Guide for detailed instructions.

Which LLM providers does goose support?

goose supports a wide range of LLM providers:

Cloud Providers:

• OpenAI (GPT-4, GPT-3.5)
• Anthropic (Claude 3.5 Sonnet, Opus, Haiku)
• Google Gemini
• GitHub Copilot
• Databricks
• Azure OpenAI
• Amazon Bedrock

Local Providers:

• Ollama (runs models locally)
• Any OpenAI-compatible API endpoint

Configure your provider with:

goose configure

Learn more: Providers

Do I need an API key?

Yes, you need an API key for your chosen LLM provider (except for local Ollama models).

Getting API keys:

• OpenAI: platform.openai.com/api-keys
• Anthropic: console.anthropic.com
• Google Gemini: aistudio.google.com/app/apikey
• GitHub Copilot: Requires GitHub subscription with Copilot access

Storing keys securely:

goose stores API keys in your system keyring by default (macOS Keychain, Windows Credential Manager, Linux Secret Service). You can also use environment variables:

export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"

See: Configuration

How much does it cost to use goose?

goose itself is free and open source. However, you pay for LLM API usage based on your provider’s pricing.

Cost considerations:

• Claude 3.5 Sonnet: ~$3 per million input tokens, ~$15 per million output tokens
• GPT-4: ~$10 per million input tokens, ~$30 per million output tokens
• GPT-3.5: ~$0.50 per million input tokens, ~$1.50 per million output tokens
• Gemini: Competitive pricing with free tier available
• Ollama (local): Free, but requires local compute resources

Cost optimization:

• Use lead/worker model configuration (expensive model for planning, cheaper for execution)
• Start sessions with clear, specific goals
• Use .goosehints to reduce context size
• Monitor usage in your provider’s dashboard

Learn more: Providers

Using goose

What can goose do?

goose can automate a wide range of development tasks:

Code Development:

• Build entire projects from scratch
• Write, refactor, and optimize code
• Generate tests and documentation
• Debug issues and fix bugs

DevOps & Automation:

• Set up CI/CD pipelines
• Configure development environments
• Manage Docker containers
• Deploy applications

Research & Analysis:

• Search documentation and codebases
• Analyze code quality and security
• Generate reports and summaries

Integration:

• Interact with GitHub, GitLab, Jira
• Query databases
• Call external APIs
• Use MCP servers for extended capabilities

See Tutorials for real-world examples.

How do I start a session with goose?

CLI:

# Start a new interactive session
goose session

# Resume a previous session
goose session resume --session-id <id>

# Run a specific task
goose session --task "Add tests for user authentication"

Desktop App:

1. Launch goose Desktop
2. Click New Session or press Cmd+N (macOS) / Ctrl+N (Windows/Linux)
3. Type your request in the chat input
4. Press Enter or click Send

Learn more: Sessions

What are extensions and how do I use them?

Extensions are tools that expand goose’s capabilities by integrating with external services and systems.

Built-in Extensions:

• Developer: File operations, shell commands, code execution
• GitHub: Repository management, PR creation, issue tracking
• Screen Control: UI automation and testing

MCP Server Extensions:

Extensions following the Model Context Protocol can be added from the community:

# In ~/.config/goose/config.yaml
extensions:
  github:
    cmd: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "your-token"

Managing Extensions:

• Desktop: Settings → Extensions → Enable/Disable
• CLI: Edit ~/.config/goose/config.yaml

Learn more: Extensions

What are recipes?

Recipes are reusable automation workflows that define specific tasks for goose to execute.

Example Recipe:

title: Add tests for a function
description: Generate comprehensive unit tests
instructions:
  - Analyze the function signature and implementation
  - Identify edge cases and boundary conditions
  - Write unit tests using the project's testing framework
  - Ensure 100% code coverage
  - Run tests and fix any failures

Running Recipes:

# CLI
goose recipe run my-recipe.yaml

# Desktop: File → Run Recipe

Use cases:

• Standardize team workflows
• Automate repetitive tasks
• Share best practices
• Schedule recurring tasks

Learn more: Recipes

How do I stop or interrupt goose?

CLI:

• Press Ctrl+C to interrupt the current task
• Type exit or quit to end the session

Desktop App:

• Click the Stop button in the chat interface
• Press Esc to cancel ongoing operations
• Close the session tab to end it

When to interrupt:

• goose is heading in the wrong direction
• You need to provide additional context
• A task is taking too long
• You notice an error or unexpected behavior

You can resume the session and provide corrections after interrupting.

Can goose edit my files? How do I prevent unwanted changes?

Yes, goose can and will edit files as part of its workflow.

Protecting Your Work:

1. Use version control (Git):

   # Stage your changes before running goose
   git add .
   git commit -m "My work before goose"
   
   # Review goose's changes
   git diff
   
   # Revert if needed
   git checkout .
   

2. Review before committing:

   • Leave goose’s edits unstaged
   • Review changes with git diff
   • Create separate commits for goose’s work

3. Use interrupts:

   • Stop goose if it’s making unwanted changes
   • Provide clearer instructions
   • Revert changes and try again

4. Limit scope:

   • Be specific about which files to modify
   • Use .goosehints to guide behavior
   • Start with small, focused tasks

Learn more: Best Practices

Configuration and Customization

Where does goose store its configuration?

goose uses platform-specific directories:

Configuration Files:

• macOS/Linux: ~/.config/goose/
• Windows: %APPDATA%\Block\goose\config\

Data and Sessions:

• macOS: ~/Library/Application Support/goose/
• Linux: ~/.local/share/goose/
• Windows: %LOCALAPPDATA%\Block\goose\

Logs:

• macOS/Linux: ~/.local/state/goose/logs/
• Windows: %LOCALAPPDATA%\Block\goose\logs\

Secrets:

• macOS: Keychain (credential named “goose”)
• Linux: System keyring (if available)
• Windows: Credential Manager

Learn more: Configuration Files

How do I use environment variables with goose?

Environment variables override configuration file settings:

Common Variables:

# Provider configuration
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-4"
export OPENAI_API_KEY="your-key"

# Lead/Worker models
export GOOSE_LEAD_MODEL="gpt-4"
export GOOSE_WORKER_MODEL="gpt-3.5-turbo"

# Network configuration
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1"

# Development
export GOOSE_PATH_ROOT="/tmp/goose-test"  # Isolated environment
export GOOSE_DISABLE_KEYRING=1  # Force file-based secrets

Making variables persistent:

Add to your shell configuration:

# ~/.bashrc or ~/.zshrc
export GOOSE_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="your-key"

Learn more: Environment Variables

Can I use multiple LLM providers or models?

Yes! goose supports multi-model configuration:

Lead/Worker Pattern:

Use a powerful model for planning and a faster/cheaper model for execution:

export GOOSE_LEAD_MODEL="claude-3-5-sonnet-20241022"
export GOOSE_WORKER_MODEL="claude-3-5-haiku-20241022"

Benefits:

• Lower costs (use expensive models only when needed)
• Faster execution (worker model handles routine tasks)
• Better quality (lead model handles complex reasoning)

Switching providers:

# Switch for a single session
GOOSE_PROVIDER=openai GOOSE_MODEL=gpt-4 goose session

# Or reconfigure
goose configure

Learn more: Custom Providers

What is .goosehints and how do I use it?

.goosehints is a file that provides project-specific context and guidelines to goose.

Example .goosehints:

# Project: My Web App

## Tech Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- Testing: Jest + React Testing Library

## Code Style
- Use functional components with hooks
- Prefer async/await over promises
- All functions must have JSDoc comments
- Test coverage must be >80%

## Important Files
- API routes: `src/routes/`
- Components: `src/components/`
- Tests: `src/__tests__/`

## Don't modify
- `config/production.json`
- `scripts/deploy.sh`

Benefits:

• Reduces token usage (concise context vs. full files)
• Guides goose’s behavior
• Enforces coding standards
• Prevents mistakes

Place .goosehints in your project root.

Learn more: Using Goosehints

How do I create custom extensions?

You can create custom extensions using the MCP protocol:

1. Create an MCP server:

// my-extension.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'my-extension',
  version: '1.0.0',
}, {
  capabilities: {
    tools: {},
  },
});

server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'my_tool',
    description: 'Does something useful',
    inputSchema: {
      type: 'object',
      properties: {
        input: { type: 'string' },
      },
    },
  }],
}));

server.setRequestHandler('tools/call', async (request) => {
  // Handle tool execution
});

const transport = new StdioServerTransport();
await server.connect(transport);

2. Configure in goose:

extensions:
  my-extension:
    cmd: node
    args: ["/path/to/my-extension.js"]

Learn more: Creating Extensions

Troubleshooting

goose is slow or unresponsive. What should I do?

Common causes and solutions:

1. Large context size:

   • Break tasks into smaller sessions
   • Use .goosehints instead of including full files
   • Clear old messages from long sessions

2. Slow LLM provider:

   • Switch to a faster model (e.g., GPT-3.5, Claude Haiku)
   • Check provider status page
   • Verify network connectivity

3. Extension issues:

   • Disable unused extensions
   • Check extension logs for errors
   • Update to latest extension versions

4. System resources:

   • Close other resource-intensive applications
   • Check disk space (logs can accumulate)
   • Monitor CPU/memory usage

If issues persist, generate a diagnostic report and check the logs.

How do I view logs or debug issues?

Generate a diagnostic report:

goose session diagnostics --session-id <id>

This creates a ZIP file with:

• System information
• Session data
• Recent logs (last 10 files)
• Configuration files

View logs manually:

# macOS/Linux
tail -f ~/.local/state/goose/logs/cli/$(date +%Y-%m-%d)/goose.jsonl

# Windows
Get-Content "$env:LOCALAPPDATA\Block\goose\logs\cli\$(Get-Date -Format yyyy-MM-dd)\goose.jsonl" -Wait

Filter for errors:

cat ~/.local/state/goose/logs/cli/*/goose.jsonl | jq 'select(.level=="ERROR")'

Learn more: Diagnostics and Debugging

Why won't my extensions activate?

Extensions may fail to activate for several reasons:

1. Missing package runners:

# Check if npx is installed (for Node.js extensions)
npx --version

# Check if uvx is installed (for Python extensions)
uvx --version

Install if needed:

• Node.js: Download from nodejs.org
• uv: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Network restrictions:

In corporate or airgapped environments, extensions can’t download dependencies. See Airgapped Environments.

3. Malicious package detection:

goose blocks extensions using packages flagged as malicious. Find alternative extensions or verify the package is safe.

4. Configuration errors:

# Incorrect
extensions:
  github:
    command: npx  # Wrong key

# Correct
extensions:
  github:
    cmd: npx
    args: ["-y", "@modelcontextprotocol/server-github"]

Learn more: Known Issues - Extensions

What should I do if goose gets stuck in a loop?

If goose enters a “doom spiral” or repeats the same actions:

Immediate actions:

1. Interrupt: Press Ctrl+C (CLI) or click Stop (Desktop)
2. Provide context: Add clarifying information about what went wrong
3. Restart if needed: End the session and start fresh

Prevention:

• Break large tasks into smaller, focused sessions
• Provide clear, specific instructions
• Use .goosehints to guide behavior
• Monitor progress and interrupt early if goose goes off-track

Example:

# Instead of:
"Build a full e-commerce website"

# Try:
"Create a product listing page with search and filters"

See: Known Issues - Stuck in a Loop

Where can I get help?

Community Support:

• Discord: Join our Discord community for real-time help
• GitHub Discussions: Ask questions in GitHub Discussions
• Twitter/X: Follow @goose_oss for updates

Documentation:

• Known Issues - Common problems and solutions
• Diagnostics - Debug tools and logging
• Guides - Detailed how-to guides

Report Bugs:

• File a bug report
• Include a diagnostic report for faster resolution
• Check existing issues first to avoid duplicates

Request Features:

• Submit a feature request
• Vote on existing feature requests
• Contribute via pull requests!

Advanced Topics

Can I use goose in CI/CD pipelines?

Yes! goose can be integrated into CI/CD workflows:

Example GitHub Actions:

name: goose Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install goose
        run: |
          curl -fsSL https://github.com/block/goose/releases/latest/download/goose-install.sh | sh

      - name: Run goose review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          goose recipe run review-pr.yaml

Use cases:

• Automated code reviews
• Test generation
• Documentation updates
• Security scanning
• Release note generation

Learn more: CI/CD Integration

How do I schedule recurring tasks?

goose supports scheduling recipes to run automatically:

Schedule a recipe:

goose schedule create \
  --recipe daily-tests.yaml \
  --cron "0 9 * * *" \
  --name "Daily Test Run"

List scheduled tasks:

goose schedule list

Remove a scheduled task:

goose schedule remove --name "Daily Test Run"

Common schedules:

• 0 9 * * * - Daily at 9 AM
• 0 */4 * * * - Every 4 hours
• 0 0 * * 0 - Weekly on Sunday midnight
• 0 0 1 * * - Monthly on the 1st

Learn more: Scheduling

Can I deploy goose as a server?

Yes! goose includes a server mode for team deployments:

Start the server:

export GOOSE_SERVER__SECRET_KEY="your-secret-key"
goosed agent  # or: just run-server

Connect from UI:

# Set server URL
export GOOSE_SERVER_URL="http://localhost:3000"
just debug-ui

Use cases:

• Team collaboration
• Centralized configuration
• Resource sharing
• Audit logging
• Access control

Learn more: Server Deployment

How do I build a custom goose distribution?

You can create custom distributions with pre-configured providers, extensions, and branding:

1. Fork the repository:

git clone https://github.com/your-org/goose.git
cd goose

2. Customize configuration:

• Update ui/desktop/package.json for branding
• Pre-configure config.yaml defaults
• Bundle custom extensions
• Add organization-specific .goosehints

3. Build:

source bin/activate-hermit
just release-binary
just bundle-desktop

Use cases:

• Enterprise deployments
• Team-specific configurations
• Airgapped environments
• Custom branding

Learn more: Custom Distributions

Still Have Questions?

If your question isn’t answered here:

1. Search the documentation - Use the search bar at the top
2. Check the guides - Browse User Guides for detailed topics
3. Join Discord - Ask the community at discord.gg/goose-oss
4. Review issues - Search GitHub Issues for similar questions
5. Start a discussion - Create a topic in GitHub Discussions

We’re here to help!