awesome-bookmarks/goose
3
0
Fork 0
mirror of https://github.com/block/goose.git synced 2026-07-17 12:56:20 +02:00
Code Issues Packages Projects Releases Wiki Activity

Docs/json recipe support (#5492)

Browse Source
This commit is contained in:
dianed-square
2025-10-31 11:16:14 -07:00
committed by GitHub
parent 69198fc6b2
commit aa100cfbcf
5 changed files with 228 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/docs/guides/codebase-analysis.md
+1 -1
View File
@@ -41,7 +41,7 @@ This shows that `authenticate` is a central function in your authentication flow
## Analysis Modes
The `analyze` tool operates in three modes—Structure, Semantic, and Focus—depending on whether you’re analyzing directories, files, or symbols. Invoke it through natural language or direct commands with [parameters](#parameters).
The `analyze` tool operates in three modes—Structure, Semantic, and Focus—depending on whether you’re analyzing directories, files, or symbols. Invoke it through natural language or direct commands with [parameters](#common-parameters).
### Understanding Project Organization
documentation/docs/guides/environment-variables.md
+1 -1
View File
@@ -313,7 +313,7 @@ OTLP is the standard protocol for sending telemetry collected by [OpenTelemetry]
| `OTEL_EXPORTER_OTLP_TIMEOUT` | Export timeout in milliseconds | Integer (ms) | `10000` |
**When to use OTLP:**
- Diagnosing slow tool execution or LLM response times when goose
- Diagnosing slow tool execution or LLM response times
- Understanding intermittent failures across multiple sessions
- Monitoring goose performance in production or CI/CD environments
- Tracking usage patterns, costs, and resource consumption over time
documentation/docs/guides/recipes/recipe-reference.md
+197 -17
View File
@@ -1,9 +1,12 @@
---
sidebar_position: 2
title: Recipe Reference Guide
description: Complete technical reference for creating and customizing recipes in goose via the CLI.
description: Complete technical reference for creating and customizing recipes in goose
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Recipes are reusable goose configurations that package up a specific setup so it can be easily shared and launched by others.
## Recipe File Format
@@ -12,11 +15,7 @@ Recipes can be defined in either:
- `.yaml` files (recommended)
- `.json` files
Files should be named either:
- `recipe.yaml`/`recipe.json`
- `<recipe_name>.yaml`/`<recipe_name>.json`
After creating recipe files, you can use the [`goose recipe` subcommands](/docs/guides/goose-cli-commands#recipe) to validate, share, and open your recipes.
See [Shareable Recipes](/docs/guides/recipes/session-recipes) to learn how to create, use, and manage recipes.
### CLI and Desktop Formats
@@ -25,12 +24,18 @@ goose recipes use two formats:
- **CLI Format**: Recipe fields (like `title`, `description`, `instructions`) are at the root level of the YAML/JSON file. This format is used when recipes are created via the CLI `/recipe` command and [Recipe Generator](/recipe-generator) YAML option.
- **Desktop Format**: Recipe fields are nested inside a `recipe` object, with additional metadata fields at the root level. This format is used when recipes are created from goose Desktop.
The CLI automatically detects and handles both formats when running `goose run --recipe <file>` and `goose recipe` commands. The Desktop can [import](/docs/guides/recipes/storing-recipes#importing-recipes) and use YAML recipes (or deeplinks) in either CLI or Desktop format.
The CLI automatically detects and handles both formats for `.yaml` and `.json` recipe files when running `goose run --recipe <file>` and `goose recipe` commands. The Desktop can [import](/docs/guides/recipes/storing-recipes#importing-recipes) `.yaml`, `.yml`, and `.json` recipe files (or deeplinks) in either CLI or Desktop format.
<details>
<summary>Format Examples</summary>
**CLI Format:**
Recipes can be written in either YAML or JSON format. Both formats follow the same schema structure.
### CLI Format
<Tabs>
<TabItem value="yaml" label="YAML" default>
```yaml
version: "1.0.0"
title: "Code Review Assistant"
@@ -40,7 +45,28 @@ prompt: "Review the code in this repository"
extensions: []
```
**Desktop Format:**
</TabItem>
<TabItem value="json" label="JSON">
```json
{
"version": "1.0.0",
"title": "Code Review Assistant",
"description": "Automated code review with best practices",
"instructions": "You are a code reviewer...",
"prompt": "Review the code in this repository",
"extensions": []
}
```
</TabItem>
</Tabs>
### Desktop Format
<Tabs>
<TabItem value="yaml" label="YAML" default>
```yaml
name: "Code Review Assistant"
recipe:
@@ -55,6 +81,29 @@ lastModified: 2025-07-02T03:46:46.778Z
isArchived: false
```
</TabItem>
<TabItem value="json" label="JSON">
```json
{
"name": "Code Review Assistant",
"recipe": {
"version": "1.0.0",
"title": "Code Review Assistant",
"description": "Automated code review with best practices",
"instructions": "You are a code reviewer...",
"prompt": "Review the code in this repository",
"extensions": []
},
"isGlobal": true,
"lastModified": "2025-07-02T03:46:46.778Z",
"isArchived": false
}
```
</TabItem>
</Tabs>
:::note
goose automatically adds metadata fields to recipes saved from the Desktop app.
:::
@@ -238,6 +287,9 @@ The `extensions` field allows you to specify which Model Context Protocol (MCP)
### Example Extension Configuration
<Tabs>
<TabItem value="yaml" label="YAML" default>
```yaml
extensions:
- type: stdio
@@ -268,6 +320,45 @@ extensions:
description: "GitHub MCP extension for repository operations"
```
</TabItem>
<TabItem value="json" label="JSON">
```json
{
"extensions": [
{
"type": "stdio",
"name": "codesearch",
"cmd": "uvx",
"args": ["mcp_codesearch@latest"],
"timeout": 300,
"bundled": true,
"description": "Query https://codesearch.sqprod.co/ directly from goose"
},
{
"type": "stdio",
"name": "presidio",
"timeout": 300,
"cmd": "uvx",
"args": ["mcp_presidio@latest"],
"available_tools": ["query_logs"]
},
{
"type": "stdio",
"name": "github-mcp",
"cmd": "github-mcp-server",
"args": [],
"env_keys": ["GITHUB_PERSONAL_ACCESS_TOKEN"],
"timeout": 60,
"description": "GitHub MCP extension for repository operations"
}
]
}
```
</TabItem>
</Tabs>
### Extension Secrets
This feature is only available through the CLI.
@@ -516,12 +607,15 @@ sub_recipes:
## Complete Recipe Example
<Tabs>
<TabItem value="yaml" label="YAML" default>
```yaml
version: "1.0.0"
title: "Example Recipe"
description: "A sample recipe demonstrating the format"
instructions: "Follow these steps with {{ required_param }} and {{ optional_param }}"
prompt: "Your task is to use {{ required_param }}"
prompt: "Your task is to use {{ required_param }} with {{ interactive_param }}"
parameters:
- key: required_param
input_type: string
@@ -576,9 +670,92 @@ response:
description: "Additional details of steps taken"
required:
- result
- status
- details
```
</TabItem>
<TabItem value="json" label="JSON">
```json
{
"version": "1.0.0",
"title": "Example Recipe",
"description": "A sample recipe demonstrating the format",
"instructions": "Follow these steps with {{ required_param }} and {{ optional_param }}",
"prompt": "Your task is to use {{ required_param }} with {{ interactive_param }}",
"parameters": [
{
"key": "required_param",
"input_type": "string",
"requirement": "required",
"description": "A required parameter example"
},
{
"key": "optional_param",
"input_type": "string",
"requirement": "optional",
"default": "default value",
"description": "An optional parameter example"
},
{
"key": "interactive_param",
"input_type": "string",
"requirement": "user_prompt",
"description": "Will prompt user if not provided"
}
],
"extensions": [
{
"type": "stdio",
"name": "codesearch",
"cmd": "uvx",
"args": ["mcp_codesearch@latest"],
"timeout": 300,
"bundled": true,
"description": "Query codesearch directly from goose"
}
],
"settings": {
"goose_provider": "anthropic",
"goose_model": "claude-sonnet-4-20250514",
"temperature": 0.7
},
"retry": {
"max_retries": 3,
"timeout_seconds": 30,
"checks": [
{
"type": "shell",
"command": "echo 'Task validation check passed'"
}
],
"on_failure": "echo 'Retry attempt failed, cleaning up...'"
},
"response": {
"json_schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "The main result of the task"
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional details of steps taken"
}
},
"required": ["result", "details"]
}
}
}
```
</TabItem>
</Tabs>
## Template Inheritance
Parent recipe (`parent.yaml`):
@@ -614,13 +791,16 @@ Recipes can be loaded from:
## Validation Rules
The following rules are enforced when loading recipes:
Recipe files must be valid YAML or JSON. In addition, the following [validation rules](https://github.com/block/goose/blob/main/crates/goose/src/recipe/validate_recipe.rs) are enforced when loading recipes and are also checked by the [`goose recipe validate` subcommand](/docs/guides/goose-cli-commands#recipe):
1. All template variables must have corresponding parameter definitions
2. Optional parameters must have default values
3. Parameter keys must be unique
4. Recipe files must be valid YAML or JSON
5. Required fields (version, title, description) must be present
- Required `title` and `description` fields must be present
- At least one of `instructions` or `prompt` must be present
- All template variables must have corresponding parameter definitions
- Parameter keys must be unique (not enforced, but required for proper functionality)
- All defined parameters must be used in template variables (no unused parameters)
- Optional parameters must have default values
- File parameters cannot have default values (prevents importing sensitive files)
- `response.json_schema` must be a valid JSON schema if specified
## Error Handling
documentation/docs/guides/recipes/session-recipes.md
+3 -5
View File
@@ -199,9 +199,11 @@ You can turn your current goose session into a reusable recipe that includes the
- Instructions
- Initial prompt
- Activities
- Parameters
- Response schema
4. When you're finished, you can:
- Copy the recipe link to share the recipe with others
- Click `Save Recipe` to [save the recipe](/docs/guides/recipes/storing-recipes) locally
- Click `Save Recipe` to save your changes
- Click `Create Schedule` to [schedule the recipe](#schedule-recipe)
:::tip
@@ -250,10 +252,6 @@ You can turn your current goose session into a reusable recipe that includes the
4. To run the recipe, click an activity bubble or send the prompt.
:::info Parameter Creation In Goose CLI Only
You can enter parameter values to use in a recipe, but you cannot add parameters to a recipe in Goose Desktop. Parameters can only be defined in recipes created via the CLI.
:::
:::info Privacy & Isolation
- Each person gets their own private session
- No data is shared between users
documentation/docs/guides/recipes/storing-recipes.md
+26 -26
View File
@@ -8,11 +8,11 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import { PanelLeft, Bot } from 'lucide-react';
This guide covers storing, organizing, and finding Goose recipes when you need to access them again later.
This guide covers storing, organizing, and finding goose recipes when you need to access them again later.
:::info Desktop UI vs CLI
- **Goose Desktop** has a visual Recipe Library for browsing and managing saved recipes
- **Goose CLI** stores recipes as files that you find using file paths or environment variables
- **goose Desktop** has a visual Recipe Library for browsing and managing saved recipes
- **goose CLI** stores recipes as files that you find using file paths or environment variables
:::
## Understanding Recipe Storage
@@ -45,15 +45,15 @@ Before saving recipes, it's important to understand where they can be stored and
**Save New Recipe:**
1. To create a recipe from your chat session, see: [Create Recipe](/docs/guides/recipes/session-recipes#create-recipe)
2. Once in the Recipe Editor, click **Save Recipe** to save it to your Recipe Library
2. Once in the Recipe Editor, click `Save Recipe` to save it to your Recipe Library
**Save Modified Recipe:**
If you're already using a recipe and want to save a modified version:
1. Click the <Bot className="inline" size={16}/> button with your current model at the bottom of the window
2. Click **View Recipe**
2. Click `View Recipe`
3. Make any desired edits to the description, instructions, or initial prompts
5. Click **Save Recipe**
5. Click `Save Recipe`
:::info
When you modify and save a recipe with a new name, a new recipe and new link are generated. You can still run the original recipe from the recipe library, or using the original link. If you edit a recipe without changing its name, the version in the recipe library is updated, but you can still run the original recipe via link.
@@ -68,6 +68,10 @@ When you modify and save a recipe with a new name, a new recipe and new link are
* Any path you specify: `/recipe /path/to/my-recipe.yaml`
* Local project recipes: `/recipe .goose/recipes/my-recipe.yaml`
:::note
The CLI saves recipes as `.yaml` files. While the CLI can run recipes in `.json` format, it does not provide an option to save recipes as JSON.
:::
</TabItem>
</Tabs>
@@ -75,29 +79,25 @@ When you modify and save a recipe with a new name, a new recipe and new link are
<Tabs groupId="interface">
<TabItem value="desktop" label="goose Desktop" default>
Import a recipe using its deeplink or YAML file:
Import a recipe using its deeplink or recipe file:
**Import via Recipe Link:**
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `Recipes` in the sidebar
3. Click **Import Recipe**
4. Under **Recipe Deeplink**, paste in the [recipe link](/docs/guides/recipes/session-recipes#share-via-recipe-link)
5. Add a name and choose the [storage location](#recipe-storage-locations)
6. Click **Import Recipe**
3. Click `Import Recipe`
4. Choose your import method:
- To import via a link: Under `Recipe Deeplink`, paste in the [recipe link](/docs/guides/recipes/session-recipes#share-via-recipe-link)
- To import via a file: Under `Recipe File`, click `Choose File`, select a recipe file, and click `Open`
5. Click `Import Recipe` to save a copy of the recipe to your Recipe Library
**Import via Recipe File:**
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `Recipes` in the sidebar
3. Click **Import Recipe**
4. Under **Recipe YAML File**, click **Choose File**, select the YAML recipe file, and click `Open`
5. Add a name and choose the [storage location](#recipe-storage-locations)
6. Click **Import Recipe**
:::warning Recipe File Format
goose Desktop accepts `.yaml`, `.yml`, and `.json` files, but **the CLI only supports `.yaml` and `.json`**. For full compatibility across both interfaces, avoid `.yml` extensions.
Importing JSON recipe files isn't currently supported.
All recipe formats follow the same [schema structure](/docs/guides/recipes/recipe-reference#recipe-structure).
:::
</TabItem>
<TabItem value="cli" label="goose CLI">
Recipe import is only available in Goose Desktop.
Recipe import is only available in goose Desktop.
</TabItem>
</Tabs>
@@ -138,7 +138,7 @@ goose recipe list --format json
**Recipe Discovery Process**
Goose searches for recipes in the following locations (in order):
goose searches for recipes in the following locations (in order):
1. **Current directory**: `.` (looks for `*.yaml` and `*.json` files)
2. **Custom paths**: Directories specified in [`GOOSE_RECIPE_PATH`](/docs/guides/environment-variables#recipe-configuration) environment variable
@@ -162,7 +162,7 @@ job-finder - Find software engineering positions - local: ~/.config/goose/recipe
$ goose recipe list --verbose
Available recipes:
goose-self-test - A comprehensive meta-testing recipe - local: ./goose-self-test.yaml
Title: Goose Self-Testing Integration Suite
Title: goose Self-Testing Integration Suite
Path: ./goose-self-test.yaml
hello-world - A sample recipe demonstrating basic usage - local: ~/.config/goose/recipes/hello-world.yaml
Title: Hello World Recipe
@@ -176,7 +176,7 @@ Available recipes:
"name": "goose-self-test",
"source": "Local",
"path": "./goose-self-test.yaml",
"title": "Goose Self-Testing Integration Suite",
"title": "goose Self-Testing Integration Suite",
"description": "A comprehensive meta-testing recipe"
},
{
@@ -242,10 +242,10 @@ The `goose recipe list` command is the recommended way to find recipes as it aut
</TabItem>
<TabItem value="cli" label="goose CLI">
Once you've located your recipe file, [run the recipe](/docs/guides/recipes/session-recipes#run-a-recipe) or [open it in goose desktop](/docs/guides/goose-cli-commands#recipe).
Once you've located your recipe file, [run the recipe](/docs/guides/recipes/session-recipes#run-a-recipe) or [open it in goose Desktop](/docs/guides/goose-cli-commands#recipe).
:::tip Format Compatibility
The CLI can run recipes saved from Goose Desktop without any conversion. Both CLI-created and Desktop-saved recipes work with all recipe commands.
The CLI can run recipes saved from goose Desktop without any conversion. Both CLI-created and Desktop-saved recipes work with all recipe commands.
:::
</TabItem>