Feature: Comprehensive Hooking System

[Edilmo]

Summary

The Gemini CLI Hooks v1 Feature introduces a first‑class hook system that lets developers intercept key lifecycle events in the Gemini agent loop. It mirrors the JSON‑over‑stdin contract, exit code semantics and matcher syntax used by Claude Code, aligns conceptually with Google’s ADK callbacks, and adds new events like BeforeModel and BeforeToolSelection for advanced prompt engineering and tool planning. The system supports two hook types: command hooks for running arbitrary scripts, and plugin hooks that load npm packages implementing a stable interface with dependency injection. Configuration can live at project, user, system and extension levels, with well‑defined precedence. Migration tooling converts existing Claude Code hooks into the new format, and dedicated CLI commands manage installation, reloading and execution of hooks.

Motivation

Today, customizing Gemini CLI behaviour requires editing core code or complex workarounds. There is no unified mechanism to inject dynamic context, enforce security guardrails, log interactions or optimise tool selection. Additionally, users with existing Claude Code scripts face friction when migrating their workflows, and there is no way to distribute reusable hook logic as npm packages. A robust hook system will:

• Allow users to augment prompts, filter or reorder tools, sanitise LLM responses and implement guardrails without modifying the core.
• Provide feature parity with Claude Code hooks so existing scripts run unmodified.
• Enable third‑party developers to share and reuse logic via npm packages with a well‑defined plugin interface.
• Lay the foundation for future integration with ADK callbacks and extension workflows.
• Increase confidence and visibility by offering observability, configuration precedence and safe‑mode execution.

Core Features

1. Event Framework & Contracts – Define a set of events (BeforeTool, AfterTool, BeforeAgent, Notification, AfterAgent, SessionStart/End, PreCompress, BeforeModel, AfterModel, BeforeToolSelection) with clear JSON input/output schemas. Support matchers (exact, regex, wildcard) and precedence across project, user, system and extension scopes.
2. Command & Plugin Hooks – Support two hook types:
   • Command hooks, which run shell commands and communicate via exit codes and stdin/stdout.
   • Plugin hooks, which discover and load npm packages labelled with geminicli-plugin, validate their declared API version and inject services (Logger, Config, HttpClient) into their hook methods. The design uses dependency injection to avoid global state and ensure loose coupling.
3. Advanced Events – Introduce BeforeModel to modify or replace the LLM request/response and BeforeToolSelection to adjust the candidate tool list before the planner runs, enabling sophisticated prompt augmentation and tool optimisation.
4. Configuration & Management – Merge hook definitions from .gemini/settings.json, user‑level and system‑level configs, and gemini-extension.json, with project settings overriding user and system settings. Provide commands like gemini hooks install <package>, gemini hooks uninstall, /hooks reload, /hooks enable, and gemini hooks migrate --from-claude to manage hooks and plugins.
5. Observability – Log every hook invocation with event name, hook type, duration and result and expose a /hooks panel listing active hooks.
6. Extension & Migration Support – Allow extensions to declare hooks that run after project/user/system hooks; publish TypeScript definitions for plugin interfaces; provide a migration command that reads .claudeconfigurations and converts them to .gemini format, converting environment variables like CLAUDE_PROJECT_DIR into GEMINI_PROJECT_DIR for compatibility.

[gemini-cli[bot]]

This issue is a feature request for a new hooking system, which falls under the extensibility area. As a new feature, it is assigned a medium priority.

[rickycambrian]

Hello, our team relies heavily on hooks, and in order to migrate our team's usage away from Claude Code in favor of gemini-cli this is a requirement for us. I made a PR that enables hooks in gemini-cli, with a utility to automatically migrate the .claude/hooks scripts to .gemini/hooks. @Edilmo if you had time to review and test this PR that would be fantastic: https://github.com/google-gemini/gemini-cli/pull/13656

I tested our implementation and hooks are working for me (see screenshot), but would need further validation. On the open PR we received some comments from gemini-code-assist which should now also be addressed. Please let me know if you have any comments or feedback 🙏

I have gone through several rounds of review with gemini-code-assist, it has pointed out some areas for improvements and have gone through a continued iteration cycle, but the feedback that gemini-code-assist has given seems really positive to me. I arrived at a snapshot which seemed very close to ready to me, but made a round of changes to make the hooks selection more persistent, and after that point there was more iteration (apologies for that becoming a really long thread), but I think we are close here. Curious about what we can do to unblock this feature, as this is a requirement for our team and I am sure others to make the switch.

Update: have done additional work and validation. Here is documentation to help figure out the correct usage: hooks.md I think things are ready for feedback from the team

[Edilmo]

Hello, our team relies heavily on hooks, and in order to migrate our team's usage away from Claude Code in favor of gemini-cli this is a requirement for us. I made a PR that enables hooks in gemini-cli, with a utility to automatically migrate the .claude/hooks scripts to .gemini/hooks. @Edilmo if you had time to review and test this PR that would be fantastic: #13656

I tested our implementation and hooks are working for me (see screenshot), but would need further validation. On the open PR we received some comments from gemini-code-assist which should now also be addressed. Please let me know if you have any comments or feedback 🙏

I have gone through several rounds of review with `gemini-code-assist`, it has pointed out some areas for improvements and have gone through a continued iteration cycle, but the feedback that `gemini-code-assist` has given seems really positive to me. I arrived at a [snapshot](https://github.com/google-gemini/gemini-cli/pull/13656/commits/79680b68594001043fc8fd66ec4216592941a28e) which seemed very close to ready to me, but made a round of changes to make the hooks selection more persistent, and after that point there was more iteration (apologies for that becoming a really long thread), but I think we are close here. Curious about what we can do to unblock this feature, as this is a requirement for our team and I am sure others to make the switch.

Update: have done additional work and validation. Here is documentation to help figure out the correct usage: hooks.md I think things are ready for feedback from the team

Hi @rickycambrian actually the implementation for this has been in PRs for quite some time (you can see the tasks were linked to small PRs). I designed and implemented months ago, the designed was approved, but given the impactful nature of the change, this require very careful review, so the work had to be broken in small pieces (+20 PRs), get carefully reviewed, by different members of the team, and then merge incrementally.

Just yesterday we finished integrating all the core and most of the hooks to be supported (including all the super important ones) are in place.

There is still work pending to be done (some in PRs and some are not). The work that is not in PR yet is related to "UX" which are dependent on some final discussions. The whole work should be done very soon (couple weeks).

If you would like to contirbute, please share your concrete hook needs and I can share with you if that is already supported such that you can help us with the testing. If your needs include something still not merge in main, we can discuss what is the best/fastest path forward.

I will also review your PR to see deltas as well.

Thanks for the contributions.

cc: @abhipatel12 @scidomino