diff --git a/documentation/docs/guides/codebase-analysis.md b/documentation/docs/guides/codebase-analysis.md index a2299070963c..dd896eedfa11 100644 --- a/documentation/docs/guides/codebase-analysis.md +++ b/documentation/docs/guides/codebase-analysis.md @@ -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 diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index 40c5b02d6f70..8c6bd934a44d 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -309,7 +309,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 diff --git a/documentation/docs/guides/recipes/recipe-reference.md b/documentation/docs/guides/recipes/recipe-reference.md index d7f1bad2b0e8..f5f622cd8ea6 100644 --- a/documentation/docs/guides/recipes/recipe-reference.md +++ b/documentation/docs/guides/recipes/recipe-reference.md @@ -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` -- `.yaml`/`.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 ` 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 ` 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.
Format Examples -**CLI Format:** +Recipes can be written in either YAML or JSON format. Both formats follow the same schema structure. + +### CLI Format + + + + ```yaml version: "1.0.0" title: "Code Review Assistant" @@ -40,7 +45,28 @@ prompt: "Review the code in this repository" extensions: [] ``` -**Desktop Format:** + + + +```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": [] +} +``` + + + + +### Desktop Format + + + + ```yaml name: "Code Review Assistant" recipe: @@ -55,6 +81,29 @@ lastModified: 2025-07-02T03:46:46.778Z isArchived: false ``` + + + +```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 +} +``` + + + + :::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 + + + ```yaml extensions: - type: stdio @@ -268,6 +320,45 @@ extensions: description: "GitHub MCP extension for repository operations" ``` + + + +```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" + } + ] +} +``` + + + + ### Extension Secrets This feature is only available through the CLI. @@ -516,12 +607,15 @@ sub_recipes: ## Complete Recipe Example + + + ```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 ``` + + + +```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"] + } + } +} +``` + + + + ## 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 diff --git a/documentation/docs/guides/recipes/session-recipes.md b/documentation/docs/guides/recipes/session-recipes.md index 1b48459a6735..b4f2561e8308 100644 --- a/documentation/docs/guides/recipes/session-recipes.md +++ b/documentation/docs/guides/recipes/session-recipes.md @@ -198,9 +198,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) @@ -245,10 +247,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 diff --git a/documentation/docs/guides/recipes/storing-recipes.md b/documentation/docs/guides/recipes/storing-recipes.md index e7e140cadafa..16ae9ae55cfa 100644 --- a/documentation/docs/guides/recipes/storing-recipes.md +++ b/documentation/docs/guides/recipes/storing-recipes.md @@ -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 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. + ::: + @@ -75,29 +79,25 @@ When you modify and save a recipe with a new name, a new recipe and new link are - 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 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 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). + ::: - Recipe import is only available in Goose Desktop. + Recipe import is only available in goose Desktop. @@ -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 -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. :::