Gemini CLI Setup

AgentKeeper integrates with Gemini CLI through command hooks. The Gemini adapter converts hook payloads into AgentKeeper's canonical Bash, Read, Write, Edit, Grep, Glob, WebFetch, and MCP skill...

AgentKeeper integrates with Gemini CLI through command hooks. The Gemini adapter converts hook payloads into AgentKeeper's canonical Bash, Read, Write, Edit, Grep, Glob, WebFetch, and MCP skill events.

Gemini's hook system supports tool, agent, model, notification, session, and tool-selection lifecycle events. AgentKeeper's default rollout claim is strongest for BeforeTool events: shell commands, file operations, web fetches, and MCP calls when Gemini emits them.

Use Policy outcomes for the shared Monitor, Warn, and Block model; this page lists what the Gemini CLI surface can actually support.

What gets monitored

Surface	Outcome support
Shell commands (`run_shell_command`)	Block or Warn before execution
File reads (`read_file`, `read_many_files`)	Block, Warn, or Audit only based on read-path policy
File writes and edits (`write_file`, `replace`)	Block or Warn before execution
Prompts	Preview; validate `BeforeAgent` payloads before using as a rollout control
MCP tool calls	Block, Warn, allow-list, or Audit only when Gemini emits MCP metadata
Web fetch/search	Can block when Gemini emits the tool event

Installation

Get your API key from Settings > Access > API keys, then run the public installer:

export AGENTKEEPER_API_URL="https://www.agentkeeper.dev"
export AGENTKEEPER_API_KEY="ak_live_..."
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide gemini

The installer stores the API key in ~/.agentkeeper/config, installs ~/.agentkeeper/hooks/gemini/agentkeeper-hook.sh, and updates ~/.gemini/settings.json. The generated command uses your expanded home directory path so Gemini can execute the hook without shell expansion.

Generated config

{
  "hooksConfig": {
    "enabled": true
  },
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "agentkeeper",
            "type": "command",
            "command": "/Users/YOU/.agentkeeper/hooks/gemini/agentkeeper-hook.sh",
            "timeout": 5000
          }
        ]
      }
    ],
    "AfterTool": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "agentkeeper",
            "type": "command",
            "command": "/Users/YOU/.agentkeeper/hooks/gemini/agentkeeper-hook.sh",
            "timeout": 5000
          }
        ]
      }
    ],
    "BeforeAgent": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "agentkeeper",
            "type": "command",
            "command": "/Users/YOU/.agentkeeper/hooks/gemini/agentkeeper-hook.sh",
            "timeout": 5000
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "agentkeeper",
            "type": "command",
            "command": "/Users/YOU/.agentkeeper/hooks/gemini/agentkeeper-hook.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Gemini uses process exit codes for enforcement. The adapter exits 0 to allow and 2 to block, with the block reason written to stderr.

Tool name mapping

Gemini CLI tool name	AgentKeeper canonical name
`run_shell_command`	`Bash`
`read_file`	`Read`
`read_many_files`	`Glob`
`write_file`	`Write`
`replace`, `edit`	`Edit`
`search_file_content`	`Grep`
`web_fetch`	`WebFetch`
`mcp__server__tool`	MCP skill policy

Verify coverage

Open the project with Gemini CLI after installing hooks.
Ask Gemini to run pwd.
Check Activity for a gemini event.
Go to Team → Policies → Access Control to disable or re-enable org-wide Gemini CLI access.
If you need prompt enforcement, test a known blocked prompt and confirm the BeforeAgent event includes enough prompt context in your Gemini CLI version.

Notes

The adapter is fail-open on errors and timeouts. If AgentKeeper is unavailable, Gemini continues normally; when the API is reachable, policy decisions are attributed to the gemini detection layer for filtering, alerts, and audit export. Workstations register on the first Gemini event that reaches AgentKeeper.

For cross-IDE claims, see IDE runtime parity.

Was this page helpful?