Gemini CLI Hooks: Automating the Agentic Loop

The “Context Switch” Tax

Most developers treat AI as a smart chatbot. You have a bug, so you:

1. Switch window to Jira/Linear.
2. Copy the reproduction steps.
3. Switch window to Terminal/IDE.
4. Paste the context: “Fix this bug: [Paste]”.

This manual context transfer is the bottleneck. It turns you into a data router. The Gemini CLI Hooks API automates this by letting you script the inputs and outputs of the agent’s cognition loop.

The Hook Lifecycle

Hooks are simple scripts (Shell, Python, JS) that trigger on specific events in the agent’s lifecycle. You define them in web/hooks.json.

Here are the supported events:

1. BeforeSession: Runs once at startup.
   • Usage: Check for API keys, load environment variables, or pull the latest git changes.
2. BeforeModel (Context Injection): Runs before your message reaches the LLM.
   • Usage: Silently append file contents, database schemas, or issue tracker details to the system prompt.
3. AfterModel: Runs after the LLM generates a response but before it’s shown.
   • Usage: Log token usage modally or audit the raw response.
4. BeforeTool (Guardrails): Runs before the agent executes a command or tool.
   • Usage: Block rm -rf, prevent network calls to blacklisted IPs, or require human approval for prod deployments.
5. AfterTool (Verification): Runs after a tool execution completes.
   • Usage: Run a linter on written code. If it fails, feed the error back to the model automatically so it fixes its own mess.

5 High-Impact Use Cases

We used these hooks to move from “Chatting with AI” to “Agentic Workflows”.

1. The “Ticket Resolver” (Context)

When you type Fix PROJ-123, a hook triggers. It fetches the ticket summary and acceptance criteria from Jira or Linear and injects them directly into the model’s context. You never have to copy-paste a bug report again.

2. The “Schema Injector” (Context)

Queries mentioning “SQL”, “database”, or specific model names trigger a hook that reads your schema.prisma or structure.sql. The model receives the exact database definition system-side, preventing it from hallucinating non-existent columns.

3. The “Dependency Sentinel” (Security)

A BeforeTool hook intercepts npm install or pip install commands. It checks the requested package against an allowed list or queries a vulnerability database. If the package is unverified or has known CVEs, the hook blocks the execution before any network call is made.

4. The “Log Tail” (Debugging)

When you ask the agent to “debug the error”, a hook executes tail -n 100 app.log or checks the latest CI failure output. The model starts the turn with the stack trace already in memory, ready to propose a fix immediately.

5. The “Linter Guard” (Quality)

A hook runs before the model commits a file write. It validates the code block against your project’s eslint or prettier config. If the code ignores your style guide, the hook appends the linter errors to the system prompt, forcing the model to self-correct before you even see the output.

From Chat to Workflow

With Hooks, the CLI becomes a true Agentic Workflow Engine.

• On Init: Run ls -R to give the agent a file map.
• On Error: Automatically feed the stderr back to the model for a fix.
• On Commit: Generate a conventionally formatted commit message based on the staged changes.

Stop chatting. Start scripting the interaction.