Gemini CLI hooks

Hooks are scripts or programs that Gemini CLI executes at specific points in the agentic loop, allowing you to intercept and customize behavior without modifying the CLI’s source code.

What are hooks?

Hooks run synchronously as part of the agent loop—when a hook event fires, Gemini CLI waits for all matching hooks to complete before continuing.

With hooks, you can:

• Add context: Inject relevant information (like git history) before the model processes a request.
• Validate actions: Review tool arguments and block potentially dangerous operations.
• Enforce policies: Implement security scanners and compliance checks.
• Log interactions: Track tool usage and model responses for auditing.
• Optimize behavior: Dynamically filter available tools or adjust model parameters.

Getting started

• Writing hooks guide: A tutorial on creating your first hook with comprehensive examples.
• Best practices: Guidelines on security, performance, and debugging.
• Hooks reference: The definitive technical specification of I/O schemas and exit codes.

Core concepts

Hook events

Hooks are triggered by specific events in Gemini CLI’s lifecycle.

Event	When It Fires	Impact	Common Use Cases
SessionStart	When a session begins (startup, resume, clear)	Inject Context	Initialize resources, load context
SessionEnd	When a session ends (exit, clear)	Advisory	Clean up, save state
BeforeAgent	After user submits prompt, before planning	Block Turn / Context	Add context, validate prompts, block turns
AfterAgent	When agent loop ends	Retry / Halt	Review output, force retry or halt execution
BeforeModel	Before sending request to LLM	Block Turn / Mock	Modify prompts, swap models, mock responses
AfterModel	After receiving LLM response	Block Turn / Redact	Filter/redact responses, log interactions
BeforeToolSelection	Before LLM selects tools	Filter Tools	Filter available tools, optimize selection
BeforeTool	Before a tool executes	Block Tool / Rewrite	Validate arguments, block dangerous ops
AfterTool	After a tool executes	Block Result / Context	Process results, run tests, hide results
PreCompress	Before context compression	Advisory	Save state, notify user
Notification	When a system notification occurs	Advisory	Forward to desktop alerts, logging

Global mechanics

Understanding these core principles is essential for building robust hooks.

Strict JSON requirements (The “Golden Rule”)

Hooks communicate via stdin (Input) and stdout (Output).

1. Silence is Mandatory: Your script must not print any plain text to stdout other than the final JSON object. Even a single echo or print call before the JSON will break parsing.
2. Pollution = Failure: If stdout contains non-JSON text, parsing will fail. The CLI will default to “Allow” and treat the entire output as a systemMessage.
3. Debug via Stderr: Use stderr for all logging and debugging (for example, echo "debug" >&2). Gemini CLI captures stderr but never attempts to parse it as JSON.

Exit codes

Gemini CLI uses exit codes to determine the high-level outcome of a hook execution:

Exit Code	Label	Behavioral Impact
0	Success	The stdout is parsed as JSON. Preferred code for all logic, including intentional blocks (for example, {"decision": "deny"}).
2	System Block	Critical Block. The target action (tool, turn, or stop) is aborted. stderr is used as the rejection reason. High severity; used for security stops or script failures.
Other