Native Gemini CLI hooks for phone approvals, policy enforcement, and session tracking with Pushary

Complete the Quickstart first to create your account and get your API key.

Pushary connects to Gemini CLI through MCP and native Gemini hooks. The MCP server gives Gemini the push notification tools. The hooks run Pushary's policy engine on Gemini tool calls: phone approvals, always-deny rules, the kill switch, task titles, and session tracking.

Setup wizard

npx @pushary/agent-hooks setup

Select "Gemini CLI". The wizard will:

Install @pushary/agent-hooks globally
Add the Pushary MCP server to ~/.gemini/settings.json (with trust: true so Pushary's own tools run without a confirmation prompt)
Write five hook entries to the same file
Save your API key

Restart Gemini CLI so it loads the new config. Unlike Codex, Gemini does not make you trust a hook before it runs, so phone approvals work as soon as you restart.

What each hook does

Event	What happens
`BeforeTool`	The approval gate. Runs before `run_shell_command`, `write_file`, and `replace`. The kill switch and always-deny policies block here; push policies send the question to your phone and run the tool only if you approve.
`AfterTool`	Records `tool_complete` or `tool_error` events with receipts, and clears any pending phone questions.
`BeforeAgent`	Captures your prompt as the session's task title on the Fleet Board. Set `PUSHARY_TASK_TITLES=off` to disable.
`SessionStart`	Registers the session on the Fleet Board from the first second.
`SessionEnd`	Marks the session idle and cancels pending phone questions.

What the gate covers

Gemini's built-in tools have different names from Claude Code, so Pushary maps them onto your existing policies:

Gemini tool	Pushary policy
`run_shell_command`	`Bash`
`write_file`	`Write`
`replace`	`Edit`

One policy works across every agent. A rule you set for Bash also gates run_shell_command.

Capability parity with Claude Code

Capability	Claude Code	Gemini CLI
Phone approvals from the lock screen	Yes	Yes, via `BeforeTool`
Policy enforcement (always-deny, auto-approve, argument patterns)	Yes	Yes, via `BeforeTool`
Kill switch	Yes	Yes, stops the next gated tool call
Task titles	Yes	Yes
Parallel session tracking	Yes	Yes
Activity receipts (`tool_complete` / `tool_error`)	Yes	Yes
Shell, write, and edit gating	Yes	Yes
Continue a run from a phone-queued command	Yes	No. Gemini's `SessionEnd` cannot re-inject a prompt

Manual setup

If you prefer not to use the wizard, edit ~/.gemini/settings.json directly.

MCP server

Install the hooks package globally so the hook command exists:

npm install -g @pushary/agent-hooks

Add the server. Replace the token with your API key:

{
  "mcpServers": {
    "pushary": {
      "httpUrl": "https://pushary.com/api/mcp/mcp",
      "headers": { "Authorization": "Bearer pk_xxx.xxx" },
      "trust": true
    }
  }
}

Hooks

Add the entries under the same top-level object. Replace the command with the output of which pushary-gemini-hook and use the same path in every entry. Timeouts are in milliseconds.

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "run_shell_command|write_file|replace",
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 180000 }
        ]
      }
    ],
    "AfterTool": [
      {
        "matcher": "run_shell_command|write_file|replace",
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 10000 }
        ]
      }
    ],
    "BeforeAgent": [
      {
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 10000 }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 10000 }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 10000 }
        ]
      }
    ]
  }
}

Set your API key in your shell profile so the hook can read it:

export PUSHARY_API_KEY="pk_xxx.xxx"

Restart Gemini CLI.

MCP tools

Once connected, Gemini can use these tools:

Tool	Description
`send_notification`	Send a push with optional rich context
`ask_user`	Ask a question: yes/no, multiple choice, or free text
`wait_for_answer`	Poll for your response
`cancel_question`	Cancel a pending question

Verify

Run the doctor to confirm the MCP server, the hooks, and notification delivery:

npx @pushary/agent-hooks doctor

Complete the Quickstart first to create your account and get your API key.

Setup wizard

npx @pushary/agent-hooks setup

Select "Gemini CLI". The wizard will:

Install @pushary/agent-hooks globally
Add the Pushary MCP server to ~/.gemini/settings.json (with trust: true so Pushary's own tools run without a confirmation prompt)
Write five hook entries to the same file
Save your API key

Restart Gemini CLI so it loads the new config. Unlike Codex, Gemini does not make you trust a hook before it runs, so phone approvals work as soon as you restart.

What each hook does

Event	What happens
`BeforeTool`	The approval gate. Runs before `run_shell_command`, `write_file`, and `replace`. The kill switch and always-deny policies block here; push policies send the question to your phone and run the tool only if you approve.
`AfterTool`	Records `tool_complete` or `tool_error` events with receipts, and clears any pending phone questions.
`BeforeAgent`	Captures your prompt as the session's task title on the Fleet Board. Set `PUSHARY_TASK_TITLES=off` to disable.
`SessionStart`	Registers the session on the Fleet Board from the first second.
`SessionEnd`	Marks the session idle and cancels pending phone questions.

What the gate covers

Gemini's built-in tools have different names from Claude Code, so Pushary maps them onto your existing policies:

Gemini tool	Pushary policy
`run_shell_command`	`Bash`
`write_file`	`Write`
`replace`	`Edit`

One policy works across every agent. A rule you set for Bash also gates run_shell_command.

Capability parity with Claude Code

Capability	Claude Code	Gemini CLI
Phone approvals from the lock screen	Yes	Yes, via `BeforeTool`
Policy enforcement (always-deny, auto-approve, argument patterns)	Yes	Yes, via `BeforeTool`
Kill switch	Yes	Yes, stops the next gated tool call
Task titles	Yes	Yes
Parallel session tracking	Yes	Yes
Activity receipts (`tool_complete` / `tool_error`)	Yes	Yes
Shell, write, and edit gating	Yes	Yes
Continue a run from a phone-queued command	Yes	No. Gemini's `SessionEnd` cannot re-inject a prompt

Manual setup

If you prefer not to use the wizard, edit ~/.gemini/settings.json directly.

MCP server

Install the hooks package globally so the hook command exists:

npm install -g @pushary/agent-hooks

Add the server. Replace the token with your API key:

{
  "mcpServers": {
    "pushary": {
      "httpUrl": "https://pushary.com/api/mcp/mcp",
      "headers": { "Authorization": "Bearer pk_xxx.xxx" },
      "trust": true
    }
  }
}

Hooks

Add the entries under the same top-level object. Replace the command with the output of which pushary-gemini-hook and use the same path in every entry. Timeouts are in milliseconds.

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "run_shell_command|write_file|replace",
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 180000 }
        ]
      }
    ],
    "AfterTool": [
      {
        "matcher": "run_shell_command|write_file|replace",
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 10000 }
        ]
      }
    ],
    "BeforeAgent": [
      {
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 10000 }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 10000 }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          { "name": "pushary", "type": "command", "command": "/path/to/pushary-gemini-hook", "timeout": 10000 }
        ]
      }
    ]
  }
}

Set your API key in your shell profile so the hook can read it:

export PUSHARY_API_KEY="pk_xxx.xxx"

Restart Gemini CLI.

MCP tools

Once connected, Gemini can use these tools:

Tool	Description
`send_notification`	Send a push with optional rich context
`ask_user`	Ask a question: yes/no, multiple choice, or free text
`wait_for_answer`	Poll for your response
`cancel_question`	Cancel a pending question

Verify

Run the doctor to confirm the MCP server, the hooks, and notification delivery:

npx @pushary/agent-hooks doctor

Gemini CLI Setup

Setup wizard

What each hook does

What the gate covers

Capability parity with Claude Code

Manual setup

MCP server

Hooks

MCP tools

Verify

On this page

Gemini CLI Setup

Setup wizard

What each hook does

What the gate covers

Capability parity with Claude Code

Manual setup

MCP server

Hooks

MCP tools

Verify

On this page