Skip to content

Docs: Lead/worker model in Goose Desktop #3342

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
blackgirlbytes merged 2 commits into from
Jul 11, 2025
Merged

Docs: Lead/worker model in Goose Desktop #3342

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cb6836a
Docs: Lead/worker model in Goose Desktop
emma-squared Jul 10, 2025
966a5c2
Updates and clarifications to lead/worker
emma-squared Jul 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 38 additions & 27 deletions documentation/docs/tutorials/lead-worker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
description: Enable multi-modal functionality by pairing LLMs to complete your tasks
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Lead/Worker Multi-Model Setup

Goose supports a lead/worker model configuration that lets you pair two different AI models - one that's great at thinking and another that's fast at doing. This setup tackles a major pain point: premium models are powerful but expensive, while cheaper models are faster but can struggle with complex tasks. With lead/worker mode, you get the best of both worlds.
Expand Down Expand Up @@ -38,24 +41,33 @@ Goose will start with `gpt-4o` for the first three turns, then hand off to `gpt-
Ensure you have [added the LLMs to Goose](/docs/getting-started/providers)
:::

The only required setting is:

```bash
export GOOSE_LEAD_MODEL="gpt-4o"
```

That's it. Goose treats your regular `GOOSE_MODEL` as the worker model by default.

If you want more control, here are the optional knobs:

```bash
export GOOSE_LEAD_PROVIDER="anthropic" # If different from the main provider
export GOOSE_LEAD_TURNS=5 # Use lead model for first 5 turns
export GOOSE_LEAD_FAILURE_THRESHOLD=3 # Switch back to lead after 3 failures
export GOOSE_LEAD_FALLBACK_TURNS=2 # Use lead model for 2 turns before retrying worker
```

After making these configurations, the lead/worker models will be used in new CLI and Desktop sessions.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
1. Click the model name at the bottom of the Goose Desktop window
2. Click **Lead/Worker Settings**
3. Check the box to **Enable lead/worker mode**
4. Select your **Lead Model** and **Worker Model** from the dropdown menus
5. (Optional) Change the default number of **initial lead turns**, the **failure threshold** before switching back to the leavd model, or the number of **fallback turns** to use the lead model during fallback
</TabItem>
<TabItem value="cli" label="Goose CLI">
The only required configuration is setting the `GOOSE_LEAD_MODEL` [environment variable](/docs/guides/environment-variables#leadworker-model-configuration):

```bash
export GOOSE_LEAD_MODEL="gpt-4o"
```
That's it. Goose treats your regular `GOOSE_MODEL` as the worker model by default.

For more control, you can also set these optional environment variables:

```bash
export GOOSE_LEAD_PROVIDER="anthropic" # If different from the main provider
export GOOSE_LEAD_TURNS=5 # Use lead model for first 5 turns
export GOOSE_LEAD_FAILURE_THRESHOLD=3 # Switch back to lead after 3 failures
export GOOSE_LEAD_FALLBACK_TURNS=2 # Use lead model for 2 turns before retrying worker
```
After making these configurations, the lead/worker models will be used in new CLI and Desktop sessions.
</TabItem>
</Tabs>

## What Counts as a Failure?

Expand All @@ -65,7 +77,7 @@ Goose is smart about detecting actual task failures, not just API errors. The fa
- Hits permission issues
- Gets corrected by the user ("that's wrong", "try again", etc.)

Meanwhile, technical hiccups like timeouts, auth issues, or service downtime don't trigger fallback mode. Goose just retries those quietly.
Technical hiccups like timeouts, authentication issues, or service downtime don't trigger fallback mode. Goose retries those quietly.

## Reasons to Use Lead/Worker

Expand All @@ -89,15 +101,14 @@ export RUST_LOG=goose::providers::lead_worker=info
```

## Planning Mode Compatibility

Lead/worker mode also works alongside Goose's `/plan` command. You can even assign separate models for each:
The lead/worker model is an automatic alternative to the [Goose CLI's `/plan` command](/docs/guides/creating-plans.md). You can assign separate models to use as the lead/worker and planning models. For example:

```bash
export GOOSE_LEAD_MODEL="o1-preview" # used automatically
export GOOSE_PLANNER_MODEL="gpt-4o" # used when you explicitly call /plan
export GOOSE_MODEL="gpt-4o-mini" # used for execution
```
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-4o-mini" # the main conversational model

---
export GOOSE_LEAD_MODEL="o1-preview" # the lead model used automatically
export GOOSE_PLANNER_MODEL="gpt-4o" # the model used when you explicitly call /plan
```

The lead/worker model helps you work smarter with Goose. You get high quality reasoning when it matters and save time and money on execution. And with the fallback system in place, you don't have to babysit it. It just works.
Use **planning mode** when you want a dedicated reasoning model to generate comprehensive strategies that you can review and approve before execution. Use the **lead/worker model** for iterative development work where you want smart automation without interruption - like implementing features, debugging issues, or exploratory coding. Your workflow can combine both: use `/plan` to strategize major decisions, then let the lead/worker models handle the tactical implementation with automatic optimization.
Loading