Skip to content
AgentAtlas

Gemini CLI hooks: settings.json, BeforeTool, AfterTool, exit codes and /hooks

How do I set up hooks in Gemini CLI?

Add a hooks object to .gemini/settings.json (project) or ~/.gemini/settings.json (user). Each event, such as BeforeTool or AfterTool, holds a list of groups with a matcher and a hooks array of command hooks. A hook gets JSON on stdin and replies with JSON on stdout. Exit 0 with a deny decision, or exit 2 with a reason on stderr, blocks the action. Use /hooks panel to see what is loaded.

Compare: hooks in every AI coding agent →

Where hooks are configured

Gemini CLI reads hooks from these places, highest precedence first:

  • Project: .gemini/settings.json in the current directory.
  • User: ~/.gemini/settings.json.
  • System: /etc/gemini-cli/settings.json.
  • Extensions: hooks that installed extensions define.

Example: check every file write

.gemini/settings.json

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}
  • type: required. Only "command" is supported today.
  • command: the shell command to run.
  • name: optional. Used in logs and by /hooks enable and /hooks disable.
  • timeout: optional, in milliseconds. The default is 60000 (60 seconds).
  • A group can set "sequential" to run its hooks one after another instead of in parallel.

Hook events

  • SessionStart and SessionEnd
  • BeforeAgent and AfterAgent
  • BeforeModel and AfterModel
  • BeforeToolSelection
  • BeforeTool and AfterTool
  • PreCompress
  • Notification

How matchers work

  • BeforeTool and AfterTool: the matcher is a regex tested against the tool name, such as "write_.*".
  • Lifecycle events: the matcher is an exact string, such as "startup".
  • "*" or an empty string matches everything.
  • Built-in tools use names like read_file and run_shell_command. MCP tools are named mcp_<server_name>_<tool_name>.

Input, output and exit codes

Every hook gets JSON on stdin with session_id, transcript_path, cwd, hook_event_name and timestamp, plus fields for its event. Stdout must contain only the final JSON object. If that JSON is invalid, Gemini CLI defaults to allow.

  • Exit 0: success. Stdout is parsed as JSON. The docs prefer this for all logic, including intentional blocks.
  • Exit 2: system block. The action is aborted and stderr is the reason.
  • Any other code: a non-fatal warning. The action goes ahead with the original parameters.
  • decision: "allow" or "deny" ("block" also works), with reason as the feedback when you deny.
  • continue: false stops the agent loop. stopReason is shown to the user.
  • systemMessage: a message shown to the user.
  • hookSpecificOutput: event fields such as additionalContext or a rewritten tool_input for BeforeTool.

Manage hooks with /hooks

  • /hooks panel shows the configured hooks.
  • /hooks enable-all and /hooks disable-all toggle every hook.
  • /hooks enable <name> and /hooks disable <name> toggle one hook.

Gemini CLI fingerprints project hooks. If a hook's name or command changes, for example after a git pull, it is treated as a new, untrusted hook and you are warned before it runs.

Sources

More Gemini CLI guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →