Recipe Reference Guide

Recipes are reusable goose configurations that package up instructions and settings so the setup can be easily shared and launched by others.

Recipe File Format​

Recipes can be defined in:

• .yaml (recommended) and .yml files
• .json files

See Shareable Recipes to learn how to create, use, and manage recipes.

Recipe Location​

Recipes can be loaded from:

1. Local filesystem:

   • Current directory
   • Directories specified in GOOSE_RECIPE_PATH environment variable

2. GitHub repositories:

   • Configure using GOOSE_RECIPE_GITHUB_REPO configuration key
   • Requires GitHub CLI (gh) to be installed and authenticated

Core Recipe Schema​

Recipes follow this schema structure:

*At least one of instructions or prompt must be provided.

Field Specifications​

Activities​

The activities field defines an optional message and clickable activity bubbles (buttons) that appears when a recipe is opened in goose Desktop.

Activity Types​

Activities can be defined in two ways:

1. Message Activity: Displays the markdown-formatted activity text in an info box above the activity bubbles. For example:

   activities:
     - "message: **Welcome!** Here's what I can help with:\n\n• 📊 Data analysis\n• 🔍 Code review\n• 📝 Documentation\n\nSelect an option below to begin."
   

   Only include one message: prefixed activity. Additional message: prefixed activities become regular clickable bubbles (and display the literal "message:" text).

2. Button Activities: Text to display in activity bubbles, which send the activity text as a prompt when clicked

Parameter Substitution​

Activities support parameter substitution, allowing you to create dynamic, personalized activity bubbles. After users provide parameter values in the Recipe Parameters dialog, the values are substituted into the activity text before the bubbles are displayed.

Example Configuration​

version: "1.0.0"
title: "Code Review Assistant"
description: "Review code with customizable focus areas"
parameters:
  - key: language
    input_type: string
    requirement: required
    description: "Programming language to review"
  - key: focus
    input_type: string
    requirement: optional
    default: "best practices"
    description: "Review focus area"

activities:
  - "message: Click an option below to start reviewing {{ language }} code with a focus on {{ focus }}."
  - "Review the current file for {{ focus }}"
  - "Suggest improvements for {{ language }} code quality"
  - "Check for security vulnerabilities"
  - "Generate unit tests"

{
  "version": "1.0.0",
  "title": "Code Review Assistant",
  "description": "Review code with customizable focus areas",
  "parameters": [
    {
      "key": "language",
      "input_type": "string",
      "requirement": "required",
      "description": "Programming language to review"
    },
    {
      "key": "focus",
      "input_type": "string",
      "requirement": "optional",
      "default": "best practices",
      "description": "Review focus area"
    }
  ],
  "activities": [
    "message: Click an option below to start reviewing {{ language }} code with a focus on {{ focus }}.",
    "Review the current file for {{ focus }}",
    "Suggest improvements for {{ language }} code quality",
    "Check for security vulnerabilities",
    "Generate unit tests"
  ]
}

In this example:

• The message activity displays instructions with substituted parameter values, for example: "Click an option below to start reviewing rust code with a focus on best practices."
• The first two activity bubbles use parameter substitution, for example: "Review the current file for best practices"
• The last two activity bubbles are static prompts that work regardless of parameters

Extensions​

The extensions field allows you to specify which Model Context Protocol (MCP) servers and other extensions the recipe needs to function. Each extension in the extensions array has the following schema:

Extension Schema​

Extension Types​

• stdio: Standard I/O client with command and arguments
• sse: Server-sent events client with a URI endpoint
• builtin: Built-in extension that is part of the bundled goose MCP server
• platform: Platform extensions that run in the agent process
• streamable_http: Streamable HTTP client with URI endpoint
• frontend: Frontend-provided tools called through the frontend
• inline_python: Inline Python code executed using uvx. Requires code field; optional dependencies for packages.

Example Extensions Configuration​

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"
    
  - type: inline_python
    name: data_processor
    code: |
      import pandas as pd
      print("Processing data...")
    dependencies:
      - pandas
      - numpy
    timeout: 120
    description: "Process data using pandas"

{
  "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"
    },
    {
      "type": "inline_python",
      "name": "data_processor",
      "code": "import pandas as pd\nprint(\"Processing data...\")",
      "dependencies": ["pandas", "numpy"],
      "timeout": 120,
      "description": "Process data using pandas"
    }
  ]
}

Extension Secrets​

This feature is only available through the CLI.

If a recipe uses an extension that requires a secret, goose can prompt users to provide the secret when running the recipe:

1. When a recipe is loaded, goose scans all extensions (including those in subrecipes) for env_keys fields
2. If any required environment variables are missing from the secure keyring, goose prompts the user to enter them
3. Values are stored securely in the system keyring and reused for subsequent runs

To update a stored secret, remove it from the system keyring and run the recipe again to be re-prompted.

Parameters​

The parameters field allows you to create dynamic, reusable recipes that can be customized for different contexts. Parameters define placeholders that users fill in when running the recipe, making the recipe more flexible and adaptable.

Parameter substitution uses Jinja-style template syntax with {{ parameter_name }} placeholders. Each parameter in the parameters array has the following schema:

Parameter Schema​

Parameter Requirements​

• required: Parameter must be provided when using the recipe
• optional: Can be omitted if a default value is specified
• user_prompt: Will interactively prompt the user for input if not provided

The required and optional parameters work best for recipes opened in goose Desktop. If a value isn't provided for a user_prompt parameter, the parameter won't be substituted and may appear as literal {{ parameter_name }} text in the recipe output.

Input Types​

• string: Default type. The parameter value is used as-is in template substitution
• number: Numeric values. Desktop UI provides number input validation
• boolean: True/false values. Desktop UI shows dropdown with "True"/"False" options
• date: Date values. Currently renders as text input
• file: The parameter value should be a file path. goose reads the file contents and substitutes the actual content (not the path) into the template
• select: Dropdown selection with predefined options. Requires options field

Example:

parameters:
  - key: max_files
    input_type: number
    requirement: optional
    default: "10"
    description: "Maximum files to process"
  
  - key: output_format
    input_type: select
    requirement: required
    description: "Choose output format"
    options:
      - json
      - markdown
      - csv
  
  - key: enable_debug
    input_type: boolean
    requirement: optional
    default: "false"
    description: "Enable debug mode"
  
  - key: source_code
    input_type: file
    requirement: required
    description: "Path to the source code file to analyze"

prompt: "Process {{ max_files }} files in {{ output_format }} format. Debug: {{ enable_debug }}. Code:\n\n{{ source_code }}"

Parameter Substitution in Desktop​

When a recipe with parameters is opened in goose Desktop, users are presented with a Recipe Parameters dialog where they can:

• Provide values for required parameters
• Modify or accept default values for optional parameters
• Enter values for user_prompt parameters

Once parameter values are submitted, they are substituted into the recipe's instructions, prompt, and activities fields before the recipe starts.

Response​

The response field enables recipes to enforce a final structured JSON output. When you specify a json_schema, goose will:

1. Validate the output: Validates the output JSON against your JSON schema with basic JSON schema validations
2. Final structured output: Ensure the final output of the agent is a response matching your JSON structure

This feature is designed for non-interactive automation to ensure consistent, parseable output. Recipes can produce structured output when run from either the goose CLI or goose Desktop. See use cases and ideas for automation workflows.

Response Schema​

Basic Structure​

response:
  json_schema:
    type: object
    properties:
      # Define your fields here, with their type and description
    required:
      # List required field names

Simple Example​

version: "1.0.0"
title: "Task Summary"
description: "Summarize completed tasks"
prompt: "Summarize the tasks you completed"
response:
  json_schema:
    type: object
    properties:
      summary:
        type: string
        description: "Brief summary of work done"
      tasks_completed:
        type: number
        description: "Number of tasks finished"
      next_steps:
        type: array
        items:
          type: string
        description: "Recommended next actions"
    required:
      - summary
      - tasks_completed

Retry​

The retry field enables recipes to automatically retry execution if success criteria are not met. This is useful for recipes that might need multiple attempts to achieve their goal, or for implementing automated validation and recovery workflows.

Retry Schema​

Success Check Configuration​

Each success check in the checks array has the following schema:

How Retry Logic Works​

1. Recipe Execution: The recipe runs normally with the provided instructions
2. Success Validation: After completion, all success checks are executed in order
3. Retry Decision: If any success check fails and retry attempts remain:
   • Execute the on_failure command (if configured)
   • Reset the agent's message history to initial state
   • Increment retry counter and restart execution
4. Completion: Process stops when either:
   • All success checks pass (success)
   • Maximum retry attempts are reached (failure)

Basic Retry Example​

version: "1.0.0"
title: "Counter Increment Task"
description: "Increment a counter until it reaches target value"
prompt: "Increment the counter value in /tmp/counter.txt by 1."

retry:
  max_retries: 5
  timeout_seconds: 10
  checks:
    - type: shell
      command: "test $(cat /tmp/counter.txt 2>/dev/null || echo 0) -ge 3"
  on_failure: "echo 'Counter is at:' $(cat /tmp/counter.txt 2>/dev/null || echo 0) '(need 3 to succeed)'"

Advanced Retry Example​

version: "1.0.0"
title: "Service Health Check"
description: "Start service and verify it's running properly"
prompt: "Start the web service and verify it responds to health checks"

retry:
  max_retries: 3
  timeout_seconds: 30
  on_failure_timeout_seconds: 60
  checks:
    - type: shell
      command: "curl -f http://localhost:8080/health"
    - type: shell  
      command: "pgrep -f 'web-service' > /dev/null"
  on_failure: "systemctl stop web-service || killall web-service"

Environment Variables​

You can configure retry behavior globally using environment variables:

• GOOSE_RECIPE_RETRY_TIMEOUT_SECONDS: Global timeout for success check commands
• GOOSE_RECIPE_ON_FAILURE_TIMEOUT_SECONDS: Global timeout for on_failure commands

These environment variables are overridden by recipe-specific timeout configurations.

Settings​

The settings field allows you to configure the AI model and provider settings for the recipe. This overrides the default configuration when the recipe is executed.

Settings Schema​

Example Settings Configuration​

settings:
  goose_provider: "anthropic"
  goose_model: "claude-sonnet-4-20250514"
  temperature: 0.7

settings:
  goose_provider: "openai"
  goose_model: "gpt-4o"
  temperature: 0.3

Subrecipes​

The sub_recipes field specifies the subrecipes that the main recipe calls to perform specific tasks. Each subrecipe in the sub_recipes array has the following schema:

Subrecipe Schema​

Example Subrecipe Configuration​

sub_recipes:
  - name: "security_scan"
    path: "./subrecipes/security-analysis.yaml"
    values:  # in key-value format: {parameter_name}: {parameter_value}
      scan_level: "comprehensive"
      include_dependencies: "true"
  
  - name: "quality_check"
    path: "./subrecipes/quality-analysis.yaml"
    description: "Performs code quality analysis"

Desktop Metadata Fields​

Recipes saved from goose Desktop include additional metadata fields. These fields are used by the Desktop app for organization and management but are ignored by CLI operations.

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: []

{
  "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": []
}

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

{
  "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
}

Template Support​

Recipes support Jinja-style template syntax in instructions, prompt, and activities fields for parameter substitution:

instructions: "Follow these steps with {{ parameter_name }}"
prompt: "Your task is to {{ action }}"
activities:
  - "Process {{ parameter_name }} with {{ action }}"

Advanced template features include:

• Template inheritance using {% extends "parent.yaml" %}
• Blocks that can be defined and overridden:

  {% block content %}
  Default content
  {% endblock %}
  

• indent() template filter

Template Inheritance​

Use {% extends "parent.yaml" %} for template inheritance:

Parent recipe (parent.yaml):

version: "1.0.0"
title: "Parent Recipe"
description: "Base recipe template"
prompt: |
  {% block prompt %}
  Default prompt text
  {% endblock %}

Child recipe:

{% extends "parent.yaml" %}
{% block prompt %}
Modified prompt text
{% endblock %}

indent() Filter For Multi-Line Values​

Use the indent() filter to ensure multi-line parameter values are properly indented and can be resolved as valid JSON or YAML format. This example uses {{ raw_data | indent(2) }} to specify an indentation of two spaces when passing data to a subrecipe:

sub_recipes:
  - name: "analyze"
    path: "./analyze.yaml"
    values:
      content: |
        {{ raw_data | indent(2) }}

Built-in Parameters​

Built-in template parameters are automatically supported and don't need to be defined in the parameters array.

Validation Rules​

Validation rules from validate_recipe.rs are enforced when loading recipes and used by the goose recipe validate subcommand:

Recipe-Level Validation​

• validate_prompt_or_instructions - At least one of instructions or prompt must be present
• validate_json_schema - JSON response schema must be valid if response.json_schema is specified

Parameter Validation​

• validate_parameters_in_template - All template variables must have corresponding parameter definitions, and all defined parameters must be used (no unused parameters)
• validate_optional_parameters - Optional parameters must have default values
• validate_optional_parameters - File parameters cannot have default values to prevent importing sensitive files

Complete Recipe Example​

version: "1.0.0"
title: "Example Recipe"
description: "A sample recipe demonstrating the format"
instructions: "Process {{ file_count }} files using {{ required_param }} and output in {{ output_format }} format. Configuration: {{ config_file }}"
prompt: "Start processing with the provided parameters"
parameters:
  - key: required_param
    input_type: string
    requirement: required
    description: "A required text parameter"
  
  - key: file_count
    input_type: number
    requirement: optional
    default: 10
    description: "Maximum number of files to process"
  
  - key: output_format
    input_type: select
    requirement: required
    description: "Choose the output format"
    options:
      - json
      - markdown
      - csv
  
  - key: config_file
    input_type: file
    requirement: required
    description: "Path to configuration file"

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

{
  "version": "1.0.0",
  "title": "Example Recipe",
  "description": "A sample recipe demonstrating the format",
  "instructions": "Process {{ file_count }} files using {{ required_param }} and output in {{ output_format }} format. Configuration: {{ config_file }}",
  "prompt": "Start processing with the provided parameters",
  "parameters": [
    {
      "key": "required_param",
      "input_type": "string",
      "requirement": "required",
      "description": "A required text parameter"
    },
    {
      "key": "file_count",
      "input_type": "number",
      "requirement": "optional",
      "default": "10",
      "description": "Maximum number of files to process"
    },
    {
      "key": "output_format",
      "input_type": "select",
      "requirement": "required",
      "description": "Choose the output format",
      "options": ["json", "markdown", "csv"]
    },
    {
      "key": "config_file",
      "input_type": "file",
      "requirement": "required",
      "description": "Path to configuration file"
    }
  ],
  "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"]
    }
  }
}

Error Handling​

Common errors to watch for:

• Missing required parameters
• Optional parameters without default values
• Template variables without parameter definitions
• Invalid YAML/JSON syntax
• Missing required fields
• Invalid extension configurations
• Invalid retry configuration (missing required fields, invalid shell commands)

When these occur, goose will provide helpful error messages indicating what needs to be fixed.

Retry-Specific Errors​

• Invalid success checks: Shell commands that cannot be executed or have syntax errors
• Timeout errors: Success checks or on_failure commands that exceed their timeout limits
• Max retries exceeded: When all retry attempts are exhausted without success
• Missing required retry fields: When max_retries or checks are not specified

Learn More​

Check out the Recipes guide for more docs, tools, and resources to help you master goose recipes.