> ## 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.

# Desktop Application

> Guide to using the Goose Desktop application

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](https://github.com/block/goose/releases):

* **macOS**: Download `.dmg` file
* **Windows**: Download `.exe` installer
* **Linux**: Download `.AppImage` or use package managers

### macOS Installation

<Steps>
  <Step title="Download the DMG">
    Download `Goose-darwin-arm64.dmg` (Apple Silicon) or `Goose-darwin-x64.dmg` (Intel)
  </Step>

  <Step title="Open and install">
    1. Open the downloaded DMG file
    2. Drag Goose.app to Applications folder
    3. Launch from Applications
  </Step>

  <Step title="Grant permissions">
    On first launch, you may need to:

    * Allow the app in System Preferences > Security & Privacy
    * Grant accessibility permissions for full functionality
  </Step>
</Steps>

### Windows Installation

<Steps>
  <Step title="Download installer">
    Download the Windows installer `.exe` file
  </Step>

  <Step title="Run installer">
    Double-click the installer and follow the prompts
  </Step>

  <Step title="Launch">
    Launch Goose from Start Menu or Desktop shortcut
  </Step>
</Steps>

### Linux Installation

<Steps>
  <Step title="Download AppImage">
    Download the `.AppImage` file
  </Step>

  <Step title="Make executable">
    ```bash theme={null}
    chmod +x Goose-*.AppImage
    ```
  </Step>

  <Step title="Run">
    ```bash theme={null}
    ./Goose-*.AppImage
    ```
  </Step>
</Steps>

## First Launch

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

<Steps>
  <Step title="Choose setup method">
    Select from:

    * **OpenRouter Login**: Automatic setup with OpenRouter
    * **Tetrate Login**: Enterprise authentication
    * **Manual Configuration**: Choose provider and enter credentials
  </Step>

  <Step title="Configure provider">
    If using manual configuration:

    1. Select your AI provider (Anthropic, OpenAI, etc.)
    2. Enter API credentials
    3. Choose a model
  </Step>

  <Step title="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)
  </Step>
</Steps>

## 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

<Steps>
  <Step title="Click New Session">
    Click the "New Session" button in the sessions view
  </Step>

  <Step title="Set working directory">
    Choose the project directory for file operations
  </Step>

  <Step title="Start chatting">
    Begin your conversation with the AI agent
  </Step>
</Steps>

### 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

<Steps>
  <Step title="Open settings">
    Navigate to Settings > Extensions
  </Step>

  <Step title="Click Add Extension">
    Choose extension type:

    * Built-in
    * Command-line (stdio)
    * Remote (HTTP)
  </Step>

  <Step title="Configure extension">
    For command-line extensions:

    ```
    Command: npx -y @block/gdrive
    Name: Google Drive
    Description: Access Google Drive files
    Timeout: 120 seconds
    ```
  </Step>

  <Step title="Set environment variables">
    Add any required API keys or configuration
  </Step>
</Steps>

## Running Recipes

Recipes are pre-configured workflows for common tasks.

### From Recipe Library

<Steps>
  <Step title="Open recipe browser">
    Click "Recipes" in the main menu
  </Step>

  <Step title="Browse or search">
    Filter by category or search by name
  </Step>

  <Step title="Select and run">
    Click on a recipe to see details, then "Run Recipe"
  </Step>

  <Step title="Provide parameters">
    Fill in any required parameters (e.g., username, platform)
  </Step>
</Steps>

### From Deeplink

Open recipes via deeplink URLs:

```
goose://recipe?config=eyJ0aXRsZSI6IjQwNFBvcnRmb2xpbyJ9...
```

Generate deeplinks using the CLI:

```bash theme={null}
goose recipe deeplink recipe.yaml
```

### Custom Recipes

<Steps>
  <Step title="Create recipe file">
    Create a YAML file with recipe definition:

    ```yaml theme={null}
    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
    ```
  </Step>

  <Step title="Import to desktop">
    File > Import Recipe > Select your YAML file
  </Step>

  <Step title="Run">
    The recipe appears in your library and can be run like built-in recipes
  </Step>
</Steps>

## 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

### Navigation

* `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](/guides/environment-variables) for configuration options.