> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<AccordionGroup>
  <Accordion title="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](/introduction)
  </Accordion>

  <Accordion title="How do I install goose?">
    goose is available in multiple formats:

    **Desktop App (Recommended for beginners):**

    * Download from the [goose website](https://block.github.io/goose)
    * Available for macOS, Linux, and Windows
    * Includes built-in UI and automatic updates

    **CLI (For developers and automation):**

    ```bash theme={null}
    # 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:**

    ```bash theme={null}
    git clone https://github.com/block/goose.git
    cd goose
    source bin/activate-hermit
    cargo build --release
    ```

    See the [Installation Guide](/installation) for detailed instructions.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    goose configure
    ```

    Learn more: [Providers](/concepts/providers)
  </Accordion>

  <Accordion title="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](https://platform.openai.com/api-keys)
    * **Anthropic**: [console.anthropic.com](https://console.anthropic.com)
    * **Google Gemini**: [aistudio.google.com/app/apikey](https://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:

    ```bash theme={null}
    export OPENAI_API_KEY="your-key-here"
    export ANTHROPIC_API_KEY="your-key-here"
    ```

    See: [Configuration](/configuration)
  </Accordion>

  <Accordion title="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](/concepts/providers)
  </Accordion>
</AccordionGroup>

## Using goose

<AccordionGroup>
  <Accordion title="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](/quickstart) for real-world examples.
  </Accordion>

  <Accordion title="How do I start a session with goose?">
    **CLI:**

    ```bash theme={null}
    # 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](/concepts/sessions)
  </Accordion>

  <Accordion title="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:

    ```yaml theme={null}
    # 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](/concepts/extensions)
  </Accordion>

  <Accordion title="What are recipes?">
    Recipes are reusable automation workflows that define specific tasks for goose to execute.

    **Example Recipe:**

    ```yaml theme={null}
    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:**

    ```bash theme={null}
    # 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](/concepts/recipes)
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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)**:
       ```bash theme={null}
       # 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](/concepts/architecture)
  </Accordion>
</AccordionGroup>

## Configuration and Customization

<AccordionGroup>
  <Accordion title="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](/configuration)
  </Accordion>

  <Accordion title="How do I use environment variables with goose?">
    Environment variables override configuration file settings:

    **Common Variables:**

    ```bash theme={null}
    # 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:

    ```bash theme={null}
    # ~/.bashrc or ~/.zshrc
    export GOOSE_PROVIDER="anthropic"
    export ANTHROPIC_API_KEY="your-key"
    ```

    Learn more: [Environment Variables](/guides/environment-variables)
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    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:**

    ```bash theme={null}
    # Switch for a single session
    GOOSE_PROVIDER=openai GOOSE_MODEL=gpt-4 goose session

    # Or reconfigure
    goose configure
    ```

    Learn more: [Custom Providers](/guides/custom-providers)
  </Accordion>

  <Accordion title="What is .goosehints and how do I use it?">
    `.goosehints` is a file that provides project-specific context and guidelines to goose.

    **Example `.goosehints`:**

    ```markdown theme={null}
    # 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](/configuration)
  </Accordion>

  <Accordion title="How do I create custom extensions?">
    You can create custom extensions using the MCP protocol:

    **1. Create an MCP server:**

    ```javascript theme={null}
    // 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:**

    ```yaml theme={null}
    extensions:
      my-extension:
        cmd: node
        args: ["/path/to/my-extension.js"]
    ```

    Learn more: [Creating Extensions](/guides/creating-extensions)
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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](/troubleshooting/diagnostics) and check the logs.
  </Accordion>

  <Accordion title="How do I view logs or debug issues?">
    **Generate a diagnostic report:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    # 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:**

    ```bash theme={null}
    cat ~/.local/state/goose/logs/cli/*/goose.jsonl | jq 'select(.level=="ERROR")'
    ```

    Learn more: [Diagnostics and Debugging](/troubleshooting/diagnostics)
  </Accordion>

  <Accordion title="Why won't my extensions activate?">
    Extensions may fail to activate for several reasons:

    **1. Missing package runners:**

    ```bash theme={null}
    # 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](https://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](/troubleshooting/known-issues#airgapped-offline-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:**

    ```yaml theme={null}
    # Incorrect
    extensions:
      github:
        command: npx  # Wrong key

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

    Learn more: [Known Issues - Extensions](/troubleshooting/known-issues#extension-issues)
  </Accordion>

  <Accordion title="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:**

    ```bash theme={null}
    # 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](/troubleshooting/known-issues#goose-stuck-in-a-loop)
  </Accordion>

  <Accordion title="Where can I get help?">
    **Community Support:**

    * **Discord**: Join our [Discord community](https://discord.gg/goose-oss) for real-time help
    * **GitHub Discussions**: Ask questions in [GitHub Discussions](https://github.com/block/goose/discussions)
    * **Twitter/X**: Follow [@goose\_oss](https://x.com/goose_oss) for updates

    **Documentation:**

    * [Known Issues](/troubleshooting/known-issues) - Common problems and solutions
    * [Diagnostics](/troubleshooting/diagnostics) - Debug tools and logging
    * [Guides](/guides/cli-usage) - Detailed how-to guides

    **Report Bugs:**

    * [File a bug report](https://github.com/block/goose/issues/new?template=bug_report.md)
    * Include a diagnostic report for faster resolution
    * Check existing issues first to avoid duplicates

    **Request Features:**

    * [Submit a feature request](https://github.com/block/goose/issues/new?template=feature_request.md)
    * Vote on existing feature requests
    * Contribute via pull requests!
  </Accordion>
</AccordionGroup>

## Advanced Topics

<AccordionGroup>
  <Accordion title="Can I use goose in CI/CD pipelines?">
    Yes! goose can be integrated into CI/CD workflows:

    **Example GitHub Actions:**

    ```yaml theme={null}
    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](/guides/recipes)
  </Accordion>

  <Accordion title="How do I schedule recurring tasks?">
    goose supports scheduling recipes to run automatically:

    **Schedule a recipe:**

    ```bash theme={null}
    goose schedule create \
      --recipe daily-tests.yaml \
      --cron "0 9 * * *" \
      --name "Daily Test Run"
    ```

    **List scheduled tasks:**

    ```bash theme={null}
    goose schedule list
    ```

    **Remove a scheduled task:**

    ```bash theme={null}
    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](/api/cli/schedule)
  </Accordion>

  <Accordion title="Can I deploy goose as a server?">
    Yes! goose includes a server mode for team deployments:

    **Start the server:**

    ```bash theme={null}
    export GOOSE_SERVER__SECRET_KEY="your-secret-key"
    goosed agent  # or: just run-server
    ```

    **Connect from UI:**

    ```bash theme={null}
    # 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](/advanced/server-deployment)
  </Accordion>

  <Accordion title="How do I build a custom goose distribution?">
    You can create custom distributions with pre-configured providers, extensions, and branding:

    **1. Fork the repository:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    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](/advanced/custom-distributions)
  </Accordion>
</AccordionGroup>

## 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](/guides/cli-usage) for detailed topics
3. **Join Discord** - Ask the community at [discord.gg/goose-oss](https://discord.gg/goose-oss)
4. **Review issues** - Search [GitHub Issues](https://github.com/block/goose/issues) for similar questions
5. **Start a discussion** - Create a topic in [GitHub Discussions](https://github.com/block/goose/discussions)

We're here to help!