フックでGemini CLIをあなたのワークフローに合わせる

Tailor Gemini CLI to your workflow with hooks

Tailor Gemini CLI to your workflow with hooks

Efficiency in the age of agents isn't just about writing code faster; it's about building custom tools that adapt to your specific environment. Whether you need to inject custom project context, enforce strict security policies, or automate testing workflows, a one-size-fits-all agent often falls short.

That’s why we’re introducing Gemini CLI hooks, a powerful new way to control and customize the agentic loop, allowing you to tailor the behavior of Gemini CLI without ever having to touch its source code.

Sorry, your browser doesn't support playback for this video

Hooks are scripts or programs that Gemini CLI executes at specific, predefined points in its lifecycle. Think of them as "middleware" for your AI assistant. With hooks you can easily add custom logic that runs synchronously within the agent loop, giving you the ability to:

Add context: Inject relevant information (like recent git commits, Jira tickets, or local documentation) before the model processes a request.

Validate actions: Review and block potentially dangerous operations before they are executed. Continue iterating until specific requirements are met, improving model performance.

Enforce policies: Implement organization-wide security and compliance requirements automatically.

Log and optimize: Track tool usage and dynamically adjust tool selection to improve model accuracy and reduce token costs.

Notifications: Get updates when Gemini CLI is idle, awaiting input or requires a tool confirmation.

By configuring hooks, you can customize Gemini CLI to your specific project. When an event fires, the CLI waits for your hook to complete before continuing, ensuring your custom logic is always respected. This opens the door for you to build on top of Gemini CLI in any way you see fit.

A compelling example: Automated secret scanning

One of the most practical uses for hooks is creating a security safety net. With a BeforeTool hook, you can prevent the AI from accidentally writing sensitive data, like API keys or passwords, into your codebase.

To see all the available hook event types in Gemini CLI, reference the official documentation.

The hook script (.gemini/hooks/block-secrets.sh):

#!/usr/bin/env bash # Read hook input from stdin input=$(cat) # Extract content being written using jq content=$(echo "$input" | jq -r &#x27;.tool_input.content // .tool_input.new_string // ""&#x27;) # Check for common secret patterns if echo "$content" | grep -qE &#x27;api[_-]?key|password|secret|AKIA[0-9A-Z]{16}&#x27;; then # Return structured denial to the agent cat <<EOF { "decision": "deny", "reason": "Security Policy: Potential secret detected in content.", "systemMessage": "Security scanner blocked operation" } EOF exit 0 fi # Allow the operation echo &#x27;{"decision": "allow"}&#x27; exit 0 Shell Copied The configuration (.gemini/settings.json):

{ "hooks": { "BeforeTool": [ { "matcher": "write_file|replace", "hooks": [ { "name": "secret-scanner", "type": "command", "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/block-secrets.sh", "description": "Prevent committing secrets" } ] } ] } } JSON Copied Now, whenever Gemini attempts to write or edit a file, the hooks script validates the content first. If a secret is detected, the operation is blocked, and the agent receives a clear explanation of why it was denied, allowing it to self-correct.

To ensure your hooks enhance your workflow without slowing you down, we recommend following a few key guidelines:

Keep hooks fast: Because they run synchronously, any delay in your script will delay the agent’s response; use parallel operations and caching for expensive tasks.

Use specific matchers: Instead of running a hook for every single tool, use the matcher property (e.g., "matcher": "write_file|replace") to limit execution to relevant events.

Security first: Hooks execute with your user privileges, so always review the source of project-level hooks before enabling them.

Leverage the tooling: Use the /hooks command to show all hooks and their status.

The power of hooks isn&#x27;t limited to your local configuration. Gemini CLI extensions now come with full support for hooks. Extension authors can bundle hooks directly within their extension, allowing users to install them with a single command and no manual configuration. See the extensions documentation on hooks to learn more on how to add hooks to your extension.

Hooks support brings a new wave of what is possible with Gemini CLI extensions. One example being the Ralph extension, which implements the viral "Ralph loop” technique. By leveraging an AfterAgent hook, the extension intercepts the agent&#x27;s completion signal and forces it into a continuous, iterative loop.

This allows Gemini CLI to persistently continue away at difficult tasks while automatically refreshing its context between attempts to prevent the context rot that often plagues lo