Skip to main content
Goose Desktop provides a rich graphical interface for working with AI agents, managing sessions, and running recipes.

​
Installation

Download Goose Desktop from the releases page:
  • macOS: Download .dmg file
  • Windows: Download .exe installer
  • Linux: Download .AppImage or use package managers

​
macOS Installation

1

Download the DMG

Download Goose-darwin-arm64.dmg (Apple Silicon) or Goose-darwin-x64.dmg (Intel)
2

Open and install

  1. Open the downloaded DMG file
  2. Drag Goose.app to Applications folder
  3. Launch from Applications
3

Grant permissions

On first launch, you may need to:
  • Allow the app in System Preferences > Security & Privacy
  • Grant accessibility permissions for full functionality

​
Windows Installation

1

Download installer

Download the Windows installer .exe file
2

Run installer

Double-click the installer and follow the prompts
3

Launch

Launch Goose from Start Menu or Desktop shortcut

​
Linux Installation

1

Download AppImage

Download the .AppImage file
2

Make executable

chmod +x Goose-*.AppImage
3

Run

./Goose-*.AppImage

​
First Launch

On first launch, Goose Desktop will guide you through setup:
1

Choose setup method

Select from:
  • OpenRouter Login: Automatic setup with OpenRouter
  • Tetrate Login: Enterprise authentication
  • Manual Configuration: Choose provider and enter credentials
2

Configure provider

If using manual configuration:
  1. Select your AI provider (Anthropic, OpenAI, etc.)
  2. Enter API credentials
  3. Choose a model
3

Enable extensions

Select built-in extensions to enable:
  • Developer tools (code editing, shell access)
  • Memory (persistent storage)
  • Computer Controller (web scraping, automation)
  • Auto Visualiser (data visualization)

​
Interface Overview

​
Main Views

The desktop app has several main views:

​
Sessions View

Manage and access your conversation sessions:
  • Recent sessions: Quick access to latest conversations
  • Search: Filter sessions by name or content
  • Session insights: View statistics and activity

​
Chat Interface

The main conversation interface includes:
  • Message history: Scrollable conversation view
  • Input area: Text input with markdown support
  • Tool output: Collapsible tool execution results
  • Thinking indicators: Visual feedback during AI processing

​
Settings Panel

Access all configuration options:
  • Provider settings: Change model and provider
  • Extension management: Enable/disable/configure extensions
  • Appearance: Theme and display preferences
  • Permissions: Tool and file access controls

​
Working with Sessions

​
Creating a New Session

1

Click New Session

Click the “New Session” button in the sessions view
2

Set working directory

Choose the project directory for file operations
3

Start chatting

Begin your conversation with the AI agent

​
Session Management

Renaming sessions:
  1. Click on the session name
  2. Enter new name
  3. Press Enter to save
Pinning sessions:
  • Click the pin icon to keep important sessions at the top
Deleting sessions:
  1. Right-click on session
  2. Select “Delete session”
  3. Confirm deletion
Exporting sessions:
  1. Open session menu
  2. Select “Export”
  3. Choose format (JSON, YAML, Markdown)
  4. Save to file

​
Using Extensions

​
Built-in Extensions

Goose Desktop includes several built-in extensions:

​
Developer Extension

Provides tools for software development: Available tools:
  • read_file: Read file contents
  • write_file: Write or update files
  • patch_file: Apply targeted edits
  • execute_command: Run shell commands
  • list_files: Browse directory contents
Example usage: 
Read the authentication logic in src/auth.ts
The AI will use read_file to access the file.

​
Memory Extension

Stores and retrieves persistent information: 
Remember that I prefer TypeScript over JavaScript
Later sessions can recall: 
What are my coding preferences?

​
Computer Controller

Advanced automation capabilities:
  • Web scraping
  • PDF/DOCX reading
  • Excel file processing
  • Automated workflows

​
Adding Custom Extensions

1

Open settings

Navigate to Settings > Extensions
2

Click Add Extension

Choose extension type:
  • Built-in
  • Command-line (stdio)
  • Remote (HTTP)
3

Configure extension

For command-line extensions:
Command: npx -y @block/gdrive
Name: Google Drive
Description: Access Google Drive files
Timeout: 120 seconds
4

Set environment variables

Add any required API keys or configuration

​
Running Recipes

Recipes are pre-configured workflows for common tasks.

​
From Recipe Library

1

Open recipe browser

Click “Recipes” in the main menu
2

Browse or search

Filter by category or search by name
3

Select and run

Click on a recipe to see details, then “Run Recipe”
4

Provide parameters

Fill in any required parameters (e.g., username, platform)
Open recipes via deeplink URLs: 
goose://recipe?config=eyJ0aXRsZSI6IjQwNFBvcnRmb2xpbyJ9...
Generate deeplinks using the CLI: 
goose recipe deeplink recipe.yaml

​
Custom Recipes

1

Create recipe file

Create a YAML file with recipe definition:
version: 1.0.0
title: "My Custom Recipe"
description: "Automated code review"
instructions: |
  Review all TypeScript files in src/
  Check for:
  - Type safety issues
  - Performance concerns
  - Security vulnerabilities
extensions:
  - type: builtin
    name: developer
2

Import to desktop

File > Import Recipe > Select your YAML file
3

Run

The recipe appears in your library and can be run like built-in recipes

​
Settings and Preferences

​
Appearance

  • Theme: Light, Dark, or System
  • Font size: Adjust chat text size
  • Code highlighting: Choose syntax theme
  • Compact mode: Reduce spacing for more content

​
Behavior

  • Auto-scroll: Keep latest message visible
  • Confirm deletions: Require confirmation for destructive actions
  • Show tool output: Display detailed tool execution results
  • Notification sounds: Audio feedback for events

​
Provider Settings

  • Default model: Choose which model to use
  • Temperature: Control response randomness (0.0-1.0)
  • Max tokens: Limit response length
  • Thinking mode: Configure extended thinking (Claude)

​
Extension Settings

For each extension:
  • Enable/Disable: Toggle extension availability
  • Timeout: Maximum execution time
  • Permissions: File access and tool permissions
  • Environment: Custom environment variables

​
Keyboard Shortcuts

  • Cmd/Ctrl + N: New session
  • Cmd/Ctrl + T: New chat
  • Cmd/Ctrl + W: Close session
  • Cmd/Ctrl + ,: Open settings
  • Cmd/Ctrl + K: Search sessions

​
Chat

  • Enter: Send message
  • Shift + Enter: New line in message
  • Cmd/Ctrl + Enter: Force send
  • Esc: Cancel current generation

​
Editing

  • Cmd/Ctrl + C: Copy selected text
  • Cmd/Ctrl + V: Paste
  • Cmd/Ctrl + A: Select all

​
Tips and Best Practices

​
Session Organization

  • Use descriptive session names
  • Pin frequently accessed sessions
  • Archive completed sessions
  • Export important conversations

​
Performance

  • Close unused sessions to reduce memory usage
  • Limit tool output verbosity for faster responses
  • Use smaller models for simple tasks

​
Security

  • Review file access permissions regularly
  • Use approval mode for sensitive operations
  • Don’t commit .goose directories to version control
  • Regularly update to latest version for security patches

​
Troubleshooting

​
App won’t start

  1. Check system requirements (Node 24.10.0+)
  2. Review logs in ~/Library/Logs/Goose (macOS)
  3. Try removing config: ~/.config/goose
  4. Reinstall application

​
Provider connection issues

  1. Verify API key in Settings > Providers
  2. Check network connectivity
  3. Confirm API quota/limits
  4. Try different model

​
Extension errors

  1. Verify extension configuration
  2. Check environment variables
  3. Review extension logs
  4. Increase timeout if needed

​
Performance issues

  1. Close unused sessions
  2. Reduce tool output verbosity
  3. Disable unused extensions
  4. Clear cache (Settings > Advanced)

​
Updates

Goose Desktop checks for updates automatically. Manual update check:
  1. Help > Check for Updates
  2. Download and install if available
  3. Restart application
Auto-update settings:
  • Enable/disable in Settings > General
  • Choose update channel (stable/alpha)
  • Set update check frequency

​
Data and Privacy

Goose Desktop stores data locally:
  • Configuration: ~/.config/goose/config.yaml
  • Sessions: ~/.config/goose/sessions/
  • Secrets: System keyring (macOS/Windows) or ~/.config/goose/secrets.yaml
  • Logs: Platform-specific log directory
Telemetry:
  • Anonymous usage statistics (opt-in)
  • No conversation content collected
  • Disable in Settings > Privacy
See Environment Variables for configuration options.

Build docs developers (and LLMs) love

Get started for freeTalk to us