DEV Community

Cover image for Getting started with Goose on Windows
Lymah
Lymah

Posted on

Getting started with Goose on Windows

#goose #ai #opensource #mcp

Table of Contents

Introduction

Goose is an open source, extensible AI agent that transforms how developers work by going beyond simple code suggestions. It can install packages, execute commands, edit files, and test code, all powered by your choice of LLM. While Goose has traditionally been more prevalent on macOS and Linux, Windows support has matured significantly, making it a powerful tool for Windows developers.
This comprehensive guide will walk you through installing, configuring, and optimizing Goose on Windows systems, addressing platform-specific challenges and best practices.

What is Goose?

Before diving into installation, let's understand what makes Goose special. Goose is an AI-powered development assistant that operates locally in your environment, integrating seamlessly with your existing tools. Unlike traditional AI coding assistants that only suggest code, Goose can:

  • Execute commands in your terminal
  • Read and modify files in your project
  • Install dependencies and run tests
  • Interact with APIs and databases
  • Work with any LLM provider you choose

The tool is available in two forms: a desktop application with a graphical interface and a command-line interface (CLI) for terminal enthusiasts.

Windows Installation Options

Goose offers multiple installation paths on Windows, each suited to different workflows and preferences. Let's explore both options.

A. Option 1: Goose Desktop (Recommended for Beginners)

The desktop application provides the easiest entry point, especially if you prefer a visual interface or are new to command-line tools.

Installation Steps:

  1. Navigate to the official Goose installation page
  2. Download the Windows ZIP file for Goose Desktop
  3. Extract the ZIP file to a location of your choice (e.g., C:\Program Files\Goose or your user directory)
  4. Run the executable file to launch the application
  5. Keep the executable accessible—consider creating a desktop shortcut or pinning it to your taskbar

A walkthrough

  1. This is what the extracted file will look like. Click on the file with the Goose icon from the folder. Image 1
  2. Create a shortcut for easier access:
    • Right-click on the Goosefile. Image 2
    • Select "Send to" → "Desktop (create shortcut)" Image 3
    • Now you can launch Goose from your desktop. Image 4

First Launch

When you first open Goose Desktop, you'll be greeted with a provider configuration screen. This is where you'll select your LLM provider and enter your API key. The interface is intuitive:
Image 5

  • Use the provider dropdown to select your preferred service (OpenAI, Google Gemini, Anthropic Claude, etc.) Image 6
  • Authorize your AI agent. Image 7
  • Authorize your created API key when prompted Image 8
  • Click Submit to complete the setup Image 9
  • Boom! Your Goose Desktop is launched. Image 10

The desktop interface features a clean chat-style interface where you can type instructions, upload files, do all sort of things and Goose will execute tasks immediately.

B. Option 2: Goose CLI (For Power Users)

The CLI version integrates directly with your terminal workflow, making it ideal for developers who live in the command line. Windows users have three approaches for running the Goose CLI.

Method 1: Native Windows Installation

This method installs Goose natively on Windows, providing the best performance and integration.
Prerequisites:
You'll need one of these environments:

  • Git Bash (recommended): Comes bundled with Git for Windows
  • MSYS2: A Unix-like environment for Windows
  • PowerShell: Built into Windows 10/11

The installation script requires curl and unzip to be available. Git Bash includes these by default, making it the simplest choice for most users.

Installation:
Open Git Bash, MSYS2, or PowerShell and run:

curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash
Enter fullscreen mode Exit fullscreen mode

To install without interactive configuration, disable CONFIGURE

curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash
Enter fullscreen mode Exit fullscreen mode

Once the installation was successful. Now you need to add the binary to your PATH. Since you're using Git Bash on Windows, add this line to your ~/.bashrc:
export PATH="/c/Users/user/.local/bin:$PATH"

Here's how to do it:

# Add to .bashrc
echo 'export PATH="/c/Users/user/.local/bin:$PATH"' >> ~/.bashrc

# Reload your shell
source ~/.bashrc

# Verify goose is now available
goose --version
Enter fullscreen mode Exit fullscreen mode

Image 11

After reloading, run the configuration:
goose configure

Configuring Your LLM Provider
Goose works with multiple LLM providers, giving you flexibility in terms of cost, performance, and features. Here's how to set up your provider on Windows.

Image 12

Follow the prompts to complete the configuration until you see a successful configuration in your terminal.

Image 13

Start interacting with Goose in your terminal with is command. goose start

Image x

You can now:

  • Ask questions about the codebase
  • Request code changes
  • Generate tests
  • Review code
  • Get explanations

Try some commands like:

  • "What can you do?"
  • "Explain the structure of this project"
  • "Help me understand how the agent system works"
  • "Show me the available MCP extensions" The context bar shows token usage: ○○○○○○○○○○ 0% (0/400000 tokens)

Tips:

  • Press Enter to send your message
  • Press Ctrl-J for a new line (multi-line input)
  • Type your instructions or questions at the ( O)> prompt

Critical Windows-Specific Note

When prompted during configuration, choose NOT to store credentials in the keyring. Windows keyring integration can be problematic with Goose. Instead, you'll set your API keys as environment variables.

Method 2: Windows Subsystem for Linux (WSL)

While the native installation is recommended, WSL provides a full Linux environment that some developers prefer.

Installation Steps

  1. Open PowerShell as Administrator
  2. Install WSL with the default Ubuntu distribution: 
wsl --install
Enter fullscreen mode Exit fullscreen mode
  1. Restart your computer if prompted
  2. Launch Ubuntu: 
wsl -d Ubuntu
Enter fullscreen mode Exit fullscreen mode

Image xx

  1. Install Goose in the Linux environment: 
curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash
Enter fullscreen mode Exit fullscreen mode

If you encounter extraction errors, install bzip2:

sudo apt update && sudo apt install bzip2 -y
Enter fullscreen mode Exit fullscreen mode

WSL Considerations

  • File system performance can be slower when working with files in Windows directories (accessed via /mnt/c/)
  • Use WSL's native file system (~/ in Ubuntu) for better performance
  • You'll need to launch WSL each time you want to use Goose
  • Windows and WSL maintain separate environments, which can complicate some workflows

Windows-Specific API Key Setup

On Windows (especially with native installation), keyring storage can be unreliable. The best practice is to use environment variables.
Setting Environment Variables:

export OPENAI_API_KEY=your_actual_api_key_here
Enter fullscreen mode Exit fullscreen mode

To make this permanent, add it to your bash configuration:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
echo 'export OPENAI_API_KEY=your_actual_api_key_here' >> ~/.bashrc
source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

For PowerShell (session-only)

$env:OPENAI_API_KEY="your_actual_api_key_here"
Enter fullscreen mode Exit fullscreen mode

For PowerShell (permanent)

[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'your_actual_api_key_here', 'User')
Enter fullscreen mode Exit fullscreen mode

After setting the environment variable, run goose configure again. Goose will detect the existing environment variable and display:

● OPENAI_API_KEY is set via environment variable

Choosing an LLM Provider

Goose supports numerous providers, each with different strengths:
Free/Low-Cost Options

  • Google Gemini: Offers a generous free tier, excellent for getting started
  • Groq: Fast inference with limited free usage

Premium Options

  • OpenAI: GPT-4o and o1 models, industry-leading performance
  • Anthropic Claude: Strong reasoning and coding capabilities
  • Tetrate Agent Router Service: Managed routing with $10 in free credits for new users

Consider your needs:

  • Starting out? Use Google Gemini's free tier
  • Professional development? GPT-4o or Claude Sonnet provide excellent results
  • Budget-conscious? Monitor your usage and set up billing alerts

Rate Limits and API Management

Most providers implement rate limits on API usage. This is especially important to understand when using Goose, as complex tasks may generate multiple API calls in quick succession.

Best Practices:

  • Start with smaller, focused tasks to understand usage patterns
  • Monitor your API usage through your provider's dashboard
  • Set up billing alerts to avoid unexpected charges
  • Consider using cheaper models for routine tasks and premium models for complex work
  • Use Goose's multi-model configuration to optimize cost and performance

Running Your First Goose Session

As I mentioned above, I will make Desktop, CLI, and general explanation in this section.

With configuration complete, you're ready to start using Goose. The experience differs slightly between Desktop and CLI.

Desktop Usage

Launch the Goose Desktop application. After the initial provider setup, you'll see a chat interface. Simply type your request in the input field:
Example Tasks:

  • "Create a Python script that fetches weather data from an API"
  • "Review the code in src/main.py and suggest improvements"
  • "Set up a new React project with TypeScript"
  • "Debug the error in my test suite" Goose will process your request, execute necessary commands, and provide results directly in the interface.

CLI Usage

Navigate to your project directory in your terminal (Git Bash, MSYS2, or PowerShell) and start a session:

cd /c/Users/YourName/projects/my-project
goose session
Enter fullscreen mode Exit fullscreen mode

You'll enter an interactive session where you can converse with Goose. The AI agent has full context of your current directory and can execute commands, read files, and make modifications.

Example Interaction:

You: Create a new FastAPI project with basic CRUD endpoints for a todo app

Goose: I'll help you set up a FastAPI project with CRUD endpoints. Let me start by creating the project structure...

[Goose creates files, installs dependencies, and sets up the project]

Goose: I've created a complete FastAPI project with:
- Project structure with proper organization
- CRUD endpoints for todos (GET, POST, PUT, DELETE)
- Pydantic models for validation
- In-memory storage (ready to connect to a database)
- requirements.txt with FastAPI and Uvicorn

You can run the server with: uvicorn main:app --reload
Enter fullscreen mode Exit fullscreen mode

To exit a session, press Ctrl+C.

Windows-Specific Optimizations and Best Practices

Path and Directory Considerations

Windows uses backslashes (\) for paths, while Unix-like systems use forward slashes (/). When using Git Bash or MSYS2, you'll typically use Unix-style paths:

# Windows path
C:\Users\YourName\projects\app

# Git Bash/MSYS2 equivalent
/c/Users/YourName/projects/app

# PowerShell (use Windows paths)
C:\Users\YourName\projects\app
Enter fullscreen mode Exit fullscreen mode

Goose handles path conversions automatically in most cases, but being aware of this helps troubleshoot issues.

Permission Issues

Windows security can sometimes interfere with Goose's file operations. If you encounter permission errors:

  • Run as Administrator: Right-click your terminal and select "Run as Administrator"
  • Check folder permissions: Ensure your user account has full control over the project directory
  • Antivirus software: Some antivirus programs flag script execution; you may need to add exclusions

The ~/.config directory is particularly important. Goose stores configuration and logs here. If the Desktop app doesn't launch or shows no window, verify this directory has read and write permissions.

Performance Tips

  • Use SSD storage: Place your projects on an SSD for faster file operations
  • Disable real-time scanning: Configure antivirus to exclude your development directories
  • Git Bash vs PowerShell: Git Bash generally provides better compatibility with Unix-oriented tools
  • Resource allocation: Goose uses LLM APIs that may take seconds to respond; be patient with complex requests

Firewall and Network Configuration

Goose makes HTTPS requests to LLM provider APIs. Ensure:

  • Windows Firewall allows outbound HTTPS connections
  • Corporate proxy settings are configured if necessary
  • VPN software doesn't block API access

For corporate environments, you may need to configure proxy
settings in your environment variables:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
Enter fullscreen mode Exit fullscreen mode

Working with Extensions

Goose's extensibility is one of its most powerful features. Extensions add new capabilities, from browser automation to specialized development tools.

Managing Extensions

CLI

goose configure
# Select "Configure Extensions"
Enter fullscreen mode Exit fullscreen mode

Desktop

  1. Click the menu button (top-left)
  2. Open Settings
  3. Navigate to Extensions
  4. Add, configure, or toggle extensions

Useful Extensions for Windows Developers

  • Computer Controller: Enables browser automation and UI interaction (useful for testing web apps)
  • Developer Tools: Enhanced code analysis and refactoring
  • Database Extensions: Direct database queries and management

Extensions are stored in the shared configuration file at ~/.config/goose/config.yaml, so they work across both Desktop and CLI interfaces.

Troubleshooting Common Windows Issues

Issue: Command Not Found After Installation

Problem: After installing, typing goose returns "command not found"
Solution:

  1. Ensure ~/.local/bin is in your PATH: 
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode
  1. Restart your terminal
  2. Verify installation: 
which goose
   goose --version
Enter fullscreen mode Exit fullscreen mode

Issue: API Key Not Persisting

Problem: Goose keeps asking for your API key each session
Solution:
This typically happens when keyring storage fails. Use environment variables instead (see the configuration section above). Make sure to add the export command to your ~/.bashrc file for permanence.

Issue: Slow Performance or Timeouts

Problem: Goose takes a very long time to respond or times out
Solution:

  • Check your internet connection and API provider status
  • Some models are slower than others; try a faster model (e.g., GPT-4o-mini instead of GPT-4o)
  • Check if you've hit rate limits with your provider
  • Increase timeout settings in extensions if applicable

Issue: Desktop App Won't Launch

Problem: Goose Desktop executable runs but no window appears
Solution:

  • Check ~/.config directory permissions
  • Look for logs in ~/.config/goose/logs/
  • Try running from a terminal to see error messages
  • Ensure antivirus isn't blocking the application

Issue: WSL File Access Errors

Problem: Goose can't access files in Windows directories
Solution:

  • Use the /mnt/c/ path to access Windows drives from WSL
  • Copy projects to WSL's native file system for better performance
  • Ensure proper line ending configuration (Git's core.autocrlf setting)

Updating Goose

Keep Goose up to date to benefit from bug fixes and new features.
CLI Update

goose update
Enter fullscreen mode Exit fullscreen mode

Desktop Update

Download the latest version from the releases page and replace your existing installation. The update process is straightforward since all configuration is stored separately in ~/.config/goose/.

Best Practices for Windows Users

Development Workflow Integration

  • Use Git Bash: For the most seamless experience with Unix-oriented development tools
  • Organize projects: Keep projects in a dedicated directory with short paths (e.g., C:\dev\projects\)
  • Version control: Always use Git to track changes Goose makes to your code
  • Review AI changes: Don't blindly accept all suggestions; understand what Goose is doing
  • Start small: Begin with simple tasks to build confidence before tackling complex projects

Security and Privacy

  • API key protection: Never commit API keys to version control
  • Sensitive data: Be cautious when working with projects containing credentials or private information
  • Code review: Always review code Goose generates, especially for security-critical applications
  • Local execution: Goose runs locally, but it sends code context to LLM APIs; understand your provider's data policies

Cost Management

  • Use appropriate models: Don't use GPT-4o for simple tasks when GPT-4o-mini will suffice
  • Break down large tasks: Instead of one massive request, split work into smaller, focused tasks
  • Monitor usage: Regularly check your API usage dashboard
  • Set budgets: Configure spending limits with your LLM provider

Advanced Configuration

Shared Configuration

Both Desktop and CLI share configuration stored at ~/.config/goose/config.yaml. You can manually edit this file for advanced customization:

providers:
  openai:
    model: gpt-4o
    api_key_env: OPENAI_API_KEY

extensions:
  computer_controller:
    enabled: true
    timeout: 300
Enter fullscreen mode Exit fullscreen mode

Multiple Providers

Goose supports multi-model configuration, letting you use different models for different tasks:

goose configure
# Add multiple providers with different models
# Switch between them as needed for your workflow
Enter fullscreen mode Exit fullscreen mode

Conclusion

Goose on Windows has evolved into a robust, production-ready tool for developers. While there are Windows-specific considerations—particularly around paths, permissions, and environment configuration—the installation and setup process is straightforward. By following the best practices outlined in this guide, you'll be well-equipped to leverage Goose's powerful AI-assisted development capabilities.
Whether you choose the Desktop application for its intuitive interface or the CLI for terminal integration, Goose can dramatically accelerate your development workflow. Start with simple tasks, familiarize yourself with how Goose operates, and gradually incorporate it into more complex aspects of your work.
The key to success with Goose is understanding it as a collaborative tool rather than a replacement for your expertise. Use it to handle repetitive tasks, explore unfamiliar technologies, and prototype quickly—but always apply your judgment and review the results.

Additional Resources

Happy coding with Goose!

Top comments (0)