tkmind/tkmind_go
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs: reorganize (#9310)

Browse Source
This commit is contained in:
Angie Jones
2026-05-18 13:38:14 -05:00
committed by GitHub
parent badb97a01e
commit bc9c1fc11a
54 changed files with 458 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/docs/guides/managing-tools/_category_.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"label": "Managing Tools",
"position": 15,
"position": 4,
"link": {
"type": "doc",
"id": "guides/managing-tools/index"
documentation/docs/guides/managing-tools/goose-permissions.md
+161
View File
@@ -0,0 +1,161 @@
---
sidebar_position: 20
title: goose Permission Modes
sidebar_label: goose Permissions
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import { PanelLeft, Tornado } from 'lucide-react';
goose’s permissions determine how much autonomy it has when modifying files, using extensions, and performing automated actions. By selecting a permission mode, you have full control over how goose interacts with your development environment.
<details>
<summary>Permission Modes Video Walkthrough</summary>
<iframe
class="aspect-ratio"
src="https://www.youtube.com/embed/bMVFFnPS_Uk"
title="goose Permission Modes Explained"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
</details>
## Permission Modes
| Mode | Description | Best For |
|------|-------------|----------|
| **Completely Autonomous** | goose can modify files, use extensions, and delete files **without requiring approval** | Users who want **full automation** and seamless integration into their workflow |
| **Manual Approval** | goose **asks for confirmation** before using any tools or extensions (supports granular [tool permissions](/docs/guides/managing-tools/tool-permissions)) | Users who want to **review and approve** every change and tool usage |
| **Smart Approval** | goose uses a risk-based approach to **automatically approve low-risk actions** and **flag others** for approval (supports granular [tool permissions](/docs/guides/managing-tools/tool-permissions)) | Users who want a **balanced mix of autonomy and oversight** based on the action’s impact |
| **Chat Only** | goose **only engages in chat**, with no extension use or file modifications | Users who prefer a **conversational AI experience** for analysis, writing, and reasoning tasks without automation |
:::warning
`Autonomous Mode` is applied by default.
:::
## Configuring goose mode
Here's how to configure:
<Tabs groupId="interface">
<TabItem value="ui" label="goose Desktop" default>
You can change modes before or during a session and it will take effect immediately.
<Tabs groupId="method">
<TabItem value="session" label="In Session" default>
Click the <Tornado className="inline" size={16} /> mode button from the bottom menu.
</TabItem>
<TabItem value="settings" label="From Settings">
1. Click the <PanelLeft className="inline" size={16} /> button on the top-left to open the sidebar.
2. Click the `Settings` button on the sidebar.
3. Click `Chat`.
4. Under `Mode`, choose the mode you'd like.
</TabItem>
</Tabs>
</TabItem>
<TabItem value="cli" label="goose CLI">
<Tabs groupId="method">
<TabItem value="session" label="In Session" default>
To change modes mid-session, use the `/mode` command.
* Autonomous: `/mode auto`
* Smart Approve: `/mode smart_approve`
* Approve: `/mode approve`
* Chat: `/mode chat`
</TabItem>
<TabItem value="settings" label="From Settings">
1. Run the following command:
```sh
goose configure
```
2. Select `goose settings` from the menu and press Enter.
```sh
┌ goose-configure
│
◆ What would you like to configure?
| ○ Configure Providers
| ○ Add Extension
| ○ Toggle Extensions
| ○ Remove Extension
// highlight-start
| ● goose settings (Set the goose mode, Tool Output, Tool Permissions, Experiment, goose recipe github repo and more)
// highlight-end
└
```
3. Choose `goose mode` from the menu and press Enter.
```sh
┌ goose-configure
│
◇ What would you like to configure?
│ goose settings
│
◆ What setting would you like to configure?
// highlight-start
│ ● goose mode (Configure goose mode)
// highlight-end
│ ○ Router Tool Selection Strategy
│ ○ Tool Permission
│ ○ Tool Output
│ ○ Max Turns
│ ○ Toggle Experiment
│ ○ goose recipe github repo
│ ○ Scheduler Type
└
```
4. Choose the goose mode you would like to configure.
```sh
┌ goose-configure
│
◇ What would you like to configure?
│ goose settings
│
◇ What setting would you like to configure?
│ goose mode
│
◆ Which goose mode would you like to configure?
// highlight-start
│ ● Auto Mode (Full file modification, extension usage, edit, create and delete files freely)
// highlight-end
| ○ Approve Mode
| ○ Smart Approve Mode
| ○ Chat Mode
|
└ Set to Auto Mode - full file modification enabled
```
</TabItem>
</Tabs>
</TabItem>
</Tabs>
:::info
In manual and smart approval modes, you will see "Allow" and "Deny" buttons in your session windows during tool calls.
goose will only ask for permission for tools that it deems are 'write' tools, e.g. any 'text editor write', 'text editor edit', 'bash - rm, cp, mv' commands.
Read/write approval makes best effort attempt at classifying read or write tools. This is interpreted by your LLM provider.
:::
## CLI Provider Permission Integration
When using [CLI providers](/docs/guides/cli-providers) like Claude Code, goose integrates with the provider's native permission system. In approve mode, permission requests from Claude Code are routed through goose's confirmation interface, giving you a unified experience.
For example, with Claude Code in approve mode:
- Claude Code detects sensitive operations (file writes, shell commands, tool calls)
- The permission prompt appears in goose's interface (CLI or Desktop)
- Your allow/deny decision is sent back to Claude Code
- Claude Code proceeds or adapts based on your response
This integration uses the same mechanism as the official Claude Agent SDKs, ensuring compatibility and consistent behavior.
See [CLI Providers - Claude Code Configuration](/docs/guides/cli-providers#claude-code-configuration) for setup details.
documentation/docs/guides/managing-tools/hooks.md
-367
View File
@@ -1,367 +0,0 @@
---
title: Hooks
sidebar_position: 4
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 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 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'
}
]}
/>
documentation/docs/guides/managing-tools/index.md
+6 -10
View File
@@ -15,6 +15,11 @@ import styles from '@site/src/components/Card/styles.module.css';
<div className={styles.categorySection}>
<h2 className={styles.categoryTitle}>📚 Documentation & Guides</h2>
<div className={styles.cardGrid}>
<Card
title="goose Permissions"
description="Choose how much autonomy goose has when using tools, editing files, and taking action in a session."
link="/docs/guides/managing-tools/goose-permissions"
/>
<Card
title="Tool Permissions"
description="Configure fine-grained permissions to control which tools goose can use and when, ensuring secure and controlled automation."
@@ -25,11 +30,6 @@ import styles from '@site/src/components/Card/styles.module.css';
description="Customize how tool interactions are displayed, from detailed verbose output to clean concise summaries."
link="/docs/guides/managing-tools/adjust-tool-output"
/>
<Card
title="Hooks"
description="Run scripts when goose starts sessions, submits prompts, calls tools, edits files, or executes shell commands."
link="/docs/guides/managing-tools/hooks"
/>
<Card
title="Code Mode"
description="Programmatic approach that discovers and calls MCP tools on demand."
@@ -61,10 +61,6 @@ import styles from '@site/src/components/Card/styles.module.css';
description="Technical deep-dive into the challenges of tool calling with open-source models and the research behind toolshim solutions."
link="/blog/2025/04/11/finetuning-toolshim"
/>
<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>
documentation/docs/guides/managing-tools/tool-permissions.md
+1 -1
View File
@@ -28,7 +28,7 @@ goose performs best with fewer than 25 total tools enabled across all extensions
## Permission Levels
Tool permissions work alongside [goose permission modes](/docs/guides/goose-permissions). The mode sets the default behavior, while tool permissions let you override the behavior of specific tools.
Tool permissions work alongside [goose permission modes](/docs/guides/managing-tools/goose-permissions). The mode sets the default behavior, while tool permissions let you override the behavior of specific tools.
Each tool can be set to one of three permission levels: