clone/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-02-01 22:48:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(hooks): clarify mandatory 'type' field and update hook schema documentation (#17499)

Browse Source
This commit is contained in:
Abhi
2026-01-25 18:33:12 -05:00
committed by GitHub
parent dcd949bdd0
commit cb772a5b7f
5 changed files with 77 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/extensions/index.md
View File

@@ -324,7 +324,7 @@ The `hooks.json` file contains a `hooks` object where keys are
```json
{
"hooks": {
"before_agent": [
"BeforeAgent": [
{
"hooks": [
{

2
docs/hooks/best-practices.md
View File

@@ -91,6 +91,7 @@ spawning a process for irrelevant events.
"hooks": [
{
"name": "validate-writes",
"type": "command",
"command": "./validate.sh"
}
]
@@ -584,6 +585,7 @@ defaults to 60 seconds, but you should set stricter limits for fast hooks.
"hooks": [
{
"name": "fast-validator",
"type": "command",
"command": "./hooks/validate.sh",
"timeout": 5000 // 5 seconds
}

20
docs/hooks/index.md
View File

@@ -104,9 +104,8 @@ You can filter which specific tools or triggers fire your hook using the
## Configuration
Hook definitions are configured in `settings.json`. Gemini CLI merges
configurations from multiple layers in the following order of precedence
(highest to lowest):
Hooks are configured in `settings.json`. Gemini CLI merges configurations from
multiple layers in the following order of precedence (highest to lowest):
1. **Project settings**: `.gemini/settings.json` in the current directory.
2. **User settings**: `~/.gemini/settings.json`.
@@ -126,8 +125,7 @@ configurations from multiple layers in the following order of precedence
"name": "security-check",
"type": "command",
"command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
"timeout": 5000,
"sequential": false
"timeout": 5000
}
]
}
@@ -136,6 +134,18 @@ configurations from multiple layers in the following order of precedence
}
```
#### Hook configuration fields
| Field | Type | Required | Description |
| :------------ | :----- | :-------- | :------------------------------------------------------------------- |
| `type` | string | **Yes** | The execution engine. Currently only `"command"` is supported. |
| `command` | string | **Yes\*** | The shell command to execute. (Required when `type` is `"command"`). |
| `name` | string | No | A friendly name for identifying the hook in logs and CLI commands. |
| `timeout` | number | No | Execution timeout in milliseconds (default: 60000). |
| `description` | string | No | A brief explanation of the hook's purpose. |
---
### Environment variables
Hooks are executed with a sanitized environment.

25
docs/hooks/reference.md
View File

@@ -18,6 +18,31 @@ including JSON schemas and API details.
---
## Configuration schema
Hooks are defined in `settings.json` within the `hooks` object. Each event
(e.g., `BeforeTool`) contains an array of **hook definitions**.
### Hook definition
| Field | Type | Required | Description |
| :----------- | :-------- | :------- | :-------------------------------------------------------------------------------------- |
| `matcher` | `string` | No | A regex (for tools) or exact string (for lifecycle) to filter when the hook runs. |
| `sequential` | `boolean` | No | If `true`, hooks in this group run one after another. If `false`, they run in parallel. |
| `hooks` | `array` | **Yes** | An array of **hook configurations**. |
### Hook configuration
| Field | Type | Required | Description |
| :------------ | :------- | :-------- | :------------------------------------------------------------------- |
| `type` | `string` | **Yes** | The execution engine. Currently only `"command"` is supported. |
| `command` | `string` | **Yes\*** | The shell command to execute. (Required when `type` is `"command"`). |
| `name` | `string` | No | A friendly name for identifying the hook in logs and CLI commands. |
| `timeout` | `number` | No | Execution timeout in milliseconds (default: 60000). |
| `description` | `string` | No | A brief explanation of the hook's purpose. |
---
## Base input schema
All hooks receive these common fields via `stdin`:

40
docs/hooks/writing-hooks.md
View File

@@ -194,6 +194,7 @@ main().catch((err) => {
"hooks": [
{
"name": "intent-filter",
"type": "command",
"command": "node .gemini/hooks/filter-tools.js"
}
]
@@ -234,7 +235,13 @@ security.
"SessionStart": [
{
"matcher": "startup",
"hooks": [{ "name": "init", "command": "node .gemini/hooks/init.js" }]
"hooks": [
{
"name": "init",
"type": "command",
"command": "node .gemini/hooks/init.js"
}
]
}
],
"BeforeAgent": [
@@ -243,6 +250,7 @@ security.
"hooks": [
{
"name": "memory",
"type": "command",
"command": "node .gemini/hooks/inject-memories.js"
}
]
@@ -252,7 +260,11 @@ security.
{
"matcher": "*",
"hooks": [
{ "name": "filter", "command": "node .gemini/hooks/rag-filter.js" }
{
"name": "filter",
"type": "command",
"command": "node .gemini/hooks/rag-filter.js"
}
]
}
],
@@ -260,7 +272,11 @@ security.
{
"matcher": "write_file",
"hooks": [
{ "name": "security", "command": "node .gemini/hooks/security.js" }
{
"name": "security",
"type": "command",
"command": "node .gemini/hooks/security.js"
}
]
}
],
@@ -268,7 +284,11 @@ security.
{
"matcher": "*",
"hooks": [
{ "name": "record", "command": "node .gemini/hooks/record.js" }
{
"name": "record",
"type": "command",
"command": "node .gemini/hooks/record.js"
}
]
}
],
@@ -276,7 +296,11 @@ security.
{
"matcher": "*",
"hooks": [
{ "name": "validate", "command": "node .gemini/hooks/validate.js" }
{
"name": "validate",
"type": "command",
"command": "node .gemini/hooks/validate.js"
}
]
}
],
@@ -284,7 +308,11 @@ security.
{
"matcher": "exit",
"hooks": [
{ "name": "save", "command": "node .gemini/hooks/consolidate.js" }
{
"name": "save",
"type": "command",
"command": "node .gemini/hooks/consolidate.js"
}
]
}
]