@pmatrix/gemini-cli-monitor

Runtime safety governance for Gemini CLI — 11-hook observability + tool-level enforcement.

Analyzes tool calls before execution, detects credential leaks in prompts, and continuously measures agent risk with live Trust Grade (A–E).

Requires a P-MATRIX account and API key.

What it does

Core Protection

• Safety Gate (BeforeTool) — Tool call analysis before execution. Blocks based on current risk level R(t) and instant-block rules (rm -rf, sudo rm, curl|sh, base64|sh).
• Credential Protection (BeforeAgent) — Detects and blocks 16 types of API keys and secrets before they reach the agent.
• Kill Switch — Automatically halts when R(t) ≥ 0.75. Manually via pmatrix_halt MCP tool. Creates ~/.pmatrix/HALT to block all sessions.

Behavioral Intelligence

• 11 Gemini CLI hooks → 4-axis signal mapping (BASELINE / NORM / STABILITY / META_CONTROL)
• BeforeModel — LLM parameter inspection (temperature, toolConfig mode): META_CONTROL signal
• AfterModel — Token usage + safety ratings observation: STABILITY signal
• BeforeToolSelection — Tool config mode observation (Gemini CLI exclusive hook)
• PreCompress — Context compression frequency → STABILITY nudge (+0.03)
• Notification — Policy DENY observation → NORM compensation path

Requirements

| Requirement | Version | |-------------|---------| | Node.js | >= 18 | | Gemini CLI | 0.26.0+ | | P-MATRIX server | v1.0.0+ |

Installation

npm (advanced users / CI)

npm install -g @pmatrix/gemini-cli-monitor

# Get your API key at app.pmatrix.io → Settings → API Keys
pmatrix-gemini setup --api-key <YOUR_API_KEY>

Follow the printed instructions to add the hooks and MCP config to ~/.gemini/settings.json, then restart Gemini CLI.

Extension Gallery (recommended)

gemini extensions install github.com/p-matrix/gemini-cli-monitor

Trust Setup

Gemini CLI only runs hooks in trusted folders. Before hooks will execute, you must trust the folder:

1. Run gemini in your project folder
2. Accept the trust prompt when asked
3. Verify trust status: pmatrix-gemini setup

Privacy

Content-Agnostic: P-MATRIX never collects, parses, or stores your prompts, LLM responses, tool results, or file contents.

• BeforeAgent — credential scanning runs locally; only detection counts are sent (never prompt content)
• BeforeTool — sends tool_name and risk classification only (never tool arguments)
• AfterTool — sends response_key_count only (never tool result content)
• BeforeModel — sends temperature, toolConfig.mode, allowedFunctionNames.length only (never messages)
• AfterModel — sends finishReason, safetyRatings, usageMetadata only (never response text)

Hooks Registered (11)

| Hook | Type | Purpose | |------|------|---------| | SessionStart | Observation | Session lifecycle, baseline signal | | SessionEnd | Observation | Session lifecycle | | BeforeAgent | Blocking | Credential scan | | BeforeTool | Blocking | Safety Gate | | AfterTool | Observation | Tool result metadata | | BeforeModel | Observation | LLM parameter inspection | | AfterModel | Observation | Token usage + safety ratings | | AfterAgent | Observation | Agent response metadata | | BeforeToolSelection | Observation | Tool config mode | | PreCompress | Observation | Context compression tracking | | Notification | Observation | Policy DENY compensation path |

Safety Gate Matrix

| Risk Level | Mode | HIGH-risk | MEDIUM-risk | LOW-risk | |-----------|------|-----------|-------------|----------| | < 0.15 | Normal | Allow | Allow | Allow | | 0.15–0.30 | Caution | Block | Allow | Allow | | 0.30–0.50 | Alert | Block | Allow | Allow | | 0.50–0.75 | Critical | Block | Block | Allow | | >= 0.75 | Halt | Block | Block | Block |

Instant block rules (regardless of R(t)):

• sudo rm / sudo mkfs / sudo dd — privilege escalation + destructive
• rm -rf <non-tmp path> — destructive deletion
• curl ... | sh — remote code execution
• base64 --decode ... | sh — obfuscated RCE
• write_file to system paths (/etc/, /sys/, /boot/, etc.) — HIGH risk

MCP Tools

| Tool | Description | |------|-------------| | pmatrix_status | Show current Grade, R(t), mode, and session counters | | pmatrix_grade | Show behavioral grade and recent history | | pmatrix_halt | Manually trigger Kill Switch |

To resume from halt: rm ~/.pmatrix/HALT

Known Limitations (v0.2.0)

| Issue | Cause | Status | |-------|-------|--------| | BeforeToolSelection filtering disabled | Over-intervention risk (D-7) | Observation only in v1.0 | | pmatrix_* MCP tools are self-exempt | By design | Early allow prevents recursion | | Policy Engine pre-execution gap | Gemini CLI calls Policy Engine after hooks | KNOWN_LIMITATION — hooks block first, Policy Engine may override | | enter_plan_mode / exit_plan_mode classified LOW | Read-only plan tools (v0.29.0+) | By design |

Advanced Configuration

Edit ~/.pmatrix/config.json:

{
  "serverUrl": "https://api.pmatrix.io",
  "agentId": "gem_YOUR_AGENT_ID",
  "apiKey": "pm_live_xxxxxxxxxxxx",
  "safetyGate": { "enabled": true, "serverTimeoutMs": 2500 },
  "credentialProtection": { "enabled": true },
  "killSwitch": { "autoHaltOnRt": 0.75 },
  "dataSharing": false,
  "debug": false
}

Offline / Server-Down Behavior

• No cache: R(t) = 0.0 (fail-open)
• Cache + server down: Last known R(t) maintained
• Server timeout (> 2,500 ms): Fail-open — tool call allowed
• ~/.pmatrix/HALT exists: All tool calls blocked regardless of server state

Dashboard

Production server: https://api.pmatrix.io Dashboard: https://app.pmatrix.io

• Story tab — R(t) trajectory timeline, mode transitions, tool block events
• Analytics tab — Grade history, stability trends
• Logs tab — Live session events, audit trail

4.0 Field Integration (v0.2.0+)

When connected to a P-MATRIX Field, the monitor participates in the 4.0 Protocol with IPC-based degraded SV (neutral 0.5 axes):

• State Vector Exchange — Sends behavioral measurements to Field peers
• pmatrix_field_status MCP tool — Query Field connection status

Activation: Set both environment variables:

| Variable | Description | |----------|-------------| | PMATRIX_FIELD_ID | Field identifier | | PMATRIX_FIELD_NODE_ID | Node identifier |

When not set, the monitor runs in standalone 3.5 mode (default).

License

Apache-2.0 © 2026 P-MATRIX