Skip to content

Improve subagents docs #5484

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
emma-squared merged 2 commits into from
Oct 31, 2025
Merged

Improve subagents docs #5484

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
92f0158
Improve subagents docs
emma-squared Oct 30, 2025
2fe437f
Add return mode to settings table
emma-squared Oct 31, 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
4 changes: 4 additions & 0 deletions documentation/docs/guides/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ These variables control how goose manages conversation sessions and context.
|----------|---------|---------|---------|
| `GOOSE_CONTEXT_STRATEGY` | Controls how goose handles context limit exceeded situations | "summarize", "truncate", "clear", "prompt" | "prompt" (interactive), "summarize" (headless) |
| `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/sessions/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 |
| `GOOSE_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/subagents) to complete before timeout | Integer (e.g., 25) | 25 |
| `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints"]` |
| `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response markdown | "light", "dark", "ansi" | "dark" |
| `GOOSE_RANDOM_THINKING_MESSAGES` | Controls whether to show amusing random messages during processing | "true", "false" | "true" |
Expand All @@ -176,6 +177,9 @@ export GOOSE_MAX_TURNS=25
# Set a reasonable limit for production
export GOOSE_MAX_TURNS=100

# Customize subagent turn limit
export GOOSE_SUBAGENT_MAX_TURNS=50

# Use multiple context files
export CONTEXT_FILE_NAMES='["CLAUDE.md", ".goosehints", ".cursorrules", "project_rules.txt"]'

Expand Down
68 changes: 51 additions & 17 deletions documentation/docs/guides/subagents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,17 @@ Subagents are independent instances that execute tasks while keeping your main c

## How to Use Subagents

To use subagents, ask Goose to delegate tasks using natural language. Goose automatically decides when to spawn subagents and handles their lifecycle. You can:
:::tip Autonomous Subagent Creation
goose can autonomously decide to use subagents when it determines they would be beneficial for your task - you don't always need to explicitly request them. This happens automatically in autonomous mode (the default). Subagents are disabled in chat-only mode.
:::

To use subagents, ask goose to delegate tasks using natural language. goose automatically decides when to spawn subagents and handles their lifecycle. You can:

1. **Request specialized help**: "Use a code reviewer to analyze this function for security issues"
2. **Reference specific recipes**: "Use the 'security-auditor' recipe to scan this endpoint"
3. **Run parallel tasks**: "Create three HTML templates simultaneously"
4. **Delegate complex work**: "Research quantum computing developments and summarize findings"
5. **Control extension access**: "Create a subagent with only the developer extension to refactor the code"

You can run multiple subagents sequentially or in parallel.

Expand All @@ -40,15 +45,15 @@ If a subagent fails or times out (5-minute default), you will receive no output

## Internal Subagents

Internal subagents spawn Goose instances to handle tasks using your current session's context and extensions. There are two ways to configure and execute internal subagents:
Internal subagents spawn goose instances to handle tasks using your current session's context and extensions. There are two ways to configure and execute internal subagents:

1. **Direct Prompts** - Quick, one-off tasks using natural language instructions
2. **Recipes** - Reusable, structured configurations for specialized subagent behavior

### Direct Prompts
Direct prompts provided for one-off tasks using natural language prompts. The main agent automatically configures the subagent based on your request.

**Goose Prompt:**
**goose Prompt:**
```
"Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel"
```
Expand Down Expand Up @@ -116,16 +121,16 @@ prompt: |
Provide specific, actionable feedback with examples.
```

**Place your recipe file where Goose can find it**
**Place your recipe file where goose can find it**
- Set [`GOOSE_RECIPE_PATH`](/docs/guides/recipes/recipe-reference#recipe-location) environment variable to your recipe directory
- Or place it in your current working directory

**Goose Prompt**
**goose Prompt**
```
Use the "code-reviewer" recipe to analyze the authentication feature I implemented
```

**Goose Output**
**goose Output**
```
I'll use your code-reviewer recipe to create a specialized subagent for this analysis.

Expand All @@ -148,9 +153,9 @@ I'll use your code-reviewer recipe to create a specialized subagent for this ana

## External Subagents

External subagents let you bring in AI agents from other providers and platforms, enabling Goose to coordinate and integrate your workflow with the broader ecosystem. In the below example, we use Codex as a subagent by running it as an MCP server:
External subagents let you bring in AI agents from other providers and platforms, enabling goose to coordinate and integrate your workflow with the broader ecosystem. In the below example, we use Codex as a subagent by running it as an MCP server:

**[Goose Configuration File](/docs/guides/config-files)** (`.~/.config/goose/config.yaml `):
**[goose Configuration File](/docs/guides/config-files)** (`.~/.config/goose/config.yaml `):
```yaml
subagent:
args:
Expand Down Expand Up @@ -180,12 +185,12 @@ approval_policy = "never"
mode = "workspace-write"
```

**Goose Prompt:**
**goose Prompt:**
```
"Use the codex subagent to analyze my codebase structure and identify the main components"
```

**Goose Output:**
**goose Output:**

```md
Based on my analysis of your codebase, here are the main components:
Expand Down Expand Up @@ -233,26 +238,55 @@ Subagents are temporary instances that exist only for task execution. After the

## Configuration

Subagents are automatically have the following pre-configured settings, but you can override any defaults using natural language in your prompts.
Subagents use the following pre-configured settings, but you can override any defaults using natural language in your prompts.

### Default Settings
| Parameter | Default | Source |
|-----------|---------|--------|
| **Max Turns** | 10 | Built-in default |
| **Timeout** | 5 minutes | Built-in default |
| Parameter | Default | How to Customize |
|-----------|---------|------------------|
| **Max Turns** | 25 | Use natural language or set `GOOSE_SUBAGENT_MAX_TURNS` |
| **Timeout** | 5 minutes | Request longer timeout in your prompt |
| **Extensions** | Inherited from parent | Specify which extensions to use in your prompt |
| **Return Mode** | All subagent information provided in main session | Specify how much detail you want in your prompt |

### Customizing Settings in Prompts

You can override any default by including the setting in your natural language request:

**Examples:**
```
"Use subagents to analyze code, limit each to 5 turns"
```

```
"Use a research subagent with 30 turns and 20-minute timeout to investigate quantum computing trends"
```

**Environment variable:** Set `GOOSE_SUBAGENT_MAX_TURNS` to change the default max turns for all subagents.

### Extension Control

Control which tools and capabilities subagents can access. By default, subagents inherit all extensions from your main session, but you can restrict access for security, focus or performance.

**Examples:**
```
"Create a subagent to write a summary, but don't give it file access"
```

```
"Use a subagent with only code editing tools to refactor main.py"
```

### Return Mode Control
Copy link
Contributor

@dianed-square dianed-square Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this also be in the settings table?

Copy link
Contributor Author

@emma-squared emma-squared Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, good point! I'll add to the table.

Choose how much information goose provides from its subagents in your main session.

**Full Details (Default):** See all tool executions and reasoning steps
```
"Use subagents to write a test and documentation, but make them timeout after 7 minutes"
"Create a subagent to debug this issue - I want to see the full investigation process"
```

**Summary Only:** Get just the final result to keep your conversation clean
```
""Use subagents to analyze code, limit each to 5 turns""
"Use a subagent to research this topic and summarize the key findings"
```

## Security Constraints
Expand Down