New Gemini CLI hooks (v0.26.0+) let you tailor the agentic loop. Add context, enforce policies, and block secrets with custom scripts that run at predefined points in your workflow.
Overview
This article introduces Gemini CLI hooks, a customization mechanism that lets developers control and extend the agentic loop of Gemini CLI without modifying its source code. Hooks act as middleware scripts that execute at predefined lifecycle points, enabling context injection, action validation, policy enforcement, logging optimization, and notifications. The article demonstrates a practical secret-scanning hook example and covers best practices for performance and security.
What You'll Learn
1
How to configure Gemini CLI hooks to customize the agentic loop at predefined lifecycle points
2
How to build an automated secret-scanning hook that blocks sensitive data from being written to your codebase
3
How to use matchers to selectively trigger hooks only for specific tool operations like file writes
4
When to use BeforeTool vs AfterAgent hook events for different customization scenarios
5
How to distribute hooks via Gemini CLI extensions for team-wide adoption
Prerequisites & Requirements
- Gemini CLI v0.26.0 or later installed via npm
- Familiarity with command-line interfaces and shell scripting (Bash)
- jq command-line JSON processor for parsing hook input
- Understanding of JSON configuration files and regex pattern matching
Key Questions Answered
What are Gemini CLI hooks and how do they work?
Gemini CLI hooks are scripts or programs that execute at specific, predefined points in the CLI's lifecycle, acting as middleware for the AI assistant. They run synchronously within the agent loop, meaning the CLI waits for the hook to complete before continuing. Hooks are configured in .gemini/settings.json and can add context, validate actions, enforce policies, log usage, and send notifications.
How do I create an automated secret scanning hook for Gemini CLI?
Create a Bash script at .gemini/hooks/block-secrets.sh that reads hook input from stdin, extracts file content using jq, and checks for secret patterns like api_key, password, secret, or AWS key patterns using grep. If a match is found, return a JSON object with decision: deny and a reason. Configure it in .gemini/settings.json under hooks.BeforeTool with a matcher for write_file|replace operations.
What hook events are available in Gemini CLI?
The article specifically demonstrates BeforeTool hooks (which run before tool execution, useful for validating and blocking operations) and AfterAgent hooks (which intercept the agent's completion signal, used by the Ralph extension for continuous iteration loops). The full list of hook event types is available in the official Gemini CLI documentation at geminicli.com.
How do matchers work in Gemini CLI hook configuration?
Matchers are regex-like patterns in the hook configuration that filter which tool operations trigger a hook. For example, setting matcher to write_file|replace ensures the hook only runs when Gemini CLI attempts to write or replace file content, rather than executing on every single tool call. This improves performance by limiting hook execution to relevant events only.
Can Gemini CLI hooks be distributed as extensions?
Yes, Gemini CLI extensions now have full support for bundling hooks. Extension authors can include hooks directly within their extension packages, allowing users to install them with a single command without manual configuration. Examples include the Ralph extension, which uses an AfterAgent hook to implement a continuous iterative loop for persistent task completion.
What is the Ralph loop technique in Gemini CLI?
The Ralph loop is a technique implemented as a Gemini CLI extension that leverages an AfterAgent hook to intercept the agent's completion signal and force it into a continuous, iterative loop. This transforms Gemini CLI from a reactive assistant into an autonomous worker that automatically refreshes its context between attempts, preventing context rot during long sessions and persisting until the task is complete.
What are the best practices for writing performant Gemini CLI hooks?
Keep hooks fast since they run synchronously and any delay blocks the agent's response — use parallel operations and caching for expensive tasks. Use specific matchers like write_file|replace instead of running hooks on every tool call. Always review the source of project-level hooks before enabling them since they execute with your user privileges. Use the /hooks command to inspect all hooks and their status.
Technologies & Tools
AI Developer Tool
Gemini CLI
The primary CLI tool being extended with the hooks system
Scripting Language
Bash
Used for writing hook scripts that validate and process tool operations
CLI Tool
Jq
Used within hook scripts to parse and extract fields from JSON input
Data Format
JSON
Configuration format for hooks in .gemini/settings.json and hook input/output communication
Package Manager
Npm
Used to install and update Gemini CLI globally
Key Actionable Insights
1Implement a BeforeTool secret-scanning hook to prevent AI-generated code from accidentally committing API keys, passwords, or other credentials to your codebase. This creates an automated security safety net that intercepts file write and replace operations before they execute.This is especially valuable in team environments where multiple developers use Gemini CLI, as the hook enforces security policies automatically without relying on individual developer vigilance.
2Use the matcher property in hook configuration to limit hook execution to only relevant tool operations rather than running on every tool call. For example, a secret scanner should only match write_file|replace, not read operations or shell commands.Since hooks run synchronously and block the agent loop, overly broad matchers will significantly slow down the CLI's response time across all operations.
3Structure hook deny responses with both a decision field and a systemMessage field to give the agent clear feedback about why an operation was blocked. This enables the agent to self-correct and attempt alternative approaches rather than failing silently.The JSON response format with decision, reason, and systemMessage fields allows the agent to understand the denial and adjust its behavior in subsequent attempts.
4Consider packaging reusable hooks as Gemini CLI extensions for easy distribution across your team or organization. Extension-bundled hooks can be installed with a single command and require no manual configuration.This is particularly useful for organization-wide security policies, compliance requirements, or standardized development workflows that should be consistently applied across all team members.
5Leverage AfterAgent hooks for implementing iterative development workflows where the agent continuously works on difficult tasks while automatically refreshing its context between attempts, preventing the context rot common in long sessions.The Ralph extension demonstrates this pattern, transforming Gemini CLI from a single-response assistant into a persistent autonomous worker suitable for complex multi-step tasks.
Common Pitfalls
1
Running hooks on every tool call without using specific matchers. Since hooks execute synchronously and block the agent loop, an overly broad hook configuration will cause noticeable delays on every operation, degrading the interactive experience significantly.
Always use the matcher property to scope hooks to relevant tool operations. For example, a secret scanner only needs to match write_file|replace, not every tool invocation.
2
Enabling project-level hooks without reviewing their source code first. Hooks execute with your user privileges, so a malicious or poorly written hook in a cloned repository could execute arbitrary commands with your permissions.
Always inspect .gemini/hooks/ scripts and .gemini/settings.json before running Gemini CLI in a new project. Treat project hooks with the same caution as any executable code from untrusted sources.
3
Writing slow or blocking hook scripts that perform expensive operations like network calls or large file scans without caching or parallelization. Because hooks run synchronously, any delay directly blocks the agent's response cycle.
Use parallel operations, caching, and efficient pattern matching to keep hook execution time minimal. Consider pre-computing expensive results and caching them for subsequent hook invocations.
Related Concepts
Gemini CLI Extensions
Agentic Loop Customization
CI/CD Security Scanning
Git Pre-commit Hooks
Middleware Patterns
Secret Detection And Credential Scanning
Context Window Management
AI Agent Automation Loops