docs: reorganize (#9310)
This commit is contained in:
Angie Jones
@@ -0,0 +1,348 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Creating Plans Before Working
|
||||
sidebar_label: Creating Plans
|
||||
---
|
||||
|
||||
import Card from '@site/src/components/Card';
|
||||
import styles from '@site/src/components/Card/styles.module.css';
|
||||
|
||||
Starting a project without a clear plan is like building a house without a blueprint. It can lead to:
|
||||
|
||||
* Confusion about what to do
|
||||
* Wasted time and effort
|
||||
* Projects that grow too big
|
||||
|
||||
A good plan keeps everyone on track and helps measure progress. That's why the goose CLI includes the `/plan` prompt completion command to help break down your projects into clear, manageable steps.
|
||||
|
||||
:::tip Plans in the goose Desktop
|
||||
The goose Desktop doesn't have a `plan` keyword. If you want goose Desktop to create a plan for you, you need to use a prompt like:
|
||||
|
||||
```
|
||||
"Hey goose, can you create a plan to convert my CLI project into a locally hosted web page that gives me input fields for each CLI command I can run? Please don't start the actual work"
|
||||
```
|
||||
Unless you ask goose to "create a plan", it might just start into the project work.
|
||||
:::
|
||||
|
||||
The goose CLI's plan mode is interactive, asking clarifying questions to understand your project before creating a plan. If you can provide thoughtful and informative answers to those questions, goose can generate a really useful and actionable plan.
|
||||
|
||||
## Set your planner provider and model
|
||||
In some workflows, it can be helpful to use one LLM for planning and a different one for execution. For example, GPT-4.1 tends to excel at strategic planning and breaking down complex tasks into clear, logical steps. On the other hand, Claude Sonnet 3.5 is particularly strong at writing clean, efficient code and following instructions precisely. By using GPT-4.1 to plan and Claude to execute, you can play to the strengths of both models and get better results overall.
|
||||
|
||||
The goose CLI plan mode uses two configuration values:
|
||||
|
||||
- `GOOSE_PLANNER_PROVIDER`: Which provider to use for planning
|
||||
- `GOOSE_PLANNER_MODEL`: Which model to use for planning
|
||||
|
||||
:::tip Multi-Model Alternative to Plan Mode
|
||||
You can combine planning mode with a different default execution model to balance cost, speed, and quality.
|
||||
:::
|
||||
|
||||
:::tip Customize Plan Format
|
||||
You can also customize how goose creates plans by editing the `plan.md` [prompt template](/docs/guides/context-engineering/prompt-templates).
|
||||
:::
|
||||
|
||||
### Set goose planner environment variables
|
||||
You might add these lines to your bash shell config file (.bashrc) to add the planner environment variables:
|
||||
```bash
|
||||
export GOOSE_PLANNER_PROVIDER=<my-chosen-provider>
|
||||
export GOOSE_PLANNER_MODEL=<my-chosen-model>
|
||||
```
|
||||
After you save your changes to the config file, you need to re-start your goose session so that goose can use the variables.
|
||||
|
||||
If these aren't set, goose will use your default provider and model settings. You might want to set different planning models if you find certain models are better at breaking down tasks into clear steps. However, your default model configuration is usually sufficient.
|
||||
|
||||
To verify that the planner provider is set, input the following terminal command:
|
||||
|
||||
```bash
|
||||
~ goose info -v
|
||||
```
|
||||
|
||||
In this example, the `info` command returns the current configuration and the path to the configuration file.
|
||||
|
||||
```bash
|
||||
goose Version:
|
||||
Version: 1.0.18
|
||||
|
||||
goose Locations:
|
||||
Config file: /Users/alincoln/.config/goose/config.yaml
|
||||
Sessions dir: /Users/alincoln/.local/share/goose/sessions
|
||||
Logs dir: /Users/alincoln/.local/state/goose/logs
|
||||
|
||||
goose Configuration:
|
||||
GOOSE_PROVIDER: anthropic
|
||||
GOOSE_MODEL: claude-3.5-sonnet
|
||||
GOOSE_PLANNER_PROVIDER: openai
|
||||
GOOSE_MODE: smart_approve
|
||||
GOOSE_PLANNER_MODEL: gpt-4.1
|
||||
```
|
||||
|
||||
If either `GOOSE_PLANNER_PROVIDER` or `GOOSE_PLANNER_MODEL` are not set, `GOOSE_PROVIDER` and `GOOSE_MODEL`are used to build your plan.
|
||||
|
||||
## Describe your project
|
||||
While goose can handle complex project descriptions, it works best with clear, concise ones. Focus on stating your project's purpose and desired outcomes. If these aren't clear, goose will ask clarifying questions until it fully understands your goals.
|
||||
|
||||
## A simple construction plan example
|
||||
goose can produce good plans for relatively simple projects such as the home construction example:
|
||||
|
||||
```bash
|
||||
( O)> /plan
|
||||
|
||||
Entering plan mode. You can provide instructions to create a plan and then act on it. To exit early, type /endplan
|
||||
|
||||
( O)> Build a four bedroom house
|
||||
◓ Measuring semantic distance...
|
||||
|
||||
I need to gather more information before creating a detailed house-building plan. Please provide clarification on the following:
|
||||
|
||||
1. What is the purpose of this plan? Are you looking for architectural designs, construction steps, or a project management timeline?
|
||||
2. What is your budget range for this four-bedroom house?
|
||||
3. What is the approximate square footage or size requirements?
|
||||
4. Do you have a specific location or lot already selected? What are the dimensions and any zoning restrictions?
|
||||
5. Are there any specific architectural styles or features you want included?
|
||||
6. How many bathrooms and other rooms (e.g., kitchen, living room, dining room, garage) do you want?
|
||||
7. Do you have any specific sustainability or energy efficiency requirements?
|
||||
8. What is your timeline for completion?
|
||||
|
||||
( O)> 1 construction steps and a project management timeline. 2 $600,000. 3 4,000 sq feet. 4 the lot is not yet selected. 5 one story rambler. 6 four bedrooms, two ful baths, a kitchen, diningroom, family room, and garage. 7 the house must be efficient and powered by solar energy. 8 complete in six months.
|
||||
◓ Taming tensors... I'll create a detailed plan for building a 4,000 sq ft, one-story rambler with four bedrooms, two full bathrooms, kitchen, dining room, family room, garage, and home office. The house will be energy efficient with solar power, with a $600,000 budget and 6-month timeline.
|
||||
|
||||
◇ Do you want to clear message history & act on this plan?
|
||||
│ Yes
|
||||
│
|
||||
|
||||
Exiting plan mode and acting on the above plan
|
||||
|
||||
### Introduction to Building a 4,000 Sq Ft Rambler
|
||||
To create a detailed plan for your 4,000 sq ft, one-story rambler, we need to consider several factors including design, energy efficiency, budget, and timeline. Given your requirements, here's an overview of how to approach this project:
|
||||
|
||||
### Step 1: Design and Planning
|
||||
- **Architectural Design**: Hire an architect to design the house, ensuring it meets your space requirements and is energy efficient. Consider factors like natural lighting, insulation, and window placement.
|
||||
- **Floor Plan**: Create a floor plan that includes four bedrooms, two full bathrooms, a kitchen, dining room, family room, garage, and home office. Ensure the layout is functional and spacious.
|
||||
- **Land Preparation**: Ensure the building site is prepared, including clearing the land, grading, and preparing the foundation.
|
||||
|
||||
### Step 2: Energy Efficiency and Solar Power
|
||||
- **Solar Power System**: Design and install a solar power system that can meet the energy needs of a 4,000 sq ft house. This may include a large solar panel array and a battery storage system for nighttime and cloudy days.
|
||||
- **Insulation and Windows**: Use high-quality insulation in the walls, floor, and ceiling to minimize heat loss. Install energy-efficient windows that allow natural light in while keeping the heat or cold out.
|
||||
- **Energy-Efficient Appliances**: Specify energy-efficient appliances and lighting to minimize energy consumption.
|
||||
|
||||
### Step 3: Budgeting
|
||||
- **Construction Costs**: Allocate approximately $200-250 per sq ft for construction, which translates to $800,000-$1,000,000 for a 4,000 sq ft house. However, your budget is $600,000, so you'll need to optimize costs without compromising on quality and energy efficiency.
|
||||
- **Solar Power System Costs**: Budget an additional $20,000 to $50,000 for the solar power system, depending on its size and complexity.
|
||||
- **Contingency Fund**: Set aside 10-20% of the budget for unexpected expenses.
|
||||
|
||||
### Step 4: Timeline
|
||||
- **Month 1-2: Design and Planning**: Complete the architectural design, obtain necessary permits, and prepare the building site.
|
||||
- **Month 3-4: Foundation and Framing**: Lay the foundation, frame the house, and install the roof.
|
||||
- **Month 5: Installation of Electrical, Plumbing, and HVAC Systems**: Install the solar power system, electrical, plumbing, and HVAC systems.
|
||||
- **Month 6: Finishing Work**: Complete the interior finishing work, including installation of energy-efficient appliances, flooring, and fixtures.
|
||||
|
||||
### Conclusion
|
||||
Building a 4,000 sq ft, energy-efficient rambler with solar power within a $600,000 budget and 6-month timeline is challenging but feasible with careful planning and design. It's essential to work closely with your architect, contractor, and solar power system installer to ensure the project stays on track and within budget.
|
||||
|
||||
Given that no extensions are currently available for more specific tools or data sources, consider the following steps to proceed with your project:
|
||||
|
||||
* Search for available extensions using the <function=platform__search_available_extensions>{}</function>
|
||||
|
||||
```
|
||||
The home construction plan remains high-level because goose's current models specialize in technology and software development rather than construction. This is why projects like our first example—building a web application—receive more detailed planning and specific guidance.
|
||||
|
||||
### Create a separate plan for plan sub-steps
|
||||
Let's return to the home construction example. While the plan includes hiring an architect, this high-level step needs more detail – such as what type of architect to hire and how to navigate the selection process.
|
||||
|
||||
```
|
||||
- **Architectural Design**: Hire an architect to design the house, ensuring it meets your space requirements and is energy efficient. Consider factors like natural lighting, insulation, and window placement.
|
||||
```
|
||||
If you exit plan mode while reviewing your construction plan, you can always resume it to continue working with goose.
|
||||
|
||||
```
|
||||
( O)> /plan hire an architect
|
||||
|
||||
Entering plan mode. You can provide instructions to create a plan and then act on it. To exit early, type /endplan
|
||||
|
||||
◓ Synchronizing flock algorithms... I need some clarifying questions to better understand your request about hiring an architect:
|
||||
|
||||
1. What is your location or preferred region for the architect to be based in?
|
||||
2. Do you have a specific budget range for architectural services?
|
||||
3. Are you looking for an architect with specific expertise (e.g., energy-efficient homes, modern design, traditional styles)?
|
||||
4. Do you need full architectural services (design through construction oversight) or just certain phases?
|
||||
5. Do you have a timeline for when you'd like to begin working with an architect?
|
||||
6. Have you already purchased land for your home, or will the architect need to help evaluate potential sites?
|
||||
7. Are there any specific certifications or qualifications you're looking for in an architect?
|
||||
8. Would you prefer to work with a solo practitioner or a larger architectural firm?
|
||||
9. Do you have any examples of architectural styles or specific homes you admire?
|
||||
10. How involved do you want to be in the design process?
|
||||
```
|
||||
|
||||
After gathering information through clarifying questions, goose creates a detailed plan for hiring an architect. This sub-plan integrates with the larger home construction project, with steps that reflect and support the overall construction context.
|
||||
|
||||
## A development project example
|
||||
In this example, a developer has written a CLI in Python that interacts with the Contentful CMS to let a user search for strings and replace them with new strings. As a website, the search/replace feature would be more usable and also allow for a larger set of features. The developer is using the goose CLI to plan the conversion project.
|
||||
|
||||
If goose believes the project can be completed in many different ways and using a wide variety of components, it will ask you a clarifying question for each of these decision points. For example, if you start a plan like this:
|
||||
|
||||
```bash
|
||||
( O)> /plan
|
||||
|
||||
Entering plan mode. You can provide instructions to create a plan and then act on it. To exit early, type /endplan
|
||||
|
||||
( O)> Convert the CLI built by search_replace_routes.py into a web page
|
||||
```
|
||||
goose parses your project description, consults with the LLM mode you've configured, and then if it needs more information, starts a round of clarifying questions.
|
||||
|
||||
## Clarifying questions
|
||||
Converting a Python CLI into a website seems simple enough but goose will have questions about things like styling, authentication, features, technology stack, and more. You might see questions like this:
|
||||
|
||||
```bash
|
||||
1. Should the application support any keyboard shortcuts for common actions?
|
||||
2. Would you like the application to remember user preferences (like case sensitivity setting) between sessions?
|
||||
3. Should there be any form of notification when operations complete successfully?
|
||||
4. How should the application handle very large text fields that might be difficult to display in the three-column layout?
|
||||
5. Are there any specific CI/CD requirements for deployment to AWS?
|
||||
|
||||
```
|
||||
You can answer the questions one at a time or you can batch your answers:
|
||||
|
||||
```bash
|
||||
( O)> 1 no keyboard shortcuts. 2 do not remember preferences. 3 on success, open a dialog that says "success". 4 Truncate to 30 characters before the string to replace and then 30 characters after the string to replace.5 no CI/CD requirements
|
||||
```
|
||||
|
||||
|
||||
:::tip
|
||||
When goose requests a project artifact like source code during plan mode, you'll need to paste the content directly into the chat. Simply copying the file contents and prefixing it with a brief description like 'Here's the requested code:' is sufficient. Note that providing just a file path won't work in plan mode.
|
||||
:::
|
||||
|
||||
When answering multiple questions, number your responses to match each question. For example, instead of answering with a simple 'no' or 'don't remember', provide context like '2. Do not store my preferences.' This helps goose track which questions have been answered and prevents repeated questions.
|
||||
|
||||
In complex projects like converting a CLI to a website, goose may ask multiple rounds of clarifying questions. Each round typically stems from new information in your previous answers or when additional details are needed about specific aspects of your project.
|
||||
|
||||
If you've answered _all_ of goose's questions and it has no more questions, goose will generate the plan. Other times, you might think goose will never run out of questions. If you want your plan and don't want to answer more questions, you can simply ask for a "generic" plan:
|
||||
|
||||
```bash
|
||||
I still need some critical information to create a comprehensive plan:
|
||||
|
||||
1. What specific functionality does your Python script perform with Contentful? Could you share the actual code or describe how it interacts with the Contentful API to search and replace content?
|
||||
2. What are the 5 predefined keys/inputs you mentioned earlier?
|
||||
3. Should the web application include all the command-line options from the script (environment, status, case-sensitive, partial-match, dry-run)?
|
||||
4. How should the application handle errors from the Contentful API?
|
||||
5. Should the application maintain any history of previous search/replace operations?
|
||||
|
||||
Without this information, I can only provide a generic plan that might not accurately capture your requirements.
|
||||
( O)> please provide a generic plan
|
||||
```
|
||||
While goose creates a standardized plan format, it customizes the content based on your answers. goose can generate the code needed to implement the steps of the plan it produces. You should review the plan and any code that it generates before ending plan mode (`/endplan`) and asking goose to implement the plan.
|
||||
|
||||
Below is a sample plan for this project, with the generated website code omitted for brevity:
|
||||
|
||||
```bash
|
||||
# Plan for Converting CLI Script to React Web Application
|
||||
|
||||
## Step 1: Set up the React project and dependencies
|
||||
1. Create a new React application using Create React App
|
||||
2. Install necessary dependencies
|
||||
3. Set up project structure
|
||||
src/
|
||||
├── components/
|
||||
│ ├── Auth/
|
||||
│ ├── Layout/
|
||||
│ ├── Search/
|
||||
│ ├── Results/
|
||||
│ └── History/
|
||||
├── services/
|
||||
│ ├── contentful.ts
|
||||
│ ├── auth.ts
|
||||
│ └── storage.ts
|
||||
├── utils/
|
||||
│ ├── validation.ts
|
||||
│ └── helpers.ts
|
||||
├── contexts/
|
||||
│ └── AppContext.tsx
|
||||
└── pages/
|
||||
├── Home.tsx
|
||||
├── Search.tsx
|
||||
└── History.tsx
|
||||
|
||||
## Step 2: Implement authentication with Okta
|
||||
1. Create an Okta application in the Okta Developer Console
|
||||
2. Configure the Okta authentication settings in the application
|
||||
3. Implement protected routes using Okta's React components
|
||||
## Step 3: Create the layout and UI components with Material UI
|
||||
1. Implement the main layout with Material UI
|
||||
2. Create the search form component
|
||||
3. Create the results display component with three columns
|
||||
4. Implement the "Load More" pagination component
|
||||
## Step 4: Implement Contentful service
|
||||
1. Create a service for interacting with Contentful
|
||||
## Step 5: Implement local storage service for history
|
||||
1. Create a service for managing search history in localStorage
|
||||
## Step 6: Implement validation utilities
|
||||
1. Create utility functions for input validation
|
||||
## Step 7: Implement main pages
|
||||
1. Create the Search page
|
||||
2. Create the History page
|
||||
## Step 8: Set up routing and main application
|
||||
1. Create the main App component
|
||||
## Step 9: Implement error handling and loading states
|
||||
1. Create error boundary components
|
||||
2. Add loading indicators for API operations
|
||||
3. Implement error messages display
|
||||
|
||||
## Step 10: Set up deployment configuration
|
||||
1. Create AWS deployment configuration
|
||||
## Step 11: Testing and quality assurance
|
||||
1. Write unit tests for key components
|
||||
2. Implement integration tests for the main workflows
|
||||
3. Perform manual testing of the application
|
||||
|
||||
This plan provides a comprehensive framework for converting your CLI script to a React web application with Material UI and Okta authentication. You'll need to adapt specific parts based on your exact requirements and the functionality of your original script.
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Basic usage
|
||||
You need to have an active goose session before you can put the CLI into plan mode. If you are going to dedicate a session to creating a plan, you should give your new session a name as in the following example:
|
||||
|
||||
```bash
|
||||
~ goose session -n web-project-plan
|
||||
starting session | provider: databricks model: databricks-meta-llama
|
||||
session id: 20251110_5
|
||||
working directory: /Users/alincoln
|
||||
|
||||
goose is running! Enter your instructions, or try asking what goose can do.
|
||||
```
|
||||
To enter planning mode, type `/plan`. Optionally, you can append your plan description to the prompt completion command.
|
||||
```bash
|
||||
( O)> /plan Build a four bedroom house
|
||||
```
|
||||
|
||||
Plan mode in the CLI is a special interaction mode where goose helps break down tasks into manageable steps. If you want to close the plan mode and return to the active session, type `/endplan`.
|
||||
|
||||
```bash
|
||||
( O)> /endplan
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
import ContentCardCarousel from '@site/src/components/ContentCardCarousel';
|
||||
import blogBanner from '@site/blog/2025-12-19-does-your-ai-agent-need-a-plan/blog-banner.png';
|
||||
|
||||
<ContentCardCarousel
|
||||
items={[
|
||||
{
|
||||
type: 'blog',
|
||||
title: 'Does Your AI Agent Need a Plan?',
|
||||
description: 'Knowing when and how to plan with an AI agent can produce better results.',
|
||||
thumbnailUrl: blogBanner,
|
||||
linkUrl: '/blog/2025/12/19/does-your-ai-agent-need-a-plan',
|
||||
date: '2025-12-19',
|
||||
duration: '7 min read'
|
||||
},
|
||||
{
|
||||
type: 'topic',
|
||||
title: 'Planning Complex Tasks',
|
||||
description: 'Learn how to use the Plan feature to break down complex tasks into manageable, executable steps.',
|
||||
linkUrl: '/docs/tutorials/plan-feature-devcontainer-setup',
|
||||
}
|
||||
]}
|
||||
/>
|
||||
@@ -0,0 +1,367 @@
|
||||
---
|
||||
title: Hooks
|
||||
sidebar_position: 5
|
||||
sidebar_label: Hooks
|
||||
---
|
||||
|
||||
# Hooks
|
||||
|
||||
Hooks let you run your own scripts when key events happen during a goose session. Use hooks to log activity, send notifications, format files after edits, run checks after shell commands, or integrate goose with local workflows without writing a custom extension.
|
||||
|
||||
goose follows the [Open Plugins hooks specification](https://open-plugins.com/agent-builders/components/hooks). Hooks are discovered from [plugins](/docs/guides/context-engineering/plugins) on disk and run as shell commands when matching lifecycle events fire.
|
||||
|
||||
:::warning Run trusted hooks only
|
||||
Hooks execute local commands on your machine. Only install or create hooks from sources you trust, and review hook scripts before enabling them.
|
||||
:::
|
||||
|
||||
## Where Hooks Live
|
||||
|
||||
A hook belongs to a [plugin](/docs/guides/context-engineering/plugins) directory. goose discovers plugins from these locations:
|
||||
|
||||
| Scope | Location |
|
||||
|---|---|
|
||||
| User | `~/.agents/plugins/<plugin-name>/` |
|
||||
| Project | `<project>/.agents/plugins/<plugin-name>/` |
|
||||
| Installed plugin | goose's plugin install directory |
|
||||
|
||||
Each plugin that defines hooks must include a `hooks/hooks.json` file:
|
||||
|
||||
```text
|
||||
my-plugin/
|
||||
├── plugin.json
|
||||
├── hooks/
|
||||
│ └── hooks.json
|
||||
└── scripts/
|
||||
└── notify.sh
|
||||
```
|
||||
|
||||
Project plugins are loaded when goose is started from that project. User plugins are available across projects.
|
||||
|
||||
## Create a Hook
|
||||
|
||||
To create any hook, choose the event you want to react to, create a plugin directory, add a `hooks/hooks.json` file that maps that event to a command, then write the script or command that should run. The command receives the event payload as JSON on stdin, so it can inspect details like the session ID, prompt text, tool name, file path, or shell command.
|
||||
|
||||
A hook plugin needs this basic structure:
|
||||
|
||||
```text
|
||||
session-logger/
|
||||
├── plugin.json
|
||||
├── hooks/
|
||||
│ └── hooks.json
|
||||
└── scripts/
|
||||
└── log-session.sh
|
||||
```
|
||||
|
||||
The plugin manifest identifies the plugin:
|
||||
|
||||
```json title="plugin.json"
|
||||
{
|
||||
"name": "session-logger",
|
||||
"version": "0.1.0",
|
||||
"description": "Log goose session events"
|
||||
}
|
||||
```
|
||||
|
||||
The hook configuration maps an event to a command. This example runs a script when the `SessionEnd` event fires:
|
||||
|
||||
```json title="hooks/hooks.json"
|
||||
{
|
||||
"hooks": {
|
||||
"SessionEnd": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${PLUGIN_ROOT}/scripts/log-session.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The script reads the event payload from stdin and performs the automation:
|
||||
|
||||
```bash title="scripts/log-session.sh"
|
||||
#!/usr/bin/env bash
|
||||
payload="$(cat)"
|
||||
session_id="$(printf '%s' "$payload" | jq -r .session_id)"
|
||||
date_str="$(date '+%Y-%m-%d %H:%M')"
|
||||
|
||||
echo "- $date_str — session $session_id ended" >> ~/goose-session-log.md
|
||||
```
|
||||
|
||||
Place the plugin under a discovered plugin location, such as `~/.agents/plugins/session-logger/`, and make command scripts executable when your operating system requires it.
|
||||
|
||||
## Hook Configuration
|
||||
|
||||
`hooks.json` has a top-level `hooks` object. Each key is an event name, and each event contains one or more rules:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "developer__shell|developer__text_editor",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${PLUGIN_ROOT}/scripts/log-tool.sh",
|
||||
"timeout": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Required | Description |
|
||||
|---|---:|---|
|
||||
| `matcher` | No | Regular expression used to decide whether the rule runs for the event. If omitted, the rule runs for every event of that type. |
|
||||
| `hooks` | Yes | Actions to run when the event and matcher apply. |
|
||||
| `type` | No | Action type. goose currently supports `command`. If omitted, `command` is used. |
|
||||
| `command` | Yes for command hooks | Shell command to run. goose runs it with `sh -c`. |
|
||||
| `timeout` | No | Timeout in seconds for the command. Defaults to 30 seconds. |
|
||||
|
||||
Use `${PLUGIN_ROOT}` in a command to reference the plugin directory. goose also sets `PLUGIN_ROOT` in the hook command's environment.
|
||||
|
||||
## Supported Events
|
||||
|
||||
| Event | When it runs | Matcher target |
|
||||
|---|---|---|
|
||||
| `SessionStart` | A session starts | None |
|
||||
| `SessionEnd` | A session ends | None |
|
||||
| `Stop` | goose receives a stop event | None |
|
||||
| `UserPromptSubmit` | The user submits a prompt | Prompt text |
|
||||
| `PreToolUse` | Before goose runs a tool | Tool name |
|
||||
| `PostToolUse` | After a tool succeeds | Tool name |
|
||||
| `PostToolUseFailure` | After a tool fails | Tool name |
|
||||
| `BeforeReadFile` | Before goose reads a file | File path |
|
||||
| `AfterFileEdit` | After goose successfully edits a file | File path |
|
||||
| `BeforeShellExecution` | Before goose runs a shell command | Shell command |
|
||||
| `AfterShellExecution` | After goose successfully runs a shell command | Shell command |
|
||||
|
||||
The matcher is a regular expression matched against the most relevant string for the event. For example, use `"\\.rs$"` to match Rust files on `AfterFileEdit`, or `"^(cargo test|pnpm test)"` to match test commands on `AfterShellExecution`.
|
||||
|
||||
:::note
|
||||
`AfterFileEdit` and `AfterShellExecution` only run after successful tool calls. To react to failed edits, failed shell commands, or other failed tool calls, use `PostToolUseFailure`.
|
||||
:::
|
||||
|
||||
## Hook Payload
|
||||
|
||||
When a hook runs, goose writes a JSON payload to the command's stdin. The payload always includes the event name and session ID, and may include fields such as the tool name, tool input, user message, or working directory.
|
||||
|
||||
Example payload for a tool event:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "PostToolUse",
|
||||
"session_id": "abc-123",
|
||||
"matcher_context": "developer__shell",
|
||||
"tool_name": "developer__shell",
|
||||
"tool_input": { "command": "rg TODO" },
|
||||
"working_dir": "/Users/you/project"
|
||||
}
|
||||
```
|
||||
|
||||
Example script that reads the payload:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
payload="$(cat)"
|
||||
event="$(printf '%s' "$payload" | jq -r .event)"
|
||||
tool="$(printf '%s' "$payload" | jq -r '.tool_name // "none"')"
|
||||
|
||||
echo "goose hook: event=$event tool=$tool" >> "${PLUGIN_ROOT}/hook.log"
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Notify When a Tool Fails
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUseFailure": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${PLUGIN_ROOT}/scripts/notify.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash title="scripts/notify.sh"
|
||||
#!/usr/bin/env bash
|
||||
payload="$(cat)"
|
||||
tool="$(printf '%s' "$payload" | jq -r '.tool_name // "tool"')"
|
||||
|
||||
osascript -e "display notification \"$tool failed\" with title \"goose\""
|
||||
```
|
||||
|
||||
### Format Files After goose Edits Them
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"AfterFileEdit": [
|
||||
{
|
||||
"matcher": "\\.(ts|tsx|js|jsx|json|md)$",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${PLUGIN_ROOT}/scripts/prettier.sh"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"matcher": "\\.rs$",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "cargo fmt"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash title="scripts/prettier.sh"
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
payload="$(cat)"
|
||||
file="$(printf '%s' "$payload" | jq -r '.matcher_context // empty')"
|
||||
|
||||
if [ -n "$file" ]; then
|
||||
npx prettier --write "$file"
|
||||
fi
|
||||
```
|
||||
|
||||
### React to Long-Running Commands
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"AfterShellExecution": [
|
||||
{
|
||||
"matcher": "^(cargo (test|build|clippy)|pnpm (test|build)|just )",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "say 'goose finished running your command'"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Try the Example Plugin
|
||||
|
||||
goose includes an example plugin at `examples/plugins/hello-hooks`.
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.agents/plugins
|
||||
cp -R examples/plugins/hello-hooks ~/.agents/plugins/hello-hooks
|
||||
chmod +x ~/.agents/plugins/hello-hooks/scripts/announce.sh
|
||||
|
||||
goose session
|
||||
```
|
||||
|
||||
The example prints hook events to stderr and appends full payloads to:
|
||||
|
||||
```text
|
||||
~/.agents/plugins/hello-hooks/last-event.log
|
||||
```
|
||||
|
||||
## Disable a Hook Plugin
|
||||
|
||||
To disable a plugin, add its name to `disabledPlugins` in your goose settings file:
|
||||
|
||||
```json title="~/.config/goose/settings.json"
|
||||
{
|
||||
"disabledPlugins": ["session-logger"]
|
||||
}
|
||||
```
|
||||
|
||||
For project-specific settings, use:
|
||||
|
||||
```text
|
||||
<project>/.config/goose/settings.json
|
||||
```
|
||||
|
||||
A plugin listed in `disabledPlugins` is skipped during plugin discovery, so its hooks will not run.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### My Hook Did Not Run
|
||||
|
||||
Check the following:
|
||||
|
||||
- The plugin directory is under `~/.agents/plugins/<name>/` or `<project>/.agents/plugins/<name>/`.
|
||||
- The hook config is at `hooks/hooks.json` inside the plugin directory.
|
||||
- The event name matches one of the [supported events](#supported-events).
|
||||
- The `matcher` regular expression matches the event's matcher target.
|
||||
- The command path is correct. Use `${PLUGIN_ROOT}` for scripts inside the plugin.
|
||||
- The script is executable if you call it directly.
|
||||
- The plugin is not listed in `disabledPlugins`.
|
||||
|
||||
### My Hook Timed Out or Failed
|
||||
|
||||
Hook failures are logged but do not crash goose or the tool that triggered the hook. If a hook fails or exceeds its timeout, goose logs the failure and continues.
|
||||
|
||||
Set a larger timeout for long-running hooks:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionEnd": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${PLUGIN_ROOT}/scripts/archive.sh",
|
||||
"timeout": 120
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### My Script Cannot Find `jq` or Another Command
|
||||
|
||||
Hooks run as local shell commands. Make sure any commands your script uses are installed and available on your shell `PATH`. For portability, prefer absolute paths for tools that may not be installed everywhere.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
import ContentCardCarousel from '@site/src/components/ContentCardCarousel';
|
||||
import hooksBanner from '@site/static/img/blog/goose-hooks.jpg';
|
||||
|
||||
<ContentCardCarousel
|
||||
items={[
|
||||
{
|
||||
type: 'blog',
|
||||
title: 'Hooks: run your own scripts on every goose event',
|
||||
description: 'Learn how lifecycle hooks let you react to session, prompt, tool, file, and shell events with your own scripts.',
|
||||
thumbnailUrl: hooksBanner,
|
||||
linkUrl: '/blog/2026/05/14/goose-hooks',
|
||||
date: '2026-05-14',
|
||||
duration: '5 min read'
|
||||
}
|
||||
]}
|
||||
/>
|
||||
@@ -25,15 +25,45 @@ import styles from '@site/src/components/Card/styles.module.css';
|
||||
description="Create reusable instruction sets containing workflows, scripts, and other resources that goose can load on demand."
|
||||
link="/docs/guides/context-engineering/using-skills"
|
||||
/>
|
||||
<Card
|
||||
title="Plugins"
|
||||
description="Install, update, and manage packages that extend goose with skills, hooks, and other reusable components."
|
||||
link="/docs/guides/context-engineering/plugins"
|
||||
/>
|
||||
<Card
|
||||
title="Hooks"
|
||||
description="Run scripts when goose starts sessions, submits prompts, calls tools, edits files, or executes shell commands."
|
||||
link="/docs/guides/context-engineering/hooks"
|
||||
/>
|
||||
<Card
|
||||
title="Custom Slash Commands"
|
||||
description="Create custom shortcuts to quickly run reusable instructions in any chat session with simple slash commands."
|
||||
link="/docs/guides/context-engineering/slash-commands"
|
||||
/>
|
||||
<Card
|
||||
title="Prompt Templates"
|
||||
description="Customize the built-in prompts that define how goose responds, plans, compacts context, and creates recipes."
|
||||
link="/docs/guides/context-engineering/prompt-templates"
|
||||
/>
|
||||
<Card
|
||||
title="Subagents"
|
||||
description="Delegate focused tasks to isolated goose instances that can run sequentially or in parallel."
|
||||
link="/docs/guides/context-engineering/subagents"
|
||||
/>
|
||||
<Card
|
||||
title="Using gooseignore"
|
||||
description="Prevent goose from accessing sensitive files and directories by defining global or project-specific ignore rules."
|
||||
link="/docs/guides/context-engineering/using-gooseignore"
|
||||
/>
|
||||
<Card
|
||||
title="Creating Plans"
|
||||
description="Use planning mode to break complex work into clear, manageable steps before goose starts implementation."
|
||||
link="/docs/guides/context-engineering/creating-plans"
|
||||
/>
|
||||
<Card
|
||||
title="Persistent Instructions"
|
||||
description="Inject critical reminders into goose's working memory every turn. Ideal for security guardrails and behavioral rules that must never be forgotten."
|
||||
link="/docs/guides/using-persistent-instructions"
|
||||
link="/docs/guides/context-engineering/using-persistent-instructions"
|
||||
/>
|
||||
<Card
|
||||
title="Memory Extension"
|
||||
@@ -66,5 +96,10 @@ import styles from '@site/src/components/Card/styles.module.css';
|
||||
description="Why do AI agents forget? Learn how context windows, tokens, and goose help you manage memory and long conversations."
|
||||
link="/blog/2025/08/18/understanding-context-windows"
|
||||
/>
|
||||
<Card
|
||||
title="Hooks: run your own scripts on every goose event"
|
||||
description="Learn how lifecycle hooks let you react to session, prompt, tool, file, and shell events with your own scripts."
|
||||
link="/blog/2026/05/14/goose-hooks"
|
||||
/>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -0,0 +1,216 @@
|
||||
---
|
||||
title: Plugins
|
||||
sidebar_position: 6
|
||||
sidebar_label: Plugins
|
||||
---
|
||||
|
||||
# Plugins
|
||||
|
||||
Plugins are packages that extend goose with reusable components. A plugin can provide [skills](/docs/guides/context-engineering/using-skills), [hooks](/docs/guides/context-engineering/hooks), or both.
|
||||
|
||||
Use plugins when you want to install, share, or update a bundle of goose functionality instead of copying individual files into your local skills or hooks directories.
|
||||
|
||||
:::warning Install trusted plugins only
|
||||
Plugins can include instructions that goose may load and hooks that execute local commands. Install plugins only from sources you trust, and review plugin contents before enabling them.
|
||||
:::
|
||||
|
||||
## What Plugins Can Provide
|
||||
|
||||
| Component | What it does |
|
||||
|---|---|
|
||||
| Skills | Reusable instructions and supporting files that teach goose how to perform a task or follow a workflow. |
|
||||
| Hooks | Local commands that run when lifecycle events happen during a goose session. |
|
||||
|
||||
A plugin is the container. Skills and hooks are components inside that container.
|
||||
|
||||
## Plugin Structure
|
||||
|
||||
A plugin is a directory with a plugin manifest and optional component directories. A plugin that includes both skills and hooks can look like this:
|
||||
|
||||
```text
|
||||
my-plugin/
|
||||
├── plugin.json
|
||||
├── skills/
|
||||
│ └── review/
|
||||
│ └── SKILL.md
|
||||
├── hooks/
|
||||
│ └── hooks.json
|
||||
└── scripts/
|
||||
└── notify.sh
|
||||
```
|
||||
|
||||
The plugin manifest identifies the plugin:
|
||||
|
||||
```json title="plugin.json"
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "Reusable skills and hooks for my team"
|
||||
}
|
||||
```
|
||||
|
||||
### Add a Skill to a Plugin
|
||||
|
||||
To add a skill to a plugin, place a skill directory under the plugin's `skills/` directory. Each skill directory contains a `SKILL.md` file:
|
||||
|
||||
```text
|
||||
my-plugin/
|
||||
└── skills/
|
||||
└── review/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
```markdown title="skills/review/SKILL.md"
|
||||
---
|
||||
name: review
|
||||
description: Review code changes for correctness, maintainability, and test coverage
|
||||
---
|
||||
|
||||
Review the code changes. Prioritize correctness issues, security concerns, missing tests, and maintainability risks. Be direct and suggest concrete fixes.
|
||||
```
|
||||
|
||||
For Open Plugins, goose namespaces imported skill names with the plugin name. The `review` skill in `my-plugin` is loaded as `my-plugin:review`.
|
||||
|
||||
### Add a Hook to a Plugin
|
||||
|
||||
To add a hook to a plugin, create `hooks/hooks.json` and map lifecycle events to commands:
|
||||
|
||||
```text
|
||||
my-plugin/
|
||||
├── hooks/
|
||||
│ └── hooks.json
|
||||
└── scripts/
|
||||
└── notify.sh
|
||||
```
|
||||
|
||||
```json title="hooks/hooks.json"
|
||||
{
|
||||
"hooks": {
|
||||
"SessionEnd": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${PLUGIN_ROOT}/scripts/notify.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Hook commands receive the event payload as JSON on stdin. Use `${PLUGIN_ROOT}` to reference files inside the plugin directory.
|
||||
|
||||
For supported events, payload details, and more hook examples, see the [Hooks guide](/docs/guides/context-engineering/hooks).
|
||||
|
||||
## Plugin Locations
|
||||
|
||||
goose discovers plugins from these locations:
|
||||
|
||||
| Plugin type | Location | Notes |
|
||||
|---|---|---|
|
||||
| User plugin | `~/.agents/plugins/<plugin-name>/` | Includes plugins installed with `goose plugin install` and plugins manually copied into your user plugins directory. |
|
||||
| Project plugin | `<project>/.agents/plugins/<plugin-name>/` | Available when goose is working in that project. |
|
||||
|
||||
Installed and manually placed user plugins use the same user plugins directory. Installed plugins include metadata created by `goose plugin install`; only installed git-backed plugins can be updated with `goose plugin update`.
|
||||
|
||||
## Install a Plugin
|
||||
|
||||
Install a plugin from a git repository with:
|
||||
|
||||
```bash
|
||||
goose plugin install https://github.com/example/my-goose-plugin.git
|
||||
```
|
||||
|
||||
The install command clones the repository, detects the plugin format, copies it into the plugins directory, and reports the imported components.
|
||||
|
||||
Example output:
|
||||
|
||||
```text
|
||||
✓ Installed open-plugins plugin 'my-plugin' (1.0.0)
|
||||
Source: https://github.com/example/my-goose-plugin.git
|
||||
Location: /Users/you/.agents/plugins/my-plugin
|
||||
Imported skills:
|
||||
- my-plugin:review
|
||||
- my-plugin:test-plan
|
||||
```
|
||||
|
||||
## Auto-Update a Plugin
|
||||
|
||||
To let goose check a plugin for updates automatically, install it with `--auto-update`:
|
||||
|
||||
```bash
|
||||
goose plugin install --auto-update https://github.com/example/my-goose-plugin.git
|
||||
```
|
||||
|
||||
When auto-update is enabled, goose checks that plugin for updates before plugin skills are loaded. Auto-update checks are rate-limited, so goose does not clone the repository on every session start.
|
||||
|
||||
If an auto-update fails, goose logs the failure and continues using the currently installed plugin.
|
||||
|
||||
:::note
|
||||
Auto-update is available for git-backed plugins installed with `goose plugin install --auto-update`. Plugins copied manually into `.agents/plugins/` are discovered, but they are not managed by the plugin update command.
|
||||
:::
|
||||
|
||||
## Update a Plugin Manually
|
||||
|
||||
To update a git-backed plugin on demand, run:
|
||||
|
||||
```bash
|
||||
goose plugin update <plugin-name>
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
goose plugin update my-plugin
|
||||
```
|
||||
|
||||
The update command fetches the plugin from its original git source, replaces the installed copy, and preserves whether auto-update was enabled for that plugin.
|
||||
|
||||
## Disable a Plugin
|
||||
|
||||
To disable a plugin globally, add its name to `disabledPlugins` in your user goose settings file:
|
||||
|
||||
```json title="~/.config/goose/settings.json"
|
||||
{
|
||||
"disabledPlugins": ["my-plugin"]
|
||||
}
|
||||
```
|
||||
|
||||
For project-specific settings, use:
|
||||
|
||||
```text
|
||||
<project>/.config/goose/settings.json
|
||||
```
|
||||
|
||||
For local-only project settings that should not be shared with teammates, use:
|
||||
|
||||
```text
|
||||
<project>/.config/goose/settings.local.json
|
||||
```
|
||||
|
||||
A disabled plugin is skipped during plugin discovery, so its skills are not loaded and its hooks do not run.
|
||||
|
||||
## Plugin Formats
|
||||
|
||||
goose supports these plugin formats:
|
||||
|
||||
| Format | Common files | Notes |
|
||||
|---|---|---|
|
||||
| Open Plugins | `plugin.json`, `.plugin/plugin.json`, `.goose-plugin/plugin.json`, `skills/`, `hooks/hooks.json` | Supports Open Plugins skills and hooks. |
|
||||
| Gemini extensions | `gemini-extension.json`, `skills/` | Supports skills from Gemini-style extension repositories. |
|
||||
|
||||
For Open Plugins, imported skill names are namespaced with the plugin name, such as `my-plugin:review`. Use that full name when explicitly loading a plugin-provided skill. Gemini extension skills keep the skill name from `SKILL.md`; goose does not prefix them with the extension name.
|
||||
|
||||
Open Plugins can use `plugin.json` at the plugin root, `.plugin/plugin.json`, or `.goose-plugin/plugin.json`. Hook-only Open Plugins can be discovered from `hooks/hooks.json`; if no manifest is present, goose infers the plugin name from the source or directory name.
|
||||
|
||||
## When to Use Plugins, Skills, or Hooks
|
||||
|
||||
| Use | Best fit |
|
||||
|---|---|
|
||||
| Package and distribute reusable goose components | Plugin |
|
||||
| Teach goose a reusable procedure or domain-specific workflow | Skill |
|
||||
| Run a local command when goose session events happen | Hook |
|
||||
|
||||
Plugins are for packaging and distribution. Skills and hooks define the behavior goose can use once the plugin is installed or discovered.
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
title: Customizing Prompt Templates
|
||||
sidebar_label: Prompt Templates
|
||||
description: Learn how to customize the prompt templates that define goose's behavior in different situations
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import { PanelLeft } from 'lucide-react';
|
||||
|
||||
goose comes with built-in prompt templates that guide its behavior in different situations. You can edit these templates to customize how goose responds, creates plans, decides what to save during compaction, and more.
|
||||
|
||||
## How It Works
|
||||
|
||||
goose's default prompt templates are defined in the codebase and embedded in the application. You can override any default by creating a custom version in your local config directory (either directly or via goose Desktop).
|
||||
|
||||
When you customize a template:
|
||||
|
||||
- Your customizations persist across goose updates
|
||||
- Changes to defaults in the codebase don't affect your customized templates
|
||||
- You can reset to default templates at any time
|
||||
- Changes take effect in new sessions
|
||||
|
||||
Your changes can range from major updates to minor adjustments such as:
|
||||
- Edit `system.md` to have goose respond in Dutch by adding an instruction to "Reply in Dutch"
|
||||
- Edit `plan.md` to add time estimates by adding instructions to "Include an estimated time for each step (e.g., "~5 min", "~30 min", "~2 hours")."
|
||||
|
||||
See [Template Variable Syntax](#template-variable-syntax) for important information about modifying template variables.
|
||||
|
||||
:::info Related Configuration
|
||||
Other goose settings and features can also affect behavior or provide context, such as [config files](/docs/guides/config-files), [.goosehints](/docs/guides/context-engineering/using-goosehints), and [skills](/docs/guides/context-engineering/using-skills).
|
||||
:::
|
||||
|
||||
## Managing Prompt Templates
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="ui" label="goose Desktop" default>
|
||||
|
||||
goose Desktop users can manage templates from the `Settings` page.
|
||||
|
||||
**To customize a template:**
|
||||
|
||||
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
|
||||
2. Click `Settings` in the sidebar
|
||||
3. Click the `Prompts` tab
|
||||
4. Click `Edit` next to the template you want to change
|
||||
5. Make your changes in the editor. You can click `Restore Default` to start over from the default template at any time.
|
||||
6. Click `Save` to apply your customization
|
||||
|
||||
Customized prompt templates display a `Customized` badge.
|
||||
|
||||
**To reset a template to its default:**
|
||||
|
||||
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
|
||||
2. Click `Settings` in the sidebar
|
||||
3. Click the `Prompts` tab
|
||||
4. Click `Edit` next to the template you want to reset
|
||||
5. Click `Reset to Default` to delete your local template file
|
||||
|
||||
Or click `Reset All` at the top of the tab to delete all of your local template files.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="cli" label="goose CLI">
|
||||
|
||||
goose CLI users can edit template files directly in the file system.
|
||||
|
||||
Custom templates are stored in:
|
||||
|
||||
- **macOS/Linux:** `~/.config/goose/prompts/`
|
||||
- **Windows:** `%APPDATA%\Block\goose\config\prompts\`
|
||||
|
||||
**To customize a template:**
|
||||
|
||||
1. Create the `prompts` directory if it doesn't exist
|
||||
2. Copy the template file name from the table above (e.g., `system.md`)
|
||||
3. Create a file with that name in your prompts directory
|
||||
4. Add your custom content and save your changes. We recommend that you start by reviewing or copying the default template (linked in the [table](#available-prompt-templates) above).
|
||||
|
||||
**To reset a template to its default:**
|
||||
|
||||
1. Delete the template file from your `prompts` directory
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Available Prompt Templates
|
||||
|
||||
The following default templates can be customized.
|
||||
|
||||
| Template | Description | Applies To |
|
||||
|----------|-------------|------------|
|
||||
| [system.md](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/prompts/system.md) | General system prompt defining goose's role, capabilities, and response format | Desktop and CLI |
|
||||
| [apps_create.md](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/prompts/apps_create.md) | Prompt for generating new standalone apps (in development) | Desktop only |
|
||||
| [apps_iterate.md](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/prompts/apps_iterate.md) | Prompt for updating existing standalone apps (in development) | Desktop only |
|
||||
| [compaction.md](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/prompts/compaction.md) | Prompt for summarizing conversation history when context limits are reached | Desktop and CLI |
|
||||
| [permission_judge.md](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/prompts/permission_judge.md) | Prompt for analyzing tool operations for read-only detection | Desktop and CLI |
|
||||
| [plan.md](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/prompts/plan.md) | Instructions for creating detailed, actionable plans with clarifying questions | CLI only |
|
||||
| [recipe.md](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/prompts/recipe.md) | Prompt for generating recipe files from conversations | Desktop and CLI |
|
||||
| [subagent_system.md](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/prompts/subagent_system.md) | System prompt for subagents spawned to handle specific tasks | Desktop and CLI |
|
||||
|
||||
Customizable templates are enumerated in the `TEMPLATE_REGISTRY` array in [`prompt_template.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/prompt_template.rs).
|
||||
|
||||
### Template Variable Syntax
|
||||
|
||||
Templates use [Jinja2](https://jinja.palletsprojects.com/) syntax for dynamic content:
|
||||
|
||||
- `{{ variable }}` - Inserts a value (e.g., `{{ extensions }}` lists enabled extensions)
|
||||
- `{% if condition %}...{% endif %}` - Conditional sections
|
||||
- `{% for item in list %}...{% endfor %}` - Loops over items
|
||||
|
||||
Check out the default templates (linked to from the [table](#available-prompt-templates) above) to find common variables, such as `{{ extensions }}` and `{{ hints }}`.
|
||||
|
||||
#### Escaping Template Variables
|
||||
|
||||
If you need to include literal variable syntax in your templates without substitution, wrap it in single quotes:
|
||||
|
||||
```markdown
|
||||
This will substitute: {{ variable }}
|
||||
This will appear literally: {{'{{variable}}'}}
|
||||
```
|
||||
|
||||
:::warning
|
||||
Be careful when modifying template variables, as incorrect changes can break functionality. Test your changes in a new session to ensure they work as expected.
|
||||
:::
|
||||
|
||||
## Additional Resources
|
||||
|
||||
import ContentCardCarousel from '@site/src/components/ContentCardCarousel';
|
||||
import promptBanner from '@site/blog/2025-03-19-better-ai-prompting/prompt.png';
|
||||
|
||||
<ContentCardCarousel
|
||||
items={[
|
||||
{
|
||||
type: 'blog',
|
||||
title: 'AI Prompting 101: How to Get the Best Responses from Your AI Agent',
|
||||
description: 'Learn different prompting styles—from instruction-based to chain-of-thought—and discover which approach works best for your needs.',
|
||||
thumbnailUrl: promptBanner,
|
||||
linkUrl: '/blog/2025/03/19/better-ai-prompting',
|
||||
date: '2025-03-19',
|
||||
duration: '8 min read'
|
||||
}
|
||||
]}
|
||||
/>
|
||||
@@ -0,0 +1,424 @@
|
||||
---
|
||||
title: Subagents
|
||||
sidebar_position: 2
|
||||
sidebar_label: Subagents
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
Subagents are independent instances that execute tasks while keeping your main conversation clean and focused. Think of them as temporary assistants that handle specific jobs, bringing process isolation and context preservation by offloading work to separate instances.
|
||||
|
||||
<details>
|
||||
<summary>Subagents Walkthrough</summary>
|
||||
<iframe
|
||||
class="aspect-ratio"
|
||||
src="https://youtube.com/embed/Uk4TtJUykK4"
|
||||
title="Subagents Explained"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
</details>
|
||||
|
||||
## How to Use Subagents
|
||||
|
||||
:::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 [permission mode](/docs/guides/managing-tools/goose-permissions) (the default). Subagents are disabled in manual approval, smart approval, and chat-only modes.
|
||||
:::
|
||||
|
||||
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.
|
||||
|
||||
| Type | Description | Trigger Keywords | Example |
|
||||
|------|-------------|------------------|---------|
|
||||
| **Sequential** (Default) | Tasks execute one after another | "first...then", "after" | `"First analyze the code, then generate documentation"` |
|
||||
| **Parallel** | Tasks execute simultaneously | "parallel", "simultaneously", "at the same time", "concurrently" | `"Create three HTML templates in parallel"` |
|
||||
|
||||
## Monitoring Subagent Activity
|
||||
|
||||
When goose delegates work to a subagent, you can see the subagent's tool calls in real-time. This transparency helps you understand what the subagent is doing and verify it's on the right track.
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="desktop" label="goose Desktop" default>
|
||||
Subagent tool calls appear as expandable sections within the conversation. Click to expand and see the full details of each tool call, including:
|
||||
- The tool name being invoked
|
||||
- Arguments passed to the tool
|
||||
- Tool output and results
|
||||
</TabItem>
|
||||
<TabItem value="cli" label="goose CLI">
|
||||
Subagent tool calls are displayed inline with visual indicators showing the tool name and extension. For example:
|
||||
|
||||
```text
|
||||
[subagent:16] text_editor | developer
|
||||
```
|
||||
|
||||
Each tool call shows:
|
||||
- The subagent identifier (e.g., `subagent:16`)
|
||||
- The tool name (e.g., `text_editor`)
|
||||
- The extension providing the tool (e.g., `developer`)
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::info
|
||||
If a subagent fails or times out (5-minute default), you will receive no output from that subagent. For parallel execution, if any subagent fails, you get results only from the successful ones.
|
||||
:::
|
||||
|
||||
## 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:**
|
||||
```
|
||||
"Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel"
|
||||
```
|
||||
|
||||
**Tool Output:**
|
||||
```json
|
||||
{
|
||||
"execution_summary": {
|
||||
"total_tasks": 2,
|
||||
"successful_tasks": 2,
|
||||
"failed_tasks": 0,
|
||||
"execution_time_seconds": 16.2
|
||||
},
|
||||
"task_results": [
|
||||
{
|
||||
"task_id": "create_hello_html",
|
||||
"status": "success",
|
||||
"result": "Successfully created hello.html with Hello World content"
|
||||
},
|
||||
{
|
||||
"task_id": "create_goodbye_html",
|
||||
"status": "success",
|
||||
"result": "Successfully created goodbye.html with Goodbye World content"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Recipes
|
||||
Use [recipe](/docs/guides/recipes/) files to define specific instructions, extensions, and behavior for subagents. Recipes provide reusable configurations that can be shared and referenced by name.
|
||||
|
||||
**Creating a Recipe File**
|
||||
|
||||
`code-reviewer.yaml`
|
||||
|
||||
```yaml
|
||||
id: code-reviewer
|
||||
version: 1.0.0
|
||||
title: "Code Review Assistant"
|
||||
description: "Specialized subagent for code quality and security analysis"
|
||||
instructions: |
|
||||
You are a code review assistant. Analyze code and provide feedback on:
|
||||
- Code quality and readability
|
||||
- Security vulnerabilities
|
||||
- Performance issues
|
||||
- Best practices adherence
|
||||
activities:
|
||||
- Analyze code structure
|
||||
- Check for security issues
|
||||
- Review performance patterns
|
||||
extensions:
|
||||
- type: builtin
|
||||
name: developer
|
||||
display_name: Developer
|
||||
timeout: 300
|
||||
bundled: true
|
||||
parameters:
|
||||
- key: focus_area
|
||||
input_type: string
|
||||
requirement: optional
|
||||
description: "Specific area to focus on (security, performance, readability, etc.)"
|
||||
default: "general"
|
||||
prompt: |
|
||||
Please review the following code focusing on {{focus_area}} aspects.
|
||||
Provide specific, actionable feedback with examples.
|
||||
```
|
||||
|
||||
**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**
|
||||
```
|
||||
Use the "code-reviewer" recipe to analyze the authentication feature I implemented
|
||||
```
|
||||
|
||||
**goose Output**
|
||||
```
|
||||
I'll use your code-reviewer recipe to create a specialized subagent for this analysis.
|
||||
|
||||
🤖 Subagent created using code-reviewer recipe
|
||||
💭 Analyzing authentication function for security issues...
|
||||
🔧 Scanning code structure and patterns...
|
||||
⚠️ Security vulnerabilities detected!
|
||||
|
||||
## Code Review Results
|
||||
|
||||
### Critical Issues Found:
|
||||
1. **SQL Injection Vulnerability**: Direct string interpolation in SQL query
|
||||
2. **Missing Password Hashing**: Plain text password comparison
|
||||
|
||||
### Recommendations:
|
||||
- Use parameterized queries or ORM
|
||||
- Implement proper password hashing (bcrypt, scrypt)
|
||||
- Add input validation and sanitization
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
**[goose Configuration File](/docs/guides/config-files)** (`.~/.config/goose/config.yaml `):
|
||||
```yaml
|
||||
subagent:
|
||||
args:
|
||||
- mcp-server
|
||||
bundled: true
|
||||
cmd: codex
|
||||
description: OpenAI Codex CLI Subagent
|
||||
enabled: true
|
||||
env_keys:
|
||||
- OPENAI_API_KEY
|
||||
envs: {}
|
||||
name: subagent
|
||||
timeout: 300
|
||||
type: stdio
|
||||
```
|
||||
|
||||
**External Tool Configuration** (`~/.codex/config.toml`):
|
||||
```toml
|
||||
# Use fast model for quick responses
|
||||
# model = "codex-mini-latest"
|
||||
disable_response_storage = true
|
||||
|
||||
# Never prompt for approval - auto-execute
|
||||
approval_policy = "never"
|
||||
|
||||
[sandbox]
|
||||
mode = "workspace-write"
|
||||
```
|
||||
|
||||
**goose Prompt:**
|
||||
```
|
||||
"Use the codex subagent to analyze my codebase structure and identify the main components"
|
||||
```
|
||||
|
||||
**goose Output:**
|
||||
|
||||
```md
|
||||
Based on my analysis of your codebase, here are the main components:
|
||||
|
||||
1. **Core Agent System** (`crates/goose/src/agents/`)
|
||||
- Agent orchestration and session management
|
||||
- Tool execution framework
|
||||
- Extension system integration
|
||||
|
||||
2. **CLI Interface** (`crates/goose-cli/`)
|
||||
- Command-line interface and session handling
|
||||
- Configuration management
|
||||
|
||||
3. **Server Components** (`crates/goose-server/`)
|
||||
- HTTP API endpoints
|
||||
- WebSocket communication for real-time interaction
|
||||
|
||||
4. **Desktop UI** (`ui/desktop/`)
|
||||
- Electron-based desktop application
|
||||
- TypeScript frontend with React components
|
||||
|
||||
The architecture follows a modular design with clear separation between the core agent logic, interfaces, and UI components.
|
||||
```
|
||||
|
||||
## Suggested Use Cases
|
||||
|
||||
**Independent Operations**
|
||||
- Creating multiple files with similar structure
|
||||
- Basic data processing tasks
|
||||
- File transformations and generations
|
||||
|
||||
**Context Preservation**
|
||||
- Complex analysis that generates lots of tool output
|
||||
- Specialized tasks better handled by dedicated agents
|
||||
- Keeping main conversation focused on high-level decisions
|
||||
|
||||
**Process Isolation**
|
||||
- Tasks that might fail without affecting main workflow
|
||||
- Operations requiring different configurations
|
||||
- Experimental or exploratory work
|
||||
|
||||
## Lifecycle and Cleanup
|
||||
|
||||
Subagents are temporary instances that exist only for task execution. After the task is completed, no manual intervention is needed for cleanup.
|
||||
|
||||
## Configuration
|
||||
|
||||
Subagents use the following pre-configured settings, but you can override any defaults using natural language in your prompts.
|
||||
|
||||
### Default Settings
|
||||
| Parameter | Default | How to Customize |
|
||||
|-----------|---------|------------------|
|
||||
| **Max Turns** | 25 | Use natural language, set `GOOSE_SUBAGENT_MAX_TURNS`, or configure `settings.max_turns` in [recipes](/docs/guides/recipes/recipe-reference#settings) or subagent tool calls |
|
||||
| **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 |
|
||||
|
||||
:::tip Advanced Customization
|
||||
You can also customize subagent behavior by editing the `subagent_system.md` [prompt template](/docs/guides/context-engineering/prompt-templates).
|
||||
:::
|
||||
|
||||
### 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.
|
||||
|
||||
:::note Summon Extension
|
||||
The `delegate` and `load` tools are provided by the `summon` platform extension, which is enabled by default. If you are using a [recipe](/docs/guides/recipes/) with an explicit `extensions` block, you must include `summon` in that list or the `delegate` tool will not be available:
|
||||
|
||||
```yaml
|
||||
extensions:
|
||||
- type: platform
|
||||
name: summon
|
||||
# ... your other extensions
|
||||
```
|
||||
|
||||
Recipes that define [`sub_recipes`](/docs/guides/recipes/subrecipes) have `summon` auto-injected.
|
||||
:::
|
||||
|
||||
**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
|
||||
Choose how much information goose provides from its subagents in your main session.
|
||||
|
||||
**Full Details (Default):** See all tool executions and reasoning steps
|
||||
```
|
||||
"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 a subagent to research this topic and summarize the key findings"
|
||||
```
|
||||
|
||||
## Security Constraints
|
||||
|
||||
Subagents operate with restricted tool access to ensure safe execution and prevent interference with the main session.
|
||||
|
||||
### Allowed Operations
|
||||
|
||||
Subagents have access to these safe operations:
|
||||
|
||||
- **Extension discovery**: Search for available extensions to understand what tools are available
|
||||
- **Resource access**: Read and list resources from enabled extensions for context
|
||||
- **Extension tools**: Use tools from extensions specified in recipes or inherited from the parent session
|
||||
|
||||
### Restricted Operations
|
||||
|
||||
The following operations are blocked to ensure subagents remain focused on their assigned tasks without affecting the broader system state:
|
||||
|
||||
- **Subagent spawning**: Cannot create additional subagents to prevent infinite recursion
|
||||
- **Extension management**: Cannot enable, disable, or modify extensions to avoid conflicts with the main session
|
||||
- **Schedule management**: Cannot create, modify, or delete scheduled tasks to prevent interference with parent workflows
|
||||
|
||||
:::info
|
||||
Subagents can browse extensions for suggestions but cannot enable them to avoid modifying the parent session.
|
||||
:::
|
||||
|
||||
## Additional Resources
|
||||
|
||||
import ContentCardCarousel from '@site/src/components/ContentCardCarousel';
|
||||
import subagentsVsSubrecipes from '@site/blog/2025-09-26-subagents-vs-subrecipes/subrecipes-vs-subagents.png';
|
||||
import agentCoordination from '@site/blog/2025-08-14-agent-coordination-patterns/agent-coordination.png';
|
||||
|
||||
<ContentCardCarousel
|
||||
items={[
|
||||
{
|
||||
type: 'blog',
|
||||
title: 'Agents, Subagents, and Multi Agents: What They Are and When to Use Them',
|
||||
description: 'Compare agents, subagents, and multi agents in AI workflows. Learn how they work together and practical scenarios for each approach.',
|
||||
thumbnailUrl: agentCoordination,
|
||||
linkUrl: '/blog/2025/08/14/agent-coordination-patterns',
|
||||
date: '2025-08-14',
|
||||
duration: '4 min read'
|
||||
},
|
||||
{
|
||||
type: 'video',
|
||||
title: 'How I Built an App with 6 Subagents',
|
||||
description: 'Deep dive into goose subagents. Walk through building an app using 6 specialized AI agents for advanced workflow automation and development.',
|
||||
thumbnailUrl: 'https://img.youtube.com/vi/yIBrD5AxtTc/maxresdefault.jpg',
|
||||
linkUrl: 'https://www.youtube.com/watch?v=yIBrD5AxtTc',
|
||||
date: '2025-10-01',
|
||||
duration: '6:53'
|
||||
},
|
||||
{
|
||||
type: 'tutorial',
|
||||
title: 'Tutorial: Using Subagents',
|
||||
description: 'Spin up a team of subagents to build a fully functional app',
|
||||
thumbnailUrl: 'https://goose-docs.ai/assets/images/tutorial-using-subagents-ef265627024db73e73d80e5799ed0c1a.png',
|
||||
linkUrl: '/docs/tutorials/subagents',
|
||||
date: '2026-01-27',
|
||||
duration: '1 hour'
|
||||
},
|
||||
{
|
||||
type: 'video',
|
||||
title: 'Flight School - Choosing the Right Tools for AI Work',
|
||||
description: 'Discover the differences between subagents and subrecipes for efficient task execution in goose. Learn which approach is best for your workflow.',
|
||||
thumbnailUrl: 'https://img.youtube.com/vi/joePzlkARjs/maxresdefault.jpg',
|
||||
linkUrl: 'https://www.youtube.com/watch?v=joePzlkARjs',
|
||||
date: '2025-09-29',
|
||||
duration: '6:13'
|
||||
},
|
||||
{
|
||||
type: 'video',
|
||||
title: 'Flight School - Choosing the Right Tools for AI Work',
|
||||
description: 'Discover the differences between subagents and subrecipes for efficient task execution in goose. Learn which approach is best for your workflow.',
|
||||
thumbnailUrl: 'https://img.youtube.com/vi/joePzlkARjs/maxresdefault.jpg',
|
||||
linkUrl: 'https://www.youtube.com/watch?v=joePzlkARjs',
|
||||
date: '2025-09-29',
|
||||
duration: '6:13'
|
||||
},
|
||||
{
|
||||
type: 'blog',
|
||||
title: 'How to Choose Between Subagents and Subrecipes in goose',
|
||||
description: 'Detailed guide to subagents and subrecipes in goose. Compare reusability, setup complexity, and get practical advice for choosing the right approach.',
|
||||
thumbnailUrl: subagentsVsSubrecipes,
|
||||
linkUrl: '/blog/2025/09/26/subagents-vs-subrecipes',
|
||||
date: '2025-09-26',
|
||||
duration: '6 min read'
|
||||
}
|
||||
]}
|
||||
/>
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: Prevent goose from Accessing Files
|
||||
sidebar_label: Using gooseignore
|
||||
sidebar_position: 9
|
||||
---
|
||||
|
||||
|
||||
`.gooseignore` is a text file that defines patterns for files and directories that goose will not access. This means goose cannot read, modify, delete, or run shell commands on these files when using the Developer extension's tools.
|
||||
|
||||
:::info Developer extension only
|
||||
The .gooseignore feature currently only affects tools in the [Developer](/docs/mcp/developer-mcp) extension. Other extensions are not restricted by these rules.
|
||||
:::
|
||||
|
||||
This guide will show you how to use `.gooseignore` files to prevent goose from changing specific files and directories.
|
||||
|
||||
## Creating your `.gooseignore` file
|
||||
|
||||
goose supports two types of `.gooseignore` files:
|
||||
- **Global ignore file** - Create a `.gooseignore` file in `~/.config/goose`. These restrictions will apply to all your sessions with goose, regardless of directory.
|
||||
- **Local ignore file** - Create a `.gooseignore` file at the root of the directory you'd like it applied to. These restrictions will only apply when working in a specific directory.
|
||||
|
||||
:::tip
|
||||
You can use both global and local `.gooseignore` files simultaneously. When both exist, goose will apply patterns from both files, with local patterns able to override global ones using negation.
|
||||
:::
|
||||
|
||||
## Example `.gooseignore` file
|
||||
|
||||
In your `.gooseignore` file, you can write patterns to match files you want goose to ignore. Here are some common patterns:
|
||||
|
||||
```plaintext
|
||||
# Ignore specific files by name
|
||||
settings.json # Ignore only the file named "settings.json"
|
||||
|
||||
# Ignore files by extension
|
||||
*.pdf # Ignore all PDF files
|
||||
*.config # Ignore all files ending in .config
|
||||
|
||||
# Ignore directories and their contents
|
||||
backup/ # Ignore everything in the "backup" directory
|
||||
downloads/ # Ignore everything in the "downloads" directory
|
||||
|
||||
# Ignore all files with this name in any directory
|
||||
**/credentials.json # Ignore all files named "credentials.json" in any directory
|
||||
```
|
||||
|
||||
## Negation Patterns
|
||||
|
||||
Use the `!` prefix to exclude files from ignore rules. This allows you to ignore broad patterns while allowing specific exceptions.
|
||||
|
||||
Within each `.gooseignore` file, patterns are processed in order from top to bottom, so later patterns can override earlier ones. Negation patterns also work across files - you can use negation in your local `.gooseignore` to allow access to files blocked by your global `.gooseignore`.
|
||||
|
||||
```plaintext
|
||||
# Ignore all environment files
|
||||
**/.env*
|
||||
|
||||
# But allow the example file
|
||||
!.env.example
|
||||
|
||||
# Ignore all log files
|
||||
*.log
|
||||
|
||||
# But allow error logs
|
||||
!error.log
|
||||
|
||||
# Ignore all JSON files in the config directory
|
||||
config/*.json
|
||||
|
||||
# But allow the template
|
||||
!config/template.json
|
||||
```
|
||||
|
||||
:::tip Pattern Order Matters
|
||||
Negation patterns must come after the patterns they're negating. The `!` pattern re-includes files that were previously ignored.
|
||||
:::
|
||||
|
||||
## Ignore File Types and Priority
|
||||
|
||||
goose respects ignore rules from global and local `.gooseignore` files, using a priority system where later patterns can override earlier ones.
|
||||
|
||||
### When You Have Ignore Files
|
||||
|
||||
When `.gooseignore` files exist, patterns are applied in this order:
|
||||
|
||||
1. **Global `.gooseignore`** (applied first)
|
||||
- Located at `~/.config/goose/.gooseignore`
|
||||
- Affects all projects on your machine
|
||||
|
||||
2. **Local `.gooseignore`** (applied second, can override global)
|
||||
- Located in the current working directory (the root of the directory you want these rules applied to)
|
||||
- Project-specific rules that can override global patterns
|
||||
|
||||
```
|
||||
~/.config/goose/
|
||||
└── .gooseignore ← Global patterns applied first
|
||||
|
||||
Project/
|
||||
├── .gooseignore ← Local patterns applied second (can override global)
|
||||
└── src/
|
||||
```
|
||||
|
||||
Because patterns are processed in order, you can use negation patterns in your local `.gooseignore` to allow access to files that were blocked by global patterns.
|
||||
|
||||
**Example: Override global restrictions in a specific project**
|
||||
|
||||
```plaintext
|
||||
# In ~/.config/goose/.gooseignore (global)
|
||||
**/.env* # Block all .env files everywhere
|
||||
|
||||
# In your-project/.gooseignore (local)
|
||||
!.env.example # Allow .env.example in this project only
|
||||
```
|
||||
|
||||
In this example, `.env` and `.env.local` remain blocked, but `.env.example` is accessible in this specific project.
|
||||
|
||||
### Default Patterns (No Ignore Files)
|
||||
|
||||
If you haven't created any `.gooseignore` files (neither global nor local), goose automatically protects these sensitive files:
|
||||
|
||||
```plaintext
|
||||
**/.env
|
||||
**/.env.*
|
||||
**/secrets.*
|
||||
```
|
||||
|
||||
:::info
|
||||
These default patterns are only active when **no** `.gooseignore` files exist. Once you create either a global or local `.gooseignore` file, you'll need to add these patterns yourself if you want to keep them.
|
||||
:::
|
||||
|
||||
## Common use cases
|
||||
|
||||
Here are some typical scenarios where `.gooseignore` is helpful:
|
||||
|
||||
- **Generated Files**: Prevent goose from modifying auto-generated code or build outputs
|
||||
- **Third-Party Code**: Keep goose from changing external libraries or dependencies
|
||||
- **Important Configurations**: Protect critical configuration files from accidental modifications
|
||||
- **Version Control**: Prevent changes to version control files like `.git` directory
|
||||
- **Custom Restrictions**: Create `.gooseignore` files to define which files goose should not access
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: Persistent Instructions
|
||||
sidebar_position: 8
|
||||
sidebar_label: Persistent Instructions
|
||||
---
|
||||
|
||||
Persistent instructions let you inject text into goose's working memory every turn. Unlike [`.goosehints`](/docs/guides/context-engineering/using-goosehints), which are loaded at session start and can expand later when goose discovers nested hint files, persistent instructions are re-read and injected fresh with every interaction. This makes them ideal for behavioral guardrails that must always be enforced, regardless of how the conversation evolves.
|
||||
|
||||
## How It Works
|
||||
|
||||
goose has a component called MOIM (Model-Observed Internal Memory) that provides contextual information to the model every turn. This includes things like the current timestamp, working directory, and your todo list. Persistent instructions are injected into this same context, placing your reminders in the model's immediate attention window.
|
||||
|
||||
Because persistent instructions are injected every turn:
|
||||
- They can't be "forgotten" as the conversation grows
|
||||
- They're more effective than system prompt instructions for critical guardrails
|
||||
- Changes take effect immediately without restarting your session
|
||||
|
||||
## Configuration
|
||||
|
||||
Configure persistent instructions using environment variables:
|
||||
|
||||
| Variable | Purpose | Default |
|
||||
|----------|---------|---------|
|
||||
| [`GOOSE_MOIM_MESSAGE_TEXT`](/docs/guides/environment-variables#session-management) | Literal text injected into working memory each turn | Not set |
|
||||
| [`GOOSE_MOIM_MESSAGE_FILE`](/docs/guides/environment-variables#session-management) | Path to a file whose contents are injected each turn. Supports `~/` | Not set |
|
||||
|
||||
When both variables are set, their contents are concatenated. The extension reads [environment variables](/docs/guides/environment-variables#session-management) fresh every turn, so you can update them without restarting your session.
|
||||
|
||||
:::info Size Limit
|
||||
Content is capped at 64 KB with UTF-8 safe truncation. Keep your instructions concise to avoid hitting this limit and to minimize token usage.
|
||||
:::
|
||||
|
||||
## Examples
|
||||
|
||||
### Simple Text Reminder
|
||||
|
||||
For short, single-purpose reminders, use `GOOSE_MOIM_MESSAGE_TEXT`:
|
||||
|
||||
```bash
|
||||
# Always run tests before committing
|
||||
export GOOSE_MOIM_MESSAGE_TEXT="IMPORTANT: Always run tests before committing changes."
|
||||
```
|
||||
|
||||
### File-Based Instructions
|
||||
|
||||
For longer or more complex instructions, use a file:
|
||||
|
||||
```bash
|
||||
export GOOSE_MOIM_MESSAGE_FILE="~/.goose/guardrails.md"
|
||||
```
|
||||
|
||||
Example `~/.goose/guardrails.md`:
|
||||
```markdown
|
||||
## Security Guidelines
|
||||
- Do not upload, share, or transmit internal code or data to any external service, gist, or public repository
|
||||
- Do not execute commands that could expose sensitive environment variables
|
||||
- Always confirm before making network requests to external services
|
||||
|
||||
## Code Quality
|
||||
- Run tests before committing changes
|
||||
- Follow the project's existing code style
|
||||
```
|
||||
|
||||
### Combining Both
|
||||
|
||||
You can use both variables together. The text is concatenated:
|
||||
|
||||
```bash
|
||||
export GOOSE_MOIM_MESSAGE_TEXT="CRITICAL: This is a production environment. Be extra careful."
|
||||
export GOOSE_MOIM_MESSAGE_FILE="~/.goose/guardrails.md"
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Security Guardrails
|
||||
|
||||
Prevent accidental data exfiltration or exposure:
|
||||
|
||||
```bash
|
||||
export GOOSE_MOIM_MESSAGE_TEXT="SECURITY: Do not upload code to external services, create public gists, or share sensitive data. All code in this repository is confidential."
|
||||
```
|
||||
|
||||
### Environment-Specific Behavior
|
||||
|
||||
Set different instructions for different environments:
|
||||
|
||||
```bash
|
||||
# Production environment
|
||||
export GOOSE_MOIM_MESSAGE_TEXT="⚠️ PRODUCTION: Double-check all commands. Prefer read-only operations. Always create backups before modifications."
|
||||
|
||||
# Development environment
|
||||
export GOOSE_MOIM_MESSAGE_TEXT="Development environment. Feel free to experiment, but run tests before committing."
|
||||
```
|
||||
|
||||
### Project-Specific Workflows
|
||||
|
||||
Enforce project conventions:
|
||||
|
||||
```bash
|
||||
export GOOSE_MOIM_MESSAGE_TEXT="This project uses pnpm, not npm. Always use 'pnpm' for package management commands."
|
||||
```
|
||||
|
||||
### Temporary Reminders
|
||||
|
||||
Since the environment variables are read fresh each turn, you can set temporary reminders:
|
||||
|
||||
```bash
|
||||
# Set a reminder for the current task
|
||||
export GOOSE_MOIM_MESSAGE_TEXT="Current focus: Refactoring the authentication module. Don't get sidetracked."
|
||||
|
||||
# Clear it when done
|
||||
unset GOOSE_MOIM_MESSAGE_TEXT
|
||||
```
|
||||
|
||||
## Persistent Instructions vs goosehints
|
||||
|
||||
| Feature | Persistent Instructions | [goosehints](/docs/guides/context-engineering/using-goosehints) |
|
||||
|---------|------------------------|-------------|
|
||||
| When loaded | Every turn | Session start, plus nested context files discovered during the session |
|
||||
| Can be forgotten | No | Yes, as context fills |
|
||||
| Best for | Critical guardrails, security rules | Project context, coding standards |
|
||||
| Token cost | Per turn | Once at start |
|
||||
| Update requires | No restart | Session restart |
|
||||
|
||||
**Use persistent instructions when:**
|
||||
- The instruction is critical and must never be ignored
|
||||
- You need security guardrails that can't be bypassed
|
||||
- You want to change behavior mid-session without restarting
|
||||
|
||||
**Use goosehints when:**
|
||||
- Providing project context and background information
|
||||
- Setting coding standards and preferences
|
||||
- The information is helpful but not critical
|
||||
|
||||
You can use both together: goosehints for project context and persistent instructions for critical guardrails.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep it concise**: Persistent instructions are injected every turn, so longer text means more tokens used per interaction.
|
||||
|
||||
2. **Be specific**: Vague instructions like "be careful" are less effective than specific ones like "always run `npm test` before committing."
|
||||
|
||||
3. **Prioritize**: Put your most important instructions first, in case of truncation.
|
||||
|
||||
4. **Use files for complex rules**: If you have multiple guidelines, organize them in a file rather than cramming everything into `GOOSE_MOIM_MESSAGE_TEXT`.
|
||||
|
||||
5. **Test your guardrails**: After setting up persistent instructions, test that goose respects them by asking it to do something that should be blocked.
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Using Skills
|
||||
sidebar_position: 2
|
||||
sidebar_label: Using Skills
|
||||
title: Agent Skills
|
||||
sidebar_position: 3
|
||||
sidebar_label: Agent Skills
|
||||
---
|
||||
|
||||
Skills are reusable sets of instructions and resources that teach goose how to perform specific tasks. A skill can range from a simple checklist to a detailed workflow with domain expertise, and can include supporting files like scripts or templates. Example use cases include deployment procedures, code review checklists, and API integration guides.
|
||||
@@ -25,10 +25,11 @@ goose skills are compatible with Claude Desktop and other [agents that support A
|
||||
|
||||
## Skill Locations
|
||||
|
||||
Skills can be stored globally or per-project:
|
||||
Skills can be stored globally, per-project, or in installed plugins:
|
||||
|
||||
1. `~/.agents/skills/` — Global skills, available in all sessions
|
||||
2. `.agents/skills/` — Project-level skills, scoped to the current project
|
||||
3. `~/.agents/plugins/<plugin-name>/` — Skills provided by installed [plugins](/docs/guides/context-engineering/plugins)
|
||||
|
||||
Place a `SKILL.md` file inside a named subdirectory. For example, a global skill called
|
||||
`code-review` goes in `~/.agents/skills/code-review/SKILL.md`.
|
||||
@@ -84,7 +85,11 @@ When reviewing code, check each of these areas:
|
||||
- [ ] SQL queries are parameterized
|
||||
```
|
||||
|
||||
### Supporting Files
|
||||
## Skills from Plugins
|
||||
|
||||
Skills can also come from installed [plugins](/docs/guides/context-engineering/plugins). Plugin-provided skills are discovered at session startup and work like other skills. For Open Plugins, skill names are namespaced with the plugin name, such as `my-plugin:review`. Use that full name when explicitly loading a plugin-provided skill.
|
||||
|
||||
## Supporting Files
|
||||
|
||||
Skills can include supporting files like scripts, templates, or configuration files. Place them in the skill directory:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user